Serialize managed Decky changes across desktop and headset

Prepare Frame Control 0.4.32 (#228 )
Co-authored-by: SAPHID <saphid@users.noreply.github.com>
2026-10-25 14:01:36 +01:00 · 2026-10-25 09:17:56 +00:00 · 2026-10-25 08:06:51 +00:00 · 2026-10-25 07:56:38 +00:00 · 2026-10-25 07:46:32 +00:00 · 2026-10-25 07:38:25 +00:00
181 changed files with 13325 additions and 278 deletions
@@ -41,8 +41,12 @@ jobs:
          python -m py_compile $(find frame/devkit-utils -type f ! -name '*.*' ! -name LICENSE) frame/devkit-utils/devkit_utils/*.py
      - name: Server tests
        run: python -m unittest discover -s tests -v
+      - name: Linux Wireless Adapter doctor (read-only PC smoke)
+        run: |
+          python ui/frame_wireless_doctor.py --json > "$RUNNER_TEMP/linux-wireless-doctor.json"
+          python -c 'import json, os; from pathlib import Path; d=json.loads((Path(os.environ["RUNNER_TEMP"]) / "linux-wireless-doctor.json").read_text()); assert d["supported"] and d["selected"] is None and d["schema"] == 1'
      - name: App syntax
-        run: node --check app/main.js && node --check app/build/make-icon.js && node --check app/build/fetch-deps.js && node --check app/preload.js && node --check app/install-link.js && node --check app/updater.js
+        run: node --check app/main.js && node --check app/obs-source.js && node --check app/build/make-icon.js && node --check app/build/fetch-deps.js && node --check app/preload.js && node --check app/install-link.js && node --check app/updater.js
      - name: App tests
        run: node --test app/test/*.test.js
      - name: Website
@@ -67,9 +71,29 @@ jobs:
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+      - name: OBS lifecycle tests
+        run: node app/test/obs-source.test.js
      - name: Server tests
        run: python -m unittest discover -s tests -v

+  # Fast, PC-only Windows query validation, without capture libraries or a headset.
+  wireless-windows:
+    runs-on: windows-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+      - name: Wireless doctor fixtures, UI and live read-only Windows inventory
+        run: python -m unittest discover -s tests -p 'test_wireless.py' -v
+
  # The iPhone app: builds for the Simulator and runs its unit tests.
  ios:
    runs-on: macos-latest
@@ -173,3 +173,24 @@ jobs:
            app/dist/*.AppImage
            app/dist/*.deb
          if-no-files-found: ignore
+
+  checksums:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Attach SHA256SUMS after all installers upload
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          gh api --paginate "repos/$GH_REPO/releases?per_page=100" --jq '.[]' > releases.jsonl
+          python3 scripts/release-checksums.py --tag "$GITHUB_REF_NAME" < releases.jsonl > SHA256SUMS
+          # Find the same draft using its exact tag, or its version title if a
+          # draft edit made GitHub temporarily show an untagged-* tag name.
+          id=$(python3 scripts/release-checksums.py --tag "$GITHUB_REF_NAME" --id < releases.jsonl)
+          old=$(gh api "repos/$GH_REPO/releases/$id" --jq '.assets[] | select(.name == "SHA256SUMS") | .id')
+          for asset in $old; do gh api -X DELETE "repos/$GH_REPO/releases/assets/$asset" >/dev/null; done
+          gh api -X POST "https://uploads.github.com/repos/$GH_REPO/releases/$id/assets?name=SHA256SUMS" \
+            -H "Content-Type: text/plain" --input SHA256SUMS >/dev/null
@@ -2,6 +2,119 @@

 ## Unreleased

+- Fix smoke cleanup skipping orphan metadata and Steam shortcuts after a test
+  title directory was already removed. Sweep and verify all six exact reserved
+  smoke IDs; preserve similarly named titles. Make `scripts/frame-smoke.sh`
+  work with POSIX sh and Python 3 without zsh, including from another working
+  directory. Local regressions cover both fixes; no new headset run.
+
+- Skip backup saves and settings reached through a symbolic link anywhere below
+  the home folder, and recheck paths before packing each file. Local synthetic
+  tests cover redirected Proton prefixes and links changed after discovery;
+  concurrent filesystem changes can still race the checks.
+  [Backup layout and limits](docs/backup-and-recovery.md).
+
+- Import a base APK with supported native-library or asset splits from a local
+  Android backup or XAPK/APKS/APKM bundle. Check package and version before
+  install; refuse resource, code and feature splits and device-variant sets.
+  This route has local fixture coverage, not a real split-game headset test.
+
+- Save Steam screenshots under a separate folder for each headset, Steam
+  account and game. Equal screenshot filenames no longer overwrite one another;
+  existing files in the old flat folder are left in place.
+  [Copying guide](docs/recording.md).
+
+- Keep Steam clip exports separate for each headset, Steam account and nested
+  recording session. Manual export and automatic copying use the same folders;
+  existing flat exports stay untouched and do not mark unrelated clips saved.
+  [Recording guide](docs/recording.md#steam-clips).
+
+- Compare two explicit Windows Wireless Adapter doctor reads in local memory.
+  Highlight exact PnP instances and known state changes after a dropout;
+  incomplete inventories stay unknown. A Forget button clears the comparison.
+  No adapter setting changes or report uploads are made.
+
+- Add recovery steps to the Windows Wireless Adapter doctor for streams that
+  drop as they start and dongles that will not reconnect. Compare exact PnP IDs
+  and test one connection condition at a time. In-app disable/re-enable remains
+  deferred until an active Steam adapter instance can be identified safely.
+  [Guide and limits](docs/windows-wireless-doctor.md).
+
+- Add an explicit host window-switch button to whole-display panels: Alt-Tab
+  on Windows and Command-Tab on macOS. Single-window panels keep their own
+  source, so the button is hidden there.
+
+- Enable the in-app OBS source Start/Stop control on Windows. A control pipe
+  lets the Python relay close its SSH child on Stop, app quit or parent exit;
+  add a short [Discord guide](docs/streaming-to-discord.md).
+
+- Add a read-only wired connection doctor for a PC using the Frame's observed
+  USB-C network: show the local route, SSH port and pinned-key login result
+  without changing IP, host keys or headset settings.
+  [Usage and limits](docs/wired-connection.md).
+
+- Start the Android app catalogue without waiting for the headset's installed-app
+  list. Browsing remains available if that status request is slow or fails;
+  installation still waits for a confirmed list to avoid duplicate installs.
+
+- Verify the packaged OBS Start and Stop control with a real Frame, and record
+  37.600 seconds of headset mirror video and non-silent output audio in OBS.
+  Listening, sync and active passthrough remain unverified.
+  [Test record](docs/evidence/obs-media-source-real-2026-10-25.md).
+
+- Bundle the OBS source helper in Linux and macOS installers and add a
+  **Capture & Live** Start/Stop control. The app selects the active Frame and
+  closes its SSH stream on a headset switch or app exit. A real Frame stream
+  reached OBS with video and non-silent audio; listening and sync remain
+  unverified. [Setup and limits](docs/obs-headset-source.md).
+
+- Add a source-checkout helper that sends the Frame's SteamVR mirror and
+  default-output audio to a local OBS Media Source. A real Frame supplied a
+  4.021-second H.264/AAC stream to a Linux receiver; OBS playback and sync
+  remain unverified. [Setup and limits](docs/obs-headset-source.md).
+
+- Link emulator setup guidance from Store → Emulators. Existing Steam library
+  shortcuts and artwork cover Android apps and sideloaded titles; Android ROM
+  transfer still needs a verified per-instance workflow.
+  [Guide](docs/emulators.md).
+
+- Record the current Frame OS mirror and charge-limit checks. Active
+  passthrough in the mirror is still unknown; this build has no supported
+  user-writable 80% charge-limit control.
+  [Headset evidence](docs/evidence/round3-headset-2026-10-25.md).
+
+- Add Windows Tools → Wireless Adapter doctor: an explicit read-only PC snapshot
+  of distinct Wi-Fi Direct PnP instances, presence/link state, PC Wi-Fi and
+  reported channels/bands, with possible 2.4 GHz overlap guidance. Unknowns stay
+  visible; no adapter disable action is offered because an unused instance
+  cannot be identified reliably. No headset access or settings changes.
+  [Sources, verification and limits](docs/windows-wireless-doctor.md).
+
+- Add a Linux PC Wireless Adapter doctor in Settings and Devices, with a source
+  CLI and local JSON report. Select observed hardware without assuming Valve
+  IDs; inspect USB/interface presence, driver/module binding, udev/permissions,
+  rfkill, channel/band and network manager evidence. Missing evidence stays
+  unknown; all checks are read-only and never contact the Frame.
+  [Usage and verification limits](docs/linux-wireless-adapter-doctor.md).
+
+- Add Linux Tools → Steam desktop sharing: request `steam -pipewire` only after
+  checking Steam is not running, or open KDE Application Permissions with
+  instructions to revoke a verified Steam screen-sharing session manually. No
+  automatic permission reset, Steam restart, or headset access. Frame Control
+  Linux capture remains disabled; live portal behavior is unverified.
+  [Usage and limits](docs/steam-pipewire.md).
+
+- Use gamescope's input for the keyboard and trackpad, following the focused
+  headset panel without installing an input service. Start KDE Connect only for
+  accents and emoji, keeping queued text ordered and cancelling it on headset
+  switches. Retain intended-headset checks before starting either control and
+  prevent Unicode helper startup from deadlocking with a headset switch.
+- Keep accepted keyboard text when the Unicode queue is full: reject new batches
+  before sending their clicks or keys, and count in-flight text toward the limit.
+  Retain unsent text after helper failures/timeouts, report the error and resume
+  it with Try again. Clean up failed workers without touching a new headset's queue.
+  [Current verification and device limits](docs/evidence/pad-gamescope-2026-10-24.md).
+
 - Keep media playback running when SteamVR refuses the optional theatre dark
  surround, including a retry after standby. Log the refusal and play without
  the surround. Overlay teardown attempts every owned handle and always calls
@@ -117,3 +230,8 @@
  shared Wine services are left alone. Verified with local Linux process
  regressions and a 13/13 real Frame smoke run that stopped five test-owned
  Proton process PIDs before removing the Windows test title.
+
+- Keep failed automatic screenshot and clip copies visible after three attempts.
+  **Resume** and **Copy everything now** allow another try without restarting;
+  headset switches cannot use another headset's list or saved-file history.
+  [Copying guide](docs/recording.md).
@@ -58,6 +58,9 @@ node --test site/test/*.test.mjs        # website feedback function

 Say what you tested, and whether you tried it on a real Steam Frame.

+To add a local feature without changing the core app, see the
+[extension guide](docs/extensions.md) and its working example.
+
 ## Blocking

 If you ignore this document twice, or spam the tracker with agent-generated
@@ -25,6 +25,8 @@ See what the headset sees, install games and Android apps, move files and text a

 <sub>Unofficial hobby project, not affiliated with Valve. Free and open source.</sub>

+[See what was tested on a real Frame, in a VM, or only in automated checks](docs/current-support-matrix.md).
+
 </div>

 ---
@@ -44,6 +46,9 @@ Live video of what the lenses show, or of the app panel in use, flat and still h
 **🔋 Battery and status**<br>
 Charge, charging watts and time left, storage, memory, temperature, Wi-Fi, and what's running.

+For PC-side USB, driver, radio and network manager evidence, use the
+[Linux Wireless Adapter doctor](docs/linux-wireless-adapter-doctor.md).
+
 For repeatable read-only battery, power-rail, temperature and fan measurements,
 use the [power and heat sampler](docs/power-and-heat.md).

@@ -73,10 +78,10 @@ Drag files onto the window to send them. Drop a game's .zip, folder or .exe to a
 <td valign="top">

 **📸 Screenshots and recordings**<br>
-Browse the shots you take in the headset and save them to your Pictures folder, or have new ones and your Steam clips copied over automatically. Record what the headset shows, with its sound, or export Steam's clips at any length, as .mp4 files in your Videos folder ([not tested on a headset yet](docs/recording.md)).
+Browse the shots you take in the headset and save them to your Pictures folder, or have new ones and your Steam clips copied over automatically. Record SteamVR's mirrored headset view, with its sound, or export Steam's clips at any length, as .mp4 files in your Videos folder. [Recording details and passthrough limits](docs/recording.md#does-record-include-passthrough).

-**⌨️ Type on the headset**<br>
-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. Copy text to the headset's clipboard and back again. Nothing else to install, anywhere. Press T to open it.
+**⌨️ 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. Copy text to the headset's clipboard and back again. Press T to open it.

 </td>
 </tr>
@@ -127,6 +132,24 @@ Choose the operating system and processor of the computer you will use.
 | **Linux** (x64) | [AppImage](https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-linux-x86_64.AppImage) · [.deb](https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-linux-amd64.deb) | `ssh` (most desktops have it) |
 | **Linux** (arm64) | [AppImage](https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-linux-arm64.AppImage) · [.deb](https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-linux-arm64.deb) | `ssh`, and `adb` for Android apps (`sudo apt install adb`) |

+### Is it safe? Check your download
+
+Starting with **v0.4.26**, get the installer and [SHA256SUMS](https://github.com/saphid/frame-control/releases/latest/download/SHA256SUMS) from the **same release**. Earlier releases do not have this file. A matching SHA-256 means your file matches that release asset. It does not prove the app is free of malware. Use the command for your downloaded file, then compare all 64 characters with its line in `SHA256SUMS`:
+
+```powershell
+# Windows PowerShell
+Get-FileHash .\Frame-Control-Setup-x64.exe -Algorithm SHA256
+```
+
+```sh
+# macOS: shasum -a 256 Frame-Control-mac-arm64.dmg
+# Linux: sha256sum Frame-Control-linux-x86_64.AppImage
+```
+
+The [source](https://github.com/saphid/frame-control) and [release build workflow](.github/workflows/release.yml) are public. The Windows installer is **not code-signed**, so SmartScreen may warn. The macOS app has only an **ad hoc signature**, not an Apple Developer ID signature; the DMG is **unsigned and not notarized**, so Gatekeeper may warn or block it. Only follow the opening steps below if you trust the download.
+
+日本語: [5 ステップの接続ガイド](docs/connection-faq.md#日本語-5-ステップで接続)を参照してください。v0.4.26 以降は公式リリースの SHA256SUMS とファイルの SHA-256 値を照合してください。Windows は未署名、macOS は開発者 ID による署名・公証がありません。
+
 **Which build?** On a Mac, check Apple menu → About This Mac: the download is
 for Apple Silicon (M-series); no Intel Mac build is published. On Windows,
 check Settings → System → About → System type: the release is x64, not a native
@@ -183,8 +206,10 @@ or run it with `--appimage-extract-and-run`.

 ## Open the app

+**Optional: open at login.** In the installed desktop app, choose **Frame → Open at Login**. It is off by default. When on, a login launch starts in the tray or menu bar if that control is available; click its icon to open the window, or use its **Quit Frame Control** menu item. Closing the window keeps the app in the tray while this option is on. Turn the same menu option off to remove its OS login item. On Linux this creates or removes only Frame Control's own file in `~/.config/autostart/` (or `$XDG_CONFIG_HOME/autostart/`). If the desktop has no working tray, the window opens at login instead. A source checkout does not offer this setting.
+
 - **macOS:** open the `.dmg`, drag **Frame Control** to **Applications**, then
-  open it from Applications. For the unsigned-app warning, use the macOS steps
+  open it from Applications. For the Gatekeeper warning, use the macOS steps
  above. Allow local network access and control of Terminal when prompted.
 - **Windows:** run the installer, then open **Frame Control** from Start. For
  the portable download, extract the entire `.zip` first and run
@@ -220,6 +245,14 @@ network. Guest Wi-Fi/client isolation can prevent discovery and connections.
   check Developer Mode, the address and network isolation, then run setup again.
   For connections away from home, see [Tailscale](docs/tailscale.md).

+**Does Frame Control lower streaming lag?** No. Frame Control manages the Frame
+over SSH. SteamVR or Steam Link carries the game stream. Frame Control does not
+carry that stream, lower ping, or need the Wireless Adapter. It can connect over
+Wi-Fi, the Wireless Adapter, or USB when your computer has an SSH route to the
+Frame. The wired doctor checks only that SSH route. A data-capable USB-A-to-C
+cable has not been tested for the Frame's USB network. See the
+[connection FAQ and Japanese quick start](docs/connection-faq.md).
+
 **What it changes:** only what you click. Installs go to your user account on
 the Frame (`--user` Flatpaks, Lepton instances, Steam downloads, sideloaded
 games in `~/devkit-game`), and nothing
@@ -254,15 +287,18 @@ Frame's software fits together, all checked against a real headset and labelled
 | [Frame Control in detail](docs/frame-control.md) | Every feature, how it works, per-platform notes, building |
 | [Scripts and headset setup](docs/scripts.md) | The command-line helpers, minimum typing, streaming options, floating panels |
 | [How the Frame works](docs/how-the-frame-works.md) | SteamVR → gamescope → Plasma, verified facts, debugging |
+| [SteamOS October 2026 compatibility](docs/steamos-2026-10-compat.md) | Frame OS 0.5.6 connection changes and SteamOS 3.9.5 PC host notes |
 | [Android apps (Lepton)](docs/apks.md) | Sideloading, the rated F-Droid catalogue, per-app instances |
 | [Import from my Quest](docs/quest-import.md) | Copy games you own off your Quest by USB; what runs, and why licence-checked games may not |
 | [My Meta library](docs/meta-library.md) | Experimental: install and test Quest games your Meta account owns, with your own token |
 | [Sideloading Linux and Windows games](docs/sideloading.md) | A .zip, folder or .exe as a Steam Devkit Game, runtime detection |
 | [Install links for websites](docs/web-install.md) | `frame-control://install` links and manifests, the rules, a button to paste |
 | [VR comfort and HUD](docs/vr-utilities.md) · [Steam games](docs/steam-games.md) · [VR video](docs/vr-video.md) · [WebXR in Chromium](docs/webxr-chromium.md) | Installing and buying, watching VR180/360, the Chromium build |
+| [Steam desktop sharing (Linux)](docs/steam-pipewire.md) | External Steam helper: launch with `-pipewire` after exiting Steam, or open KDE permissions to re-pick a screen manually; no automatic permission reset |
 | [PC in the headset](docs/pc-in-headset.md) | Experimental, Windows only, off until you turn it on: a whole PC screen as a panel in the Frame. Tested in a Windows VM; individual windows need a WGC-enabled build |
 | [Mac in the headset](docs/mac-in-headset.md) | Mac windows and screens as panels in the Frame, with laser and keyboard input |
 | [VR mods and custom songs](docs/mods.md) | UEVR for Unreal games from Frame Control (install, play in VR, remove), the per-game table, Beat Saber blockers |
+| [Decky Loader on Frame](docs/decky-frame.md) · [Frame Control in VR](docs/headset-app.md) · [Frame plugin author guide](docs/frame-plugin-author.md) · [Frame Control extensions](docs/extensions.md) | Experimental Decky support, a removable headset panel, and the local extension API |
 | [SSH](docs/ssh.md) · [Streaming](docs/streaming.md) · [Files](docs/file-transfer.md) · [Panels](docs/panels.md) · [Tailscale](docs/tailscale.md) | Topic notes |
 | [Frame Control for iPhone](docs/iphone.md) | The iPhone and iPad app, how it runs the server on the Frame, pairing |
 | [Recovery and OS images](docs/recovery-and-images.md) | Where to download the Frame's OS, what's inside, testing without the headset |
@@ -17,6 +17,7 @@ const REQUIRED = [
  "ui/frame_status.py",
  "scripts/frame_power_sample.py",
  "scripts/frame_power_report.py",
+  "scripts/obs-headset-source.py",
  "ui/frame_android.py",
  "frame/android/lepton-app.sh",
  "frame/openxr-compat/XrApiLayer_FRAME_compat.json",
@@ -0,0 +1,53 @@
+// Opt-in OS login item. Linux owns only its marked autostart file; an existing
+// custom entry is never overwritten or removed.
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const MARKER = "# Managed by Frame Control; use Frame > Open at Login to remove.\n";
+const FILE = "com.saphid.frame-control.desktop";
+
+function quoteExec(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, "\\$").replace(/`/g, "\\`").replace(/%/g, "%%")}"`;
+}
+
+function createLoginItem({ platform = process.platform, electronApp, env = process.env,
+                           executable = process.execPath, filesystem = fs,
+                           home = os.homedir() }) {
+  const config = env.XDG_CONFIG_HOME && path.isAbsolute(env.XDG_CONFIG_HOME)
+    ? env.XDG_CONFIG_HOME : path.join(home, ".config");
+  const file = path.join(config, "autostart", FILE);
+  const command = platform === "linux" && env.APPIMAGE && path.isAbsolute(env.APPIMAGE)
+    ? env.APPIMAGE : executable;
+  function owned() {
+    try { return filesystem.readFileSync(file, "utf8").startsWith(MARKER); }
+    catch (err) { if (err.code === "ENOENT") return false; throw err; }
+  }
+  function enabled() {
+    if (platform === "linux") return owned();
+    return !!electronApp.getLoginItemSettings().openAtLogin;
+  }
+  function set(enabledNow) {
+    if (platform !== "linux") {
+      electronApp.setLoginItemSettings({ openAtLogin: !!enabledNow, openAsHidden: !!enabledNow,
+                                        args: enabledNow ? ["--hidden"] : [] });
+      if (enabled() !== !!enabledNow) throw new Error("The operating system did not save the login item.");
+      return enabled();
+    }
+    if (enabledNow) {
+      if (filesystem.existsSync(file) && !owned()) throw new Error(`A different autostart entry already exists: ${file}`);
+      filesystem.mkdirSync(path.dirname(file), { recursive: true });
+      const body = MARKER + "[Desktop Entry]\nType=Application\nName=Frame Control\n" +
+        `Exec=${quoteExec(command)} --hidden\nTerminal=false\nX-GNOME-Autostart-enabled=true\n`;
+      const tmp = file + `.tmp-${process.pid}`;
+      try { filesystem.writeFileSync(tmp, body, { mode: 0o600 }); filesystem.renameSync(tmp, file); }
+      finally { try { filesystem.unlinkSync(tmp); } catch (err) { if (err.code !== "ENOENT") throw err; } }
+    } else if (owned()) {
+      filesystem.unlinkSync(file);
+    }
+    return enabled();
+  }
+  return { enabled, set, file };
+}
+
+module.exports = { createLoginItem, quoteExec };
@@ -1,7 +1,7 @@
 // Frame Control as a desktop app (macOS, Windows, Linux): starts ui/server.py on
 // a free loopback port and shows it in a native window. The server does all the
 // work over the `frame` SSH alias; this file only hosts it.
-const { app, BrowserWindow, Menu, Notification, clipboard, dialog, ipcMain, nativeImage, session, shell } = require("electron");
+const { app, BrowserWindow, Menu, Notification, Tray, clipboard, dialog, ipcMain, nativeImage, session, shell } = require("electron");
 const { execFile, spawn } = require("child_process");
 const { promisify } = require("util");
 const fs = require("fs");
@@ -12,6 +12,7 @@ const path = require("path");
 const { SCHEME, parseInstallLink, linkFromArgv } = require("./install-link");
 const updater = require("./updater");
 const { preferenceStore } = require("./preferences");
+const { createLoginItem } = require("./login-item");
 const { createMetaSignIn } = require("./meta-signin");

 const run = promisify(execFile);
@@ -30,10 +31,12 @@ const LOG = path.join(LOG_DIR, "server.log");
 const BG = "#0d1117";
 const FRAME = process.env.FRAME_ALIAS || "frame";
 const preferences = preferenceStore(path.join(app.getPath("userData"), "client-preferences.json"));
+const loginItem = createLoginItem({ electronApp: app });

 let server = null;
 let url = null;
 let win = null;
+let tray = null;
 let quitting = false;
 let python = null;

@@ -304,6 +307,33 @@ ipcMain.handle("update:get", (e) => fromUi(e) ? publicUpdate() : null);
 ipcMain.handle("update:check", (e) => fromUi(e) ? checkForUpdate({ manual: true }).then(publicUpdate) : null);
 ipcMain.handle("update:install", (e) => { if (fromUi(e)) installUpdate(); });

+// The OBS source is local to this computer. Closing the Python relay's control
+// pipe lets it stop SSH on every platform, including Windows where SIGTERM
+// terminates Python without running its cleanup block.
+const OBS_SCRIPT = path.join(SCRIPTS, "obs-headset-source.py");
+const { createObsSource } = require("./obs-source");
+const obsSource = createObsSource({
+  spawn,
+  // Keep the button hidden until native Windows/Frame streaming is verified.
+  supported: !IS_WIN,
+  prepare: async alias => {
+    if (!fs.existsSync(OBS_SCRIPT)) throw new Error("The OBS helper is missing; reinstall Frame Control.");
+    const env = { ...process.env, PATH: await loginPath() };
+    const executable = python || await findPython(env);
+    if (!executable) throw new Error(PYTHON_HELP);
+    if (quitting || alias !== activeAlias()) throw new Error("The selected headset changed; try again.");
+    return { executable, args: [...PY_FLAGS, OBS_SCRIPT], env };
+  },
+  onState: state => {
+    if (win && !win.isDestroyed()) win.webContents.send("obs:state", state);
+  },
+});
+const publicObs = () => obsSource.status();
+const stopObs = () => obsSource.stop();
+ipcMain.handle("obs:status", e => fromUi(e) ? publicObs() : null);
+ipcMain.handle("obs:start", (e, port) => fromUi(e) ? obsSource.start(activeAlias(), port) : null);
+ipcMain.handle("obs:stop", e => fromUi(e) ? stopObs() : null);
+
 // The page reports the headsets it knows (the server's Devices tab), so the Frame
 // menu can switch between them. Only plain names and ids go into the menu.
 const ALIAS_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
@@ -314,6 +344,7 @@ ipcMain.on("devices:changed", (e, list) => {
    .map(d => ({ id: d.id.slice(0, 80), name: String(d.name || d.alias).slice(0, 60), alias: d.alias, active: !!d.active }));
  if (JSON.stringify(next) === JSON.stringify(devices)) return;
  devices = next;
+  if (obsSource.status().alias && obsSource.status().alias !== activeAlias()) stopObs();
  buildMenu();
 });
 const activeAlias = () => (devices.find(d => d.active) || {}).alias || FRAME;
@@ -516,7 +547,60 @@ function registerScheme() {
  }
 }

-function createWindow() {
+function showWindow() {
+  if (!win) return createWindow(true);
+  if (win.isMinimized()) win.restore();
+  win.show();
+  win.focus();
+}
+
+function ensureTray() {
+  if (tray) return true;
+  try {
+    const icon = nativeImage.createFromPath(path.join(__dirname, "build", "icon.png"));
+    if (icon.isEmpty()) return false;
+    tray = new Tray(icon);
+    // Some Linux desktops accept the Tray object but expose no status icon.
+    // Keep a visible login window rather than hiding the only way back in.
+    if (process.platform === "linux") {
+      const bounds = tray.getBounds();
+      if (!bounds.width || !bounds.height) { tray.destroy(); tray = null; return false; }
+    }
+    tray.setToolTip("Frame Control");
+    tray.on("click", showWindow);
+    updateTrayMenu();
+    return true;
+  } catch {
+    if (tray) { try { tray.destroy(); } catch {} tray = null; }
+    return false;
+  }
+}
+
+function updateTrayMenu() {
+  if (!tray) return;
+  tray.setContextMenu(Menu.buildFromTemplate([
+    { label: "Open Frame Control", click: showWindow },
+    { label: "Open at Login", type: "checkbox", checked: loginItem.enabled(), click: toggleLoginItem },
+    { type: "separator" },
+    { label: "Quit Frame Control", click: () => app.quit() },
+  ]));
+}
+
+function toggleLoginItem() {
+  try {
+    const on = loginItem.set(!loginItem.enabled());
+    if (on) ensureTray();
+    else if (tray) { tray.destroy(); tray = null; }
+    buildMenu();
+    updateTrayMenu();
+  } catch (err) {
+    dialog.showErrorBox("Open at Login", String(err.message || err));
+    buildMenu();
+    updateTrayMenu();
+  }
+}
+
+function createWindow(showOnReady = !process.argv.includes("--hidden") || !tray) {
  win = new BrowserWindow({
    width: 1400, height: 950, minWidth: 760, minHeight: 560,
    title: "Frame Control", backgroundColor: BG, show: false,
@@ -525,7 +609,10 @@ function createWindow() {
    webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true, backgroundThrottling: false,
                      preload: path.join(__dirname, "preload.js") },
  });
-  win.once("ready-to-show", () => win.show());
+  win.once("ready-to-show", () => { if (showOnReady) win.show(); });
+  win.on("close", (event) => {
+    if (!quitting && tray && loginItem.enabled()) { event.preventDefault(); win.hide(); }
+  });
  if (CHROME_CSS) win.webContents.on("did-finish-load", () => win.webContents.insertCSS(CHROME_CSS));
  // External links open in the default browser; the app never navigates away.
  win.webContents.setWindowOpenHandler(({ url: target }) => {
@@ -579,6 +666,8 @@ function buildMenu() {
      label: "Frame",
      submenu: [
        { label: "Set Up Connection…", click: () => setUpConnection() },
+        { label: "Open at Login", type: "checkbox", checked: loginItem.enabled(),
+          enabled: app.isPackaged, click: toggleLoginItem },
        { label: IS_MAC ? "Open SSH in Terminal" : "Open SSH in a Terminal", click: openSsh },
        { type: "separator" },
        ...(devices.length > 1 ? [{
@@ -627,7 +716,7 @@ if (!app.requestSingleInstanceLock()) {
  app.on("open-url", (e, link) => { e.preventDefault(); openInstallLink(link); });
  // Windows and Linux start a second instance with the link as an argument.
  app.on("second-instance", (_e, argv) => {
-    if (win) { if (win.isMinimized()) win.restore(); win.focus(); }
+    if (!argv.includes("--hidden")) showWindow();
    const link = linkFromArgv(argv);
    if (link) openInstallLink(link);
  });
@@ -635,12 +724,41 @@ if (!app.requestSingleInstanceLock()) {
  if (firstLink) openInstallLink(firstLink);
  app.whenReady().then(() => {
    registerScheme();
+    if (loginItem.enabled()) ensureTray();
    buildMenu();
    createWindow();
    scheduleUpdateChecks();
  });
-  app.on("activate", () => { if (!win) createWindow(); });
+  app.on("activate", showWindow);
  app.on("window-all-closed", () => app.quit());
-  app.on("before-quit", () => { quitting = true; stopServer(); });
-  process.on("exit", stopServer);
+  let obsQuitWaiting = false;
+  let obsQuitReady = false;
+  app.on("before-quit", (event) => {
+    quitting = true;
+    stopServer();
+    if (!obsSource.child || obsQuitReady) { stopObs(); return; }
+    event.preventDefault();
+    if (obsQuitWaiting) return;
+    obsQuitWaiting = true;
+    const child = obsSource.child;
+    let timer;
+    child.once("close", () => {
+      clearTimeout(timer);
+      obsQuitReady = true;
+      app.quit();
+    });
+    stopObs();
+    timer = setTimeout(() => {
+      if (child.exitCode === null) {
+        if (IS_WIN) {
+          // Only the helper and its SSH child: never enumerate unrelated SSH jobs.
+          spawn("taskkill", ["/PID", String(child.pid), "/T", "/F"],
+                { stdio: "ignore", windowsHide: true, detached: true }).unref();
+        } else child.kill("SIGKILL");
+      }
+      obsQuitReady = true;
+      app.quit();
+    }, 8000);
+  });
+  process.on("exit", () => { stopObs(); stopServer(); });
 }
@@ -0,0 +1,59 @@
+// Own one Python relay. Async preparation can be cancelled before a process exists.
+const ALIAS = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+function createObsSource({ prepare, spawn, onState = () => {}, supported = true }) {
+  let child = null, attempt = 0;
+  let state = { state: 'idle', alias: '', port: 15099, error: '', supported };
+  const status = () => ({ ...state });
+  function set(next, alias = state.alias, port = state.port, error = '') {
+    state = { state: next, alias, port, error, supported };
+    onState(status()); return status();
+  }
+  function stop() {
+    ++attempt;
+    if (!child) return set('idle');
+    set('stopping');
+    if (child.stdin && !child.stdin.writableEnded) child.stdin.end();
+    return status();
+  }
+  async function start(alias, port = 15099) {
+    if (!supported) return status();
+    if (!ALIAS.test(alias || '')) throw new Error('Select a valid headset first.');
+    if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('OBS port must be a whole number from 1024 to 65535.');
+    if (child || state.state === 'starting') return status();
+    const id = ++attempt;
+    set('starting', alias, port);
+    try {
+      const { executable, args = [], env } = await prepare(alias);
+      if (id !== attempt) return status();
+      const proc = spawn(executable, [...args, '--frame', alias, '--port', String(port), '--control-stdin'],
+                         { env, stdio: ['pipe', 'ignore', 'pipe'], windowsHide: true });
+      child = proc;
+      // The helper may exit between a click and closing its control pipe.
+      proc.stdin.on('error', () => {});
+      let output = '';
+      proc.stderr.on('data', chunk => {
+        output = (output + chunk.toString('utf8')).slice(-2048);
+        if (child === proc && state.state === 'starting' && output.includes('Frame Control OBS stream is ready'))
+          set('running', alias, port);
+      });
+      proc.once('error', error => {
+        if (child !== proc) return;
+        child = null; set('failed', alias, port, `Could not start OBS source: ${error.message}`);
+      });
+      // close follows stderr EOF, so the final failure message is available.
+      proc.once('close', (code, signal) => {
+        if (child !== proc) return;
+        const stopping = state.state === 'stopping';
+        child = null;
+        set(stopping ? 'idle' : 'failed', alias, port,
+            stopping ? '' : `OBS source stopped (${signal || code}). ${output.trim().split('\n').pop() || 'Check SteamVR and SSH.'}`);
+      });
+      return status();
+    } catch (error) {
+      if (id !== attempt) return status();
+      return set('failed', alias, port, error.message);
+    }
+  }
+  return { start, stop, status, get child() { return child; } };
+}
+module.exports = { createObsSource };
@@ -1,12 +1,12 @@
 {
  "name": "frame-control",
-  "version": "0.4.17",
+  "version": "0.4.32",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "frame-control",
-      "version": "0.4.17",
+      "version": "0.4.32",
      "license": "MIT",
      "devDependencies": {
        "electron": "^44.4.5",
@@ -1,7 +1,7 @@
 {
  "name": "frame-control",
  "productName": "Frame Control",
-  "version": "0.4.17",
+  "version": "0.4.32",
  "description": "Desktop app for managing a Valve Steam Frame over SSH",
  "private": true,
  "main": "main.js",
@@ -36,10 +36,12 @@
    },
    "files": [
      "main.js",
+      "obs-source.js",
      "preload.js",
      "install-link.js",
      "updater.js",
      "preferences.js",
+      "login-item.js",
      "meta-signin.js",
      "package.json",
      "build/icon.png"
@@ -69,6 +71,7 @@
        "to": "scripts",
        "filter": [
          "*.sh",
+          "obs-headset-source.py",
          "frame_power_sample.py",
          "frame_power_report.py"
        ]
@@ -21,6 +21,15 @@ contextBridge.exposeInMainWorld("frameApp", {
  writeImage: (bytes) => ipcRenderer.invoke("clipboard:writeImage", bytes),
  setUpConnection: () => ipcRenderer.invoke("connection:setup"),
  restartServer: () => ipcRenderer.invoke("server:restart"),  // the "couldn't start" page's Try Again
+  obs: {
+    status: () => ipcRenderer.invoke("obs:status"),
+    start: (port) => ipcRenderer.invoke("obs:start", port),
+    stop: () => ipcRenderer.invoke("obs:stop"),
+    onState: (cb) => {
+      ipcRenderer.removeAllListeners("obs:state");
+      ipcRenderer.on("obs:state", (_e, state) => cb(state));
+    },
+  },
  // The Frame menu's headset switcher: the page tells it the headsets, and hears picks.
  devicesChanged: (list) => ipcRenderer.send("devices:changed", list),
  onUseDevice: (cb) => {
@@ -0,0 +1,57 @@
+const { test } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { createLoginItem } = require("../login-item");
+
+test("Linux login toggle creates and removes only its own desktop entry", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "frame-login-test-"));
+  try {
+    const login = createLoginItem({ platform: "linux", env: { XDG_CONFIG_HOME: root },
+                                    executable: "/opt/Frame Control/frame-control" });
+    assert.equal(login.enabled(), false);
+    assert.equal(login.set(true), true);
+    const body = fs.readFileSync(login.file, "utf8");
+    assert.match(body, /^# Managed by Frame Control;/);
+    assert.match(body, /Exec="\/opt\/Frame Control\/frame-control" --hidden/);
+    assert.equal(fs.statSync(login.file).mode & 0o777, 0o600);
+    assert.equal(login.set(false), false);
+    assert.equal(fs.existsSync(login.file), false);
+    fs.mkdirSync(path.dirname(login.file), { recursive: true });
+    fs.writeFileSync(login.file, "[Desktop Entry]\nName=My custom launcher\n");
+    assert.throws(() => login.set(true), /different autostart entry/);
+    assert.equal(login.set(false), false);
+    assert.match(fs.readFileSync(login.file, "utf8"), /My custom launcher/);
+  } finally { fs.rmSync(root, { recursive: true, force: true }); }
+});
+
+test("AppImage autostart launches the AppImage, with safe desktop escaping", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "frame-appimage-test-"));
+  try {
+    const login = createLoginItem({ platform: "linux", env: { XDG_CONFIG_HOME: root,
+                                    APPIMAGE: '/home/user/Frame Control 100%.AppImage' },
+                                    executable: "/tmp/.mount_extracted/AppRun" });
+    login.set(true);
+    assert.match(fs.readFileSync(login.file, "utf8"), /Exec="\/home\/user\/Frame Control 100%%\.AppImage" --hidden/);
+    login.set(false);
+  } finally { fs.rmSync(root, { recursive: true, force: true }); }
+});
+
+for (const platform of ["win32", "darwin"]) {
+  test(`${platform} login toggle uses the OS API and starts hidden`, () => {
+    let openAtLogin = false;
+    const calls = [];
+    const electronApp = {
+      getLoginItemSettings: () => ({ openAtLogin }),
+      setLoginItemSettings: opts => { calls.push(opts); openAtLogin = opts.openAtLogin; },
+    };
+    const login = createLoginItem({ platform, electronApp });
+    assert.equal(login.enabled(), false);
+    assert.equal(login.set(true), true);
+    assert.deepEqual(calls.at(-1).args, ["--hidden"]);
+    assert.equal(calls.at(-1).openAsHidden, true);
+    assert.equal(login.set(false), false);
+    assert.deepEqual(calls.at(-1).args, []);
+  });
+}
@@ -0,0 +1,86 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { EventEmitter } = require('node:events');
+const { createObsSource } = require('../obs-source');
+
+function fixture(prepare) {
+  const states = [], children = [];
+  const source = createObsSource({
+    prepare: prepare || (async () => ({ executable: 'python', args: ['helper.py'], env: {} })),
+    spawn(executable, args, options) {
+      const child = new EventEmitter();
+      child.stderr = new EventEmitter(); child.stdin = new EventEmitter();
+      child.stdin.end = () => { child.stdin.writableEnded = true; };
+      children.push({ child, executable, args, options }); return child;
+    },
+    onState: s => states.push(s),
+  });
+  return { source, states, children };
+}
+
+test('Stop during Python discovery cancels the pending start', async () => {
+  let resolve;
+  const f = fixture(() => new Promise(r => { resolve = r; }));
+  const pending = f.source.start('frame', 15100);
+  assert.equal(f.source.status().state, 'starting');
+  f.source.stop();
+  resolve({ executable: 'python', args: ['helper.py'], env: {} });
+  await pending;
+  assert.equal(f.children.length, 0);
+  assert.equal(f.source.status().state, 'idle');
+});
+
+test('late stderr cannot undo Stop; closing allows a fresh start on another port', async () => {
+  const f = fixture(); await f.source.start('frame', 15100);
+  const { child, args } = f.children[0];
+  assert.deepEqual(args.slice(-5), ['--frame', 'frame', '--port', '15100', '--control-stdin']);
+  child.stderr.emit('data', Buffer.from('Frame Control OBS stream is '));
+  child.stderr.emit('data', Buffer.from('ready\n'));
+  assert.equal(f.source.status().state, 'running');
+  f.source.stop();
+  child.stderr.emit('data', Buffer.from('last ffmpeg warning\n'));
+  assert.equal(f.source.status().state, 'stopping');
+  child.emit('close', 0, null);
+  assert.equal(f.source.status().state, 'idle');
+  await f.source.start('other-frame', 15101);
+  assert.equal(f.source.status().port, 15101);
+  // An old child cannot overwrite the replacement's state.
+  child.emit('close', 255, null);
+  assert.equal(f.source.status().state, 'starting');
+});
+
+test('concurrent starts spawn once and preparation failures are retryable', async () => {
+  let attempts = 0;
+  const f = fixture(async () => {
+    if (++attempts === 1) throw new Error('Python missing');
+    return { executable: 'python', args: [], env: {} };
+  });
+  assert.equal((await f.source.start('frame')).state, 'failed');
+  assert.match(f.source.status().error, /Python missing/);
+  await Promise.all([f.source.start('frame'), f.source.start('frame')]);
+  assert.equal(f.children.length, 1);
+});
+
+test('invalid ports and aliases cannot spawn; errors and closed pipes remain visible', async () => {
+  const f = fixture();
+  for (const port of [0, 1023, 65536, 15099.5, '15100']) {
+    await assert.rejects(f.source.start('frame', port), /port/i);
+  }
+  await assert.rejects(f.source.start('-bad'), /headset/i);
+  assert.equal(f.children.length, 0);
+  await f.source.start('frame');
+  const { child } = f.children[0];
+  child.stdin.emit('error', Object.assign(new Error('closed pipe'), { code: 'EPIPE' }));
+  child.stderr.emit('data', Buffer.from('network lost\n'));
+  child.emit('close', 255, null);
+  assert.equal(f.source.status().state, 'failed');
+  assert.match(f.source.status().error, /network lost/);
+});
+
+test('an unverified host hides the controls and cannot spawn a relay', async () => {
+  let spawned = false;
+  const source = createObsSource({ supported: false, prepare: async () => ({}), spawn: () => { spawned = true; } });
+  assert.equal(source.status().supported, false);
+  await source.start('frame');
+  assert.equal(spawned, false);
+});
@@ -4,7 +4,7 @@ A SideQuest backup can contain a small APK and much larger `main.…obb` and
 `patch.…obb` files. All of them belong to the same game. Installing only the APK
 can leave the game unable to start because its assets are missing.

-In **Add / Install → Import Android game** (or **Apps → Browse → Import Android game**), choose the APK and its OBB files together.
+In **Add / Install → Import Android game** (or **Apps → Browse → Import Android game**), choose the base APK, any supported splits, and its OBB files together.
 You can also drop them anywhere in the window. In the desktop app, dropping the
 APK alone finds matching OBB files beside it; dropping a folder containing the
 APK and OBBs also works. Browsers can read only the files you explicitly choose.
@@ -37,9 +37,13 @@ are discarded after use or cancellation; abandoned imports expire after an hour
 when the importer is next used, and dead-server staging folders are swept at
 startup.

-This flow handles one ordinary APK and standard OBB files for one game at a time.
-Split APKs, XAPK/APKS archives, nested Android/data folders and private save
-archives need their own import handling. PC ZIP/folder/EXE imports keep their
+This flow handles one base APK, supported native-library or asset splits, and
+standard OBB files for one game at a time. It checks the package and version in
+each split manifest before touching the headset. The existing Quest merger
+rejects resource, code and feature splits and sets with multiple device
+variants. A merged APK is re-signed; that can affect a game's licence or login.
+XAPK/APKS/APKM archives use the same checks. Nested Android/data folders and
+private save archives remain unsupported. PC ZIP/folder/EXE imports keep their
 existing route. Quest USB and Meta library imports keep their existing workflow.

 Validation covers actual APK parsing, the three-file backup layout, package
@@ -55,3 +59,5 @@ released, and the battery remained at 99%. See [device evidence](evidence/androi
 The headset was unworn; this checks transfer and persistence, not rendering,
 Resident Evil 4 gameplay, or a game that exits before data can be copied. This
 flow does not change APK compatibility or remove licence checks.
+The supported-split backup route was checked with generated local fixtures and
+existing merger tests, not a real split game on the Frame.
@@ -436,13 +436,13 @@ permissions remain unverified. They do not change APK install or launch behavior
 ## Local APK/OBB backups and Android bundles

 In **Android apps → Import Android game → Choose game files…** (or **Send to Frame**), choose one
-standalone APK and its matching `main.<version>.<package>.obb` and/or
+base APK, any supported splits, and its matching `main.<version>.<package>.obb` and/or
 `patch.<version>.<package>.obb` files together. The desktop app also discovers
 matching OBB files beside a lone selected APK. Browser uploads use only the
 files you selected. Installed apps can receive OBB-only imports.

 You can instead select **one `.xapk`, `.apks`, or `.apkm` archive** containing
-one standalone APK and optional matching OBBs. These extensions describe
+one base APK, optional supported splits and matching OBBs. These extensions describe
 containers, not a guarantee that their contents are supported. OBBs may be
 at the archive root, under `<package>/`, or under `Android/obb/<package>/`;
 one enclosing backup folder is allowed. Known manifest/icon/signature
@@ -450,7 +450,7 @@ sidecars are ignored; the APK manifest determines the package. Unknown files,
 unsafe paths, links, encrypted entries, duplicate paths (including case
 collisions), more than 4,096 entries, or more than 16 GiB unpacked are refused.
 Staging also keeps 64 MiB of free disk space. Payloads still have the regular
-one-APK/99-OBB limit. Ordinary `.zip` files keep the PC-title import route;
+100-file/99-OBB limit. Ordinary `.zip` files keep the PC-title import route;
 extract an Android ZIP yourself and select its APK/OBBs.

 The importer previews the app and files before **Import game & data**.
@@ -463,12 +463,14 @@ data setup. Uploaded and extracted staging is removed on cancellation,
 inspection failure, or job completion/failure; abandoned imports expire
 through the existing one-hour staging lifecycle. Original local files stay intact.

-**Limits:** this backup importer refuses multiple APKs, split-only APKs and
-bases marked as requiring splits. It does not select device variants or restore
-`Android/data`, private app data, saves, or entitlements. For the separate
-restricted native-library/asset split workflow see
-[Quest split APKs](quest-import.md#split-apks) and the CLI above. Resource,
-code and feature splits are not supported by that merger.
+**Limits:** this backup importer requires exactly one base APK. For split sets,
+each split must identify the same package and version, and pass the existing
+[Quest split merger](quest-import.md#split-apks). It refuses resource, code and
+feature splits and does not choose among device variants. Merging re-signs the
+APK, which can affect licences. It does not restore `Android/data`, private app
+data, saves or entitlements. These split imports have local fixture and merger
+tests, but no real split game has been installed with this backup route on the
+Frame.

 For issue #102, the RE4 report only establishes that an APK attempt failed.
 Missing OBBs are a hypothesis; the edition/build, exact files, failing step,
@@ -100,7 +100,21 @@ copy one by hand if you need it.
 - Steam Cloud's own folders (`userdata/<account>/<appid>`), shader caches and
  screenshots (**Tools → Capture & Live** saves those to Pictures).
 - Android apps themselves, their OBB files and shared storage (`/sdcard`).
- Symbolic links (never followed), and single files over 2 GiB.
+- Symbolic links, including any ancestor below the home folder of a selected
+  save or settings path, and single files over 2 GiB. Discovery checks each
+  component, and packing checks it again before opening each file.
+
+Steam backups use the normal `~/.local/share/Steam` directory tree. A separate
+`~/.steam/steam` alias does not affect this route. A library, Proton prefix or
+Wine save folder redirected by a symlink below the home folder is skipped,
+even if its target is inside home; it is not resolved and backed up elsewhere.
+The home folder itself is trusted and may use the host's normal path aliases.
+
+These are path checks, not a filesystem snapshot: a concurrent rename or link
+replacement between a check and a read can still race it. Close games and
+avoid moving or relinking these folders during backup. This fix rejects links
+already present when checked, including ones introduced after discovery; it
+does not provide atomic protection against concurrent filesystem changes.

 Backups aren't encrypted. Game folders can still hold a launcher's login, and
 Android app data can hold an app's, so keep backups private.
@@ -192,11 +206,18 @@ If the button can't help, or the headset isn't reachable:
 `tests/test_backup.py` runs the headset-side script (`ui/frame_backup_remote.py`)
 for real against a folder laid out like the Frame's home, with only SSH faked:
 which paths are picked, that sign-in files and keys never are (also inside game
-folders), links never followed, the manifest and its checksums, restore checks
+folders), links in save/settings roots and their ancestors refused, the manifest
+and its checksums, restore checks
 after a reset (game not installed, no Proton folders yet, not signed in), that a
 restore replaces only its own files and keeps the old ones, unsafe archives
 (`..`, absolute paths, links, other games' folders) writing nothing, backup
 names that try to leave the backups folder, and the exact Game Mode command.
+Synthetic symlink fixtures cover every component of a Proton save root below
+home, including `compatdata/<appid>` and `steamuser/AppData`, plus directory
+and file links introduced between discovery and packing. Ordinary Proton and
+non-Steam saves, Linux saves, controller layouts, reference settings and home
+aliases still pack with their original bytes. These are local fixture checks;
+this path fix has not been tested on a headset.
 `tests/e2e/test_recovery_kit.py` backs up a Proton save from the fake Frame through
 the server, deletes it and restores it. Neither involves a real headset.

@@ -9,6 +9,11 @@ only control the Frame has is a vendor charger attribute that Valve's own
 charging daemon also manages. Research as of 2026-10-23, confirmed with the
 read-only checks below on a Frame running SteamOS 0.5.6 (build 20261015.6141207):

+Rechecked read-only on build `20261022.6153909` on 2026-10-25: the
+`BatteryChargeLimit1` interface still returned `UnknownInterface`, no
+`charge_control_*` sysfs attribute existed, and the vendor charging switches
+were root-owned mode `644`. See [Round 3 headset evidence](evidence/round3-headset-2026-10-25.md).
+
 - `steamosctl get-max-charge-level` fails with `UnknownInterface: ...BatteryChargeLimit1`.
 - `/usr/share/steamos-manager/devices/` has `[battery_charge_limit]` only for
  the Steam Deck, ROG Ally, ROG Xbox Ally and MSI Claw, not the Frame.
@@ -0,0 +1,37 @@
+# Connection and streaming lag FAQ
+
+## Does Frame Control lower my streaming lag?
+
+No. Frame Control uses SSH to manage the Frame. SteamVR or Steam Link sends the
+game stream. Frame Control does not carry the game stream. It cannot lower your
+game-stream ping or fix a stream that stops on the PC. A 40–75 ms ping in a VR
+game is not a Frame Control measurement.
+
+You do **not** need the Steam Wireless Adapter to use Frame Control. The app can
+connect over Wi-Fi, the Wireless Adapter, or USB if the computer has an SSH
+route to the Frame. Use the route that lets the app connect. To improve game
+streaming, check the SteamVR or Steam Link connection on the PC and the Frame.
+The [wired connection doctor](wired-connection.md) checks only Frame Control's
+SSH route. A successful doctor check does not prove that the game stream uses
+the cable or has low lag.
+
+## Can I use a USB-A-to-C cable?
+
+A Mac reached the Frame over a USB-C connection on the
+`10.86.200.232/29` USB network. That test used a USB-C host port. We have
+**not tested a USB-A-to-C cable** with the Frame. A data-capable USB-A-to-C
+cable might show a USB network interface on your PC, but this is unknown on
+the tested Frame OS and PC hosts. Check whether your PC shows that interface
+and whether Frame Control's wired doctor can reach the Frame at
+`10.86.200.233`. A charge-only cable cannot carry USB data. You can use Wi-Fi
+for Frame Control if the USB route does not work.
+
+## 日本語: 5 ステップで接続
+
+1. [公式リリース](https://github.com/saphid/frame-control/releases/latest)から PC の OS 用ファイルをダウンロードします。Windows は `.exe`、macOS は `.dmg`、Linux は `.AppImage` または `.deb` です。同じリリースの `SHA256SUMS` でファイルを確認してください。
+2. PC に Frame Control をインストールして起動します。Windows はスタートメニュー、macOS はアプリケーション、Linux はアプリ一覧から開きます。AppImage の場合は実行権限を付けて開きます。
+3. Frame の Steam 設定 → システムで開発者モードを有効にし、開発者設定でユーザーパスワードを設定します。Frame と PC を同じ信頼できるネットワークに接続し、Frame を起こしておきます。
+4. PC の Frame Control で **Set Up Connection…** を選びます。Frame が見つからない場合は、Frame の設定で IP アドレスを確認して入力します。macOS では **Devices & connection → + Add a headset…** からアドレスを設定できます。
+5. Frame に **Pair new host** が出たら、自分が開始した要求だけを承認します。ペアリングに失敗した場合は、PC のターミナルで開発者モードのパスワードを入力します。接続後、Frame Control に戻って状態を確認します。
+
+Frame Control は管理用の SSH 接続を使います。ゲーム映像は SteamVR / Steam Link が送ります。Frame Control を入れてもゲームの ping は下がりません。無線アダプターは必須ではありません。USB-A-to-C ケーブルで Frame の USB ネットワークが使えるかは、まだ確認できていません。
@@ -0,0 +1,29 @@
+# What we have tested
+
+Current for Frame Control **v0.4.32**, 25 October 2026. “Real Frame + physical PC” means an actual headset and a non-virtual computer. “VM only” means a Windows virtual machine, sometimes connected to the real Frame. A CI test or a simulated device is **not** a physical hardware test. The date/version column is the last relevant check, not a promise that every new release was retested on that platform. See each link for the exact procedure and limits.
+
+| Feature | Real Frame + physical PC tested | VM only | Untested or limited | Last check and proof |
+|---|---|---|---|---|
+| Core title smoke test | Linux lxso2 installed, launched and removed reserved native/Proton titles on the real Frame; all 13 steps passed | No | Unworn headset; visible rendering and controller input not checked. Other feature paths retain their separate limits below | 25 Oct, v0.4.31 candidate source `1255ef2`, Frame OS 0.5.6 build `20261022.6153909`: [sanitized results](evidence/round2-smoke-2026-10-25.json) |
+| Windows desktop in the headset | No physical Windows PC test | Windows 11 VM sent a whole desktop to a real Frame; this used an intermediate fix, not the final native DLL | Physical GPU, capture and controller input; individual windows unavailable in bundled DXGI build | 24 Oct, v0.4.10 installer + candidate fix: [VM log](evidence/windows-vm-2026-10-24.md), [PC guide](pc-in-headset.md) |
+| Linux desktop in the headset | No | No | Native Linux PC capture is disabled; lxso2 lacked a desktop portal and PipeWire session. The separate Steam `-pipewire` helper is not Frame Control's PC capture | 24 Oct, v0.4.17: [host audit](evidence/linux-pc-host-lxso2-2026-10-24.md), [Steam helper PR #163](https://github.com/saphid/frame-control/pull/163) |
+| Mac desktop in the headset | A physical Mac sent its screen/window to a real Frame | No | Current v0.4.26 Mac installer and worn-headset controller input have not been repeated | 28 Sep, pre-v0.4 / Frame OS 0.4.1: [Mac guide and measurement](streaming.md#b-show-the-macs-desktop-inside-the-frame) |
+| OBS headset source on Linux | Real Frame to OBS 30.0.2 on a Linux host: 187.367 s, 720p30 H.264/AAC stereo, 5,621 frames, no encoder skips; room passthrough appeared in the recording | No | Synthetic tone was measured, not real game audio or audible listening. Default audio led by about 0.43 s in this setup; a measured +480 ms OBS offset removed residual skew at test resolution. Source-image latency was 1.431 s in one trial; other hosts and long sessions are unverified | 25 Oct, v0.4.30 package plus PR #219 runtime: [validation](evidence/obs-validation-2026-10-25.md) |
+| OBS headset source on Windows | No physical Windows PC test | Windows 11 VM helper fixture passed, but a native bridge to the real Frame sent no packets | In-app OBS controls remain hidden; native Windows OBS and firewall path are unverified | 25 Oct, PR #219: [validation](evidence/obs-validation-2026-10-25.md), [OBS guide](obs-headset-source.md) |
+| OBS headset source on macOS | No | No | Helper and OBS Media Source not tested on a Mac with a Frame | 25 Oct, v0.4.22: [OBS PR #174](https://github.com/saphid/frame-control/pull/174), [OBS guide](obs-headset-source.md) |
+| OBS headset source on a SteamOS / Steam Machine PC | No SteamOS PC or Flatpak OBS runtime test | No SteamOS host VM test | v0.4.27 AppImage launched on Ubuntu x86_64 under Xvfb; the helper sent H.264/AAC from a real Frame to a local UDP receiver. SteamOS read-only root, desktop UI and Flatpak OBS remain unverified | 25 Oct, v0.4.27: [host test](evidence/obs-steamos-host-2026-10-25.md), [OBS guide](obs-headset-source.md#steamos--steam-machine-pc-host) |
+| Wired connection doctor | No physical PC/Frame cable test of the doctor | No | Synthetic route/SSH tests; a separate Mac USB-C address observation does not test the doctor or game stream | 25 Oct, v0.4.23: [PR #178](https://github.com/saphid/frame-control/pull/178), [wired guide](wired-connection.md) |
+| Windows Wireless Adapter doctor | No physical Steam Wireless Adapter/dropout test | Windows 11 VM ran read-only checks without the adapter or WLAN | Adapter identification, dropouts and recovery on hardware | 24–25 Oct, v0.4.20–0.4.25: [VM log](evidence/windows-wireless-2026-10-24.md), [doctor guide](windows-wireless-doctor.md), [comparison PR #184](https://github.com/saphid/frame-control/pull/184) |
+| Linux Wireless Adapter doctor | No Steam Wireless Adapter hardware test | No | Read-only Linux host checks and mocked adapter states; no adapter-specific hardware observation | 24 Oct, v0.4.20: [PR #165](https://github.com/saphid/frame-control/pull/165), [doctor guide](linux-wireless-adapter-doctor.md) |
+| Switch PC windows | No physical Windows PC test | No real VM-to-Frame Alt+Tab check recorded | Explicit chord is covered by tests; actual window focus, keyboard layouts and controller interaction are unverified | 25 Oct, v0.4.24: [PR #181](https://github.com/saphid/frame-control/pull/181), [PC guide](pc-in-headset.md) |
+| Keyboard and trackpad from Frame Control | A Linux PC sent a click and ASCII keys to a temporary focused window on the real Frame | No | Worn-headset interaction, Unicode delivery and pixel-accurate pointing | 24 Oct, v0.4.19: [received-event log](evidence/pad-gamescope-2026-10-24.md), [PR #66](https://github.com/saphid/frame-control/pull/66) |
+| Backup and restore after reset | Same-headset backup, no-op save restore and Return to Game Mode checks | No | Restore **after a factory reset**, replacement restore and Android data restore have not been tested on a headset. No headset reset was done | 24 Oct, v0.4.17: [backup guide](backup-and-recovery.md), [Return to Game Mode log](evidence/return-game-mode-packaged-2026-10-24.json) |
+| Android game backup import | F-Droid Basic APK with synthetic main and patch OBBs installed, transferred and read back on a real Frame | No | v0.4.30 restricted split-APK backup route has generated-fixture and existing merger tests only; no real split game or RE4 gameplay test | 20 Oct OBB headset check; 25 Oct, v0.4.30 split fixtures: [OBB device evidence](evidence/android-import/device.json), [split PR #206](https://github.com/saphid/frame-control/pull/206), [guide](android-backups.md) |
+| Passthrough in recordings | Real room pixels in OBS and a production MP4 after safe SteamVR wake | No | **Yes** for the checked 0.5.6 mirror. Raw cameras are not opened. Other games/modes and Steam clips may differ | 25 Oct: [validation](evidence/obs-validation-2026-10-25.md), [recording guide](recording.md#does-record-include-passthrough) |
+| Open at login | No Frame needed; Linux autostart file toggled on a physical Linux host with an isolated config directory | No | A full login session and physical Windows/macOS host login have not been checked; OS API calls were unit tested | 25 Oct, v0.4.26: [PR #189](https://github.com/saphid/frame-control/pull/189) |
+| Local Frame Control extensions | Example panel displayed live Frame status in a browser preview; the real Frame served a read-only example in the experimental headset panel | No | No wearer-visible extension view; third-party extensions and physical Windows/macOS extension folders untested | 25 Oct, v0.4.29: [PR #194](https://github.com/saphid/frame-control/pull/194), [PR #201](https://github.com/saphid/frame-control/pull/201), [extension guide](extensions.md) |
+| Experimental Frame Control SteamVR panel | Real Frame OS 0.5.6 installed its user service, registered an overlay, served authenticated live status and a read-only extension, saved a screenshot and short MP4, and removed owned resources | No | Headset was unworn in standby: overlay reported `not_visible`, stereo capture was dark; wearer-visible pixels and controller input are unverified. The new large read-only status screen has browser layout and packaging checks only | 25 Oct, v0.4.29 device check and v0.4.31 status screen: [PR #198](https://github.com/saphid/frame-control/pull/198), [PR #201](https://github.com/saphid/frame-control/pull/201), [PR #220](https://github.com/saphid/frame-control/pull/220), [panel guide](headset-app.md) |
+| Experimental Decky Loader manager | Real Frame OS 0.5.6 ARM64 user-service install, status, update and remove completed; seven official-store plugin backends loaded, and ProtonDB Badges completed managed store install/update/remove | No | Plugin pages, settings, routes, toasts and controller input in VR remain unverified; some plugins need root, x86_64 binaries or Deck-specific hardware | 25 Oct, v0.4.31: [PR #208](https://github.com/saphid/frame-control/pull/208), [compatibility table](decky-frame.md) |
+| Experimental Framey VR plugin panels and store | No live real-Frame panel test | No | ProtonDB Badges settings rendered and sent a setting call in local Chromium. The fake Frame and CI exercised the store search, install progress, quick actions, settings, local routes and toasts. Wearer-visible pixels, controller input and live settings persistence remain unverified | 25 Oct, v0.4.32: [#223](https://github.com/saphid/frame-control/pull/223), [#224](https://github.com/saphid/frame-control/pull/224), [#225](https://github.com/saphid/frame-control/pull/225), [#226](https://github.com/saphid/frame-control/pull/226), [#227](https://github.com/saphid/frame-control/pull/227), [browser/fake Frame evidence](evidence/framey-browser-2026-10-25.md), [guide](framey-loader.md) |
+
+Release notes must preserve these limits until a newer recorded check changes them. When a feature is retested, add its date, exact app/Frame version, host type and proof here. The older [v0.3.1 matrix](support-matrix.html) is a historical snapshot and does not describe current coverage.
@@ -0,0 +1,195 @@
+# Decky Loader on Steam Frame
+
+For the modding-path survey, licence review and update limits, see
+[plugin and modding research](plugins-research.md).
+
+**Status, 2026-10-25:** Decky Loader 3.3.0's ARM64 backend starts on Frame OS
+0.5.6 and injects into Steam's shared CEF context. Its Decky tab registers in
+JavaScript. A usable plugin menu in the Frame's VR shell has **not** been
+verified. Frame Control therefore labels its user-service manager experimental.
+ProtonDB Badges loaded in the backend and Gamepad UI plugin registry, but its
+VR user interface has not been seen or used.
+
+## Official store plugin audit, 2026-10-25
+
+On a real Frame with Frame OS 0.5.6 build `20261022.6153909`, SteamVR 2.18.2
+reported `activity_level` 3 (standby). The battery was 99% before and after.
+The test downloaded the official store's current archives, checked each SHA-256
+against store metadata, and inspected their manifests and binaries. For seven
+non-root candidates, the removable user-service loader started each plugin in
+turn. It stopped between plugins. Logs showed `Loaded <name>` for all seven.
+The service and test folders were removed after the run; the owned shared lock
+was released. **A load message is not proof that a plugin's page, settings, or
+action works in VR.** No plugin was tried by a wearer.
+
+| Official store plugin (tested version) | Result | Evidence and limit |
+| --- | --- | --- |
+| ProtonDB Badges 1.3.4 | Partial | ARM64 backend loaded. Earlier 1.1.0 also registered in the shared Gamepad UI; badges in the VR shell were not seen. |
+| CSS Loader 2.1.3 | Partial | Backend loaded; one `SyntaxWarning`. Theme controls and CSS application in VR were not checked. |
+| SteamGridDB 1.8.1 | Partial | Backend loaded. Artwork selection and its UI were not checked. |
+| Animation Changer 1.3.2 | Partial | Backend loaded. Boot animation replacement was not attempted. |
+| Storage Cleaner 1.4.0 | Partial | Backend loaded. No files were cleaned; no UI check. |
+| HLTB for Deck 2.0.12 | Partial | Passive plugin loaded. Game page content in VR was not checked. |
+| Bluetooth 3.1.1 | Partial | Backend logged `Bluetooth plugin loaded`. Pairing and VR controls were not checked. |
+| PowerTools 2.0.3 | Not applicable | Manifest asks for root; archive includes x86_64 Ryzen binaries and targets Steam Deck hardware. The Frame user service blocks it. |
+| Audio Loader 1.6.1 | Not applicable | Manifest asks for `_root`; the Frame user service blocks it. |
+| Wine Cellar 0.2.1 | Broken on ARM64 | Archive includes an x86_64 backend binary. The store installer blocks it before execution. |
+| MagicPods 2.0.21 | Broken on ARM64 | Archive includes an x86_64 `magicpodscore` binary. The store installer blocks it before execution. |
+| Decky Recorder | Not in current official store | No matching plugin appeared in the official store list on this date; no archive was installed. Frame Control's own headset panel has a separate recorder. |
+
+The table reflects the tested versions only. Other releases can change their
+files or behavior. The official store's digest checks the archive in transit;
+it does not certify plugin code. Plugins run with the headset user's access.
+For a new plugin, follow the [Frame plugin and extension guide](frame-plugin-author.md).
+
+The new store transaction was also exercised on the same real Frame:
+**managed loader install → ProtonDB Badges 1.3.4 store install → status →
+store update → store remove → managed loader remove**. Status reported the
+managed store ID and version while the plugin was installed. The service
+remained active after each store change. The battery was 99% before and after.
+The test removed its plugin folder, loader, and owned lock. This validates the
+store file and service path over SSH, not a visible VR plugin page.
+
+Frame Control's desktop app and opt-in headset panel now show official store
+entries. Install, update, and remove need an explicit confirmation. They only
+change Frame Control owned plugin folders under
+`~/.local/share/frame-control/decky/plugins`. The installer checks the store
+hash and archive paths, blocks root plugins and non-ARM64 binaries, and rolls
+back an update if the service restart fails. The current VR shell does not
+provide Decky's Steam Deck Quick Access Menu. Frame Control's headset panel
+shows installed plugins and store actions. Its separate Framey iframe now hosts
+compatible API v2 plugin pages, settings, local routes, and panel toasts.
+Steam route patches and system notifications remain unavailable. The panel
+still needs a worn-headset visual and controller check. See the
+[current compatibility table](frame-plugin-author.md#framey-api-v2-compatibility).
+
+## What was checked on the real headset
+
+The headset was SteamOS `0.5.6`, `VARIANT_ID=vr`, build `20261022.6153909`,
+`aarch64` (SteamOS 3.9.x family). SSH reached it through the existing `frame`
+alias. `/` was mounted read-write as Btrfs; no root filesystem change was
+needed. `systemctl --user` was running. The Steam client launched with
+`-cef-enable-debugging`, `-vrgamepadui`, and `-steamdeck`; its web helper served
+CEF remote debugging on `127.0.0.1:8080`. The usual
+`.cef-enable-remote-debugging` marker was absent, yet debugging was active.
+
+CEF listed a `SharedJSContext` target at `steamloopback.host/routes/library/home`
+and a separate `SteamVR` target for the VR overlay. The Decky 3.3.0 ARM64
+binary started from `/tmp` as the normal user: port `127.0.0.1:1337` answered
+HTTP 200, the log reported `Loading Decky frontend!`, and CEF showed
+`window.deckyHasLoaded === true` and one registered Decky tab in
+`SharedJSContext`. The `SteamVR` target had neither that global nor a Decky tab;
+its current body text did not contain Decky. The Steam web helper had
+`--disable-quick-menu`. This is evidence of backend and shared-context
+injection, not proof of an accessible Decky plugin menu inside VR. A QAM
+interaction in the headset and a plugin UI test remain necessary.
+
+Frame Control's per-user manager was then exercised on the real Frame:
+**install → status → update → status → remove → status**. The service became
+active, the binary matched Decky's published SHA-256, and removal left no
+service, binary or listening port 1337. Decky's already injected JavaScript
+remained in Steam's running web helper until that helper was restarted. After a
+web helper restart, both `deckyHasLoaded` and the tab hook were absent. All
+temporary trial files and the test's empty managed data folder were removed.
+
+## ProtonDB Badges compatibility test
+
+The [ProtonDB Badges v1.1.0 release](https://github.com/OMGDuke/protondb-decky/releases/tag/v1.1.0)
+was tested on the same Frame OS build. It is a popular, passive Decky plugin
+(133 GitHub stars at test time) that adds badges to game pages. The published
+archive SHA-256 was
+`b4c72ff0ffe60b1a14abafe75a62f644cbb6689f398a753a1905c281151d9173`.
+Its six archive entries had no links or path traversal, and its manifest declared
+`flags: []` and `api_version: 2`. The release contains a frontend bundle and
+no backend `main.py`; its source backend only manages its own settings.
+
+The test copied the archive into Frame Control's managed Decky plugin folder,
+then installed the official Decky 3.3.0 ARM64 binary as a user service. Decky's
+log said `Plugin ProtonDB Badges is passive` and `Loaded ProtonDB Badges`.
+`DeckyPluginLoader.plugins` in Steam's `SharedJSContext` contained
+`ProtonDB Badges`; `deckyHasLoaded` was true there. The separate `SteamVR`
+CEF target had no Decky globals or plugin text, and SteamVR listed no Decky
+overlay. The headset was in standby, so no in-headset plugin page or badge
+interaction was verified. The backend's unauthenticated root URL returned
+HTTP 403, as expected.
+
+The test removed the managed Decky service and binary, the test plugin folder,
+and its shared-device lock. The service was no longer running, the plugin list
+was empty, the binary and unit were gone, and port 1337 was closed. Decky's
+already injected frontend may remain in the running Steam web helper until
+Steam normally restarts; the test did not restart Steam or SteamVR.
+
+## Why the official Decky installer is not used
+
+The current [Decky installer](https://github.com/SteamDeckHomebrew/decky-installer/blob/e42a3c828de90673959b4de26cf5c5d2c7830554/cli/install_release.sh)
+selects `PluginLoader-arm64` on `aarch64`, creates `~/homebrew/plugins`, writes
+the CEF marker, installs `/etc/systemd/system/plugin_loader.service`, and uses
+`sudo systemctl` to enable a **root** service. Its
+[uninstaller](https://github.com/SteamDeckHomebrew/decky-installer/blob/e42a3c828de90673959b4de26cf5c5d2c7830554/cli/uninstall.sh)
+also uses sudo. These scripts do not call `steamos-readonly`, but they do write
+under `/etc`; their root service has broad control over the headset. The
+current [Decky loader](https://github.com/SteamDeckHomebrew/decky-loader/blob/00cd202872b85868071b041c8f1b34e734147195/backend/decky_loader/injector.py)
+targets Steam's shared Gamepad UI CEF page, injects a frontend served on port
+1337, and patches the standard Quick Access Menu. On Frame, Steam supplies
+the CEF target, while visible VR shell integration is unresolved.
+
+Frame Control downloads only Decky's official latest ARM64 release, requires
+its published SHA-256 digest, and checks the ELF architecture. It installs a
+**user** service named `frame-control-decky.service` in
+`~/.config/systemd/user`, with the binary and plugin folder under
+`~/.local/share/frame-control/decky`. It never asks for a sudo password, edits
+`/etc`, or changes CEF flags. Decky warns that running without root is not
+officially supported. Plugins that require root, assume `~/homebrew`, or rely
+on Steam Deck hardware may fail even if the loader runs. Frame Control lists
+plugins already present in its managed folder and the upstream `~/homebrew`
+folder. The opt-in store manager installs compatible archives only into its
+own folder. It cannot make Steam Deck QAM plugin pages visible in Frame VR.
+The experimental [Framey panel host](framey-loader.md) can render compatible
+plugin settings inside Frame Control's separate SteamVR dashboard panel.
+The real headset still needs a worn-user visibility and controller check.
+
+The latest tested release was
+[Decky 3.3.0](https://github.com/SteamDeckHomebrew/decky-loader/releases/tag/v3.3.0),
+`PluginLoader-arm64` SHA-256
+`8ef5dcf36cbbbb6e97201a6baed5d79c4cc44ec27789fc9af1c5b6ae8f0b25b6`.
+This digest comes from that release's GitHub API asset metadata; it detects a
+download mismatch, but is not an independent signature.
+
+## Opt in and remove
+
+In Frame Control, open **Tools → Decky Loader on Frame**, read the experimental
+notice, check the acknowledgement box, and choose **Install**. **Update**
+downloads and verifies the latest ARM64 release again. **Remove managed
+Decky** disables and removes only Frame Control's user service and binary.
+It preserves plugin files and settings so unrelated user data is not deleted.
+Open **Official plugin store** to review a plugin, then confirm each install,
+update, or remove. Root and x86-only plugins are blocked. The manager only
+removes plugin folders that it installed; it leaves other Decky folders alone.
+The desktop app and headset panel share one lock for managed Decky changes.
+If another change is in progress, wait for it to finish and try again.
+Restart Steam or the headset to clear the frontend already injected into its
+current web helper process. No action wipes the headset.
+
+Manual removal if Frame Control is unavailable:
+
+```sh
+ssh frame 'systemctl --user disable --now frame-control-decky.service; rm -f ~/.config/systemd/user/frame-control-decky.service ~/.local/share/frame-control/decky/PluginLoader ~/.local/share/frame-control/decky/.frame-control/receipt.json; systemctl --user daemon-reload; systemctl --user reset-failed frame-control-decky.service'
+```
+
+That command intentionally keeps `~/.local/share/frame-control/decky/plugins`
+and `settings`. Check those folders before deleting them yourself. An upstream
+Decky installation is separate; use its own installer to remove it. Frame
+Control refuses to install alongside an upstream system service.
+
+## Next compatibility test
+
+In the headset, open Steam's VR dashboard and look for Decky's plugin tab or
+Quick Access Menu after an opt-in install. If none appears, inspect whether
+the VR shell exposes a different menu component and whether Decky's frontend
+can target it without patching Steam globally. Confirm the plugin's visible
+UI, controller interaction, and persistence across a normal Steam restart.
+Until those checks pass,
+Frame Control should not describe Decky plugins as usable in VR yet. A worn
+headset check is needed for both the Decky menu and the Frame Control SteamVR
+panel; only then can their controller interaction and plugin presentation be
+confirmed.
@@ -0,0 +1,54 @@
+# Emulators and your own games
+
+Frame Control's **Store → Emulators** lists Android emulators from its open
+app sources. Pick an app, read its compatibility result, and install it. An
+installed Android app gets its own Steam library shortcut and artwork; **Add
+artwork** in its library menu can fill missing images later. The artwork
+workflow also covers native Linux and Windows titles added through **Send to
+Frame**. An optional SteamGridDB key under **Settings → Library artwork**
+can supply exact-title community images; source images and generated art are
+fallbacks. See [VR APKs → In the Steam library](vr-apks.md#in-the-steam-library)
+for the limits and tested behavior.
+
+## Set up an emulator
+
+1. In **Store → Emulators**, choose an emulator that supports the console and
+   file format you want. Check its compatibility result before installing;
+   an app listed in the store is not automatically verified on the Frame.
+2. Launch the new shortcut from Steam. Open the emulator's own settings to
+   choose a gamepad layout, core or system, and game folder. These controls
+   differ by emulator; Frame Control does not change them.
+3. Use game files you own and any firmware that emulator's instructions
+   require. Frame Control does not provide ROMs or firmware.
+
+**Android apps run in separate Lepton instances.** Copying a ROM to the
+Frame's Linux `~/Downloads` through **Send to Frame** does not automatically
+put it in an Android app's `/sdcard/Download`. A one-click ROM transfer is
+deferred until an emulator and its file picker can be tested end to end on a
+real Frame. An app's own import or sync feature may be enough. Advanced users
+can use [Lepton's per-instance ADB port](apks.md)
+to copy into that instance, after confirming the correct container and port.
+Do not assume that port 5555 is the emulator: it is Lepton Development, while
+installed apps receive their own ports.
+
+For a native Linux emulator that can read the Frame's home directory, use
+**Send to Frame → Copy to ~/Downloads instead** for your files, then open them
+from the emulator. Whether a particular emulator has a Frame-compatible ARM64
+build, correct controller mapping and readable storage must be checked for
+that app. **Linux apps** in Frame Control lists Flatpak options; a Windows or
+native game archive can instead be added through
+[Send to Frame](sideloading.md#using-it), which registers a Steam title and
+artwork. Each ROM is usually opened *inside* its emulator; Frame Control does
+not create one Steam shortcut per ROM.
+
+## If something does not appear
+
+- Check that the emulator is running and is the same app instance to which
+  you sent the file. Android instances do not share `/sdcard` storage.
+- Check the emulator's supported extension and whether it expects an archive
+  or an extracted file. Some systems need firmware before games appear.
+- For an empty Steam tile, use **Add artwork** in the installed app or
+  sideloaded title menu. This changes artwork, not emulator data or ROMs.
+
+The Frame's microSD/USB path into Android apps remains unverified without an
+inserted medium and an app readback test; see [issue #169](https://github.com/saphid/frame-control/issues/169).
@@ -0,0 +1,79 @@
+# Auto-sync retry and headset-selection reliability
+
+Date: 25 October 2026. Base: `d79efb4`, Frame Control v0.4.30.
+Issue: [#214](https://github.com/saphid/frame-control/issues/214).
+Environment: Linux x86_64, Python 3.12.3, Node 24.15.0.
+
+## Reproduced problems
+
+The existing 19 auto-sync tests passed on the base revision. Added regressions
+failed before the implementation: an exhausted clip lost its error, explicit
+retry did not recover failed screenshots or clips, and switches around listing
+or copying continued the old pass. The original callback interface also had no
+way to carry the tick's captured device into the server list reservation.
+
+The final fake-source tests exercise these boundaries:
+
+- Fail screenshots or clips three times, keep checking without further copy
+  attempts, and retain the source error plus an explicit retry instruction.
+- Recover the source and use either Resume or Copy everything now without
+  restarting. Successful copies stay deduplicated; Resume retains the ledger
+  even after a local file is deleted. Copy everything now retains its documented
+  ability to restore deleted files and include older media.
+- Reset an exhausted budget while the source still fails: another three
+  attempts are allowed, rather than unlimited background attempts.
+- Save an exhausted item by hand and clear its stale failure on the next list.
+- Switch after tick captures A, during a list, after screenshot bookkeeping,
+  between media kinds, before a transfer, or before transfer bookkeeping.
+  Interrupted passes do not mark the other headset's IDs or continue copying.
+- Switch to B exactly at callback entry through the production `_sync_list`
+  adapter. `working(A)` refuses before calling the source list, leaving both
+  ledgers and copy callbacks untouched. The same production reservation blocks
+  a device switch during a list and rejects stale screenshot/clip transfers.
+- Execute the production Settings renderer in Node: Resume is available for
+  copy errors and disk-full pauses, and hidden for a healthy state.
+
+## Implementation boundary
+
+Each list callback now receives the captured device, like the copy callbacks.
+The existing server `working(meant)` mechanism checks that intended headset
+under `_work_lock` while reserving work; `devices_post` uses the same lock to
+refuse switches during that work. The worker also checks for interruption
+around lists and transfers. No new device lock or clip destination logic is
+introduced. The server diff is confined to `_sync_list`.
+
+The failed-attempt and error maps are in-memory and reset on explicit retry or
+restart. The successful-copy ledger and settings persistence retain their
+existing format. Disk-full pauses, offline backoff, clip settling and the
+three-attempt limit remain covered by the original tests.
+
+## Checks
+
+- `python3 -m unittest discover -s tests -p test_autosync.py -v`: 33 passed.
+- `python3 -m unittest discover -s tests -p test_shot_copy.py -v`: 2 passed.
+- `python3 -m unittest discover -s tests -p test_clips.py -v`: 34 passed,
+  including local ffmpeg coverage.
+- `python3 -m unittest discover -s tests -p test_service_regressions.py -v`:
+  36 passed.
+- `python3 -m unittest discover -s tests -p test_page_scripts.py -v`: 5 passed.
+- `node --test site/test/*.test.mjs`: 2 test files passed.
+- `python3 -m py_compile ui/frame_autosync.py ui/server.py tests/test_autosync.py`
+  and `git diff --check`: passed.
+
+- `python3 -m unittest discover -s tests -v`: 1,525 tests run in 184.876
+  seconds, passed with 16 skips. Ran with sandbox escalation for loopback
+  sockets; test isolation still used throwaway app/SSH data and mocked headset
+  transport. Final output:
+
+  ```text
+  Ran 1525 tests in 184.876s
+  OK (skipped=16)
+  ```
+
+## Limits and handoff
+
+All new regressions use fake sources and mocked transport; they do not prove
+real-headset transfer or UI rendering. No headset was accessed: its shared test
+lock was held by another task. The Docker fake-Frame end-to-end suite and
+Windows/macOS runs were not performed locally. The coordinator owns review and
+merge; this task does not release, change PR #113, or publish announcements.
@@ -0,0 +1,36 @@
+# Framey loader evidence, 25 October 2026
+
+## Local browser and fake Frame
+
+The official Decky store returned 116 validated entries. ProtonDB Badges was
+entry 14, release 1.3.4, SHA-256
+`90a3453ac02709cad64096e7539fd8141fa56f99ae3441fc24a4990dc9684358`.
+Its published ZIP passed Frame Control's store manifest and path validator. The current
+`dist/index.js` bundle was loaded in an opaque-origin iframe in local Chromium
+with the Framey React/DFL shim. The [browser screenshot](framey-browser-2026-10-25.png)
+shows the plugin's settings panel. A pointer click on **Enable Badge on
+Library** issued `set_setting('settings', …)` through the iframe's request
+bridge. The local test parent returned a stub backend reply; it did not use a
+real headset or Decky backend. A separate fake Frame CEF fixture returned
+`get_setting` and `set_setting` responses through Frame Control's CDP bridge;
+that fixture does not model the real Decky process.
+
+The disposable fake Frame end-to-end harness passed the store catalogue,
+acknowledgement and HTTP auth checks, hash-verified install, update, and
+removal through the real Frame Control HTTP server and SSH transaction. The
+full fake Frame suite passed 48 tests; the full unit suite passed 1,559 tests
+(16 skipped). Unit tests covered unsafe archives,
+unmanaged-folder preservation, asset isolation, backend-call scope,
+and safe aborts of the worn-headset check.
+
+## Real headset status
+
+Read-only SSH on Frame OS 0.5.6 found battery at 98–99%. SteamVR activity was
+initially 3 (standby), briefly 0, then 3 again. During the active probe the
+shared `/tmp/frame-test.lock` belonged to `obs-aacapv3evh-20261025`. It later
+became free after SteamVR returned to standby. Framey did not acquire, replace,
+or remove it. The active probe found no installed Frame Control VR panel or
+Framey plugin; the scripted worn check exited before acquiring a lock or
+altering the headset. There is **no** wearer-visible VR
+menu screenshot, controller-input proof, or live settings-persistence result
+from this round.
@@ -0,0 +1,58 @@
+# OBS relay and MP4 follow-up, 25 October 2026 UTC
+
+This check used a Linux x86-64 host (`lxso2`) and the real Frame running
+SteamOS 0.5.6, build `20261022.6153909`. The host reached `ssh frame`. Before
+device work, the task atomically acquired `/tmp/frame-test.lock`, wrote its
+owner marker, and after cleanup removed only that marker and its lock. Battery
+was 99–100%; SteamVR 2.18.2 reported `activity_level: 3` (standby). Steam and
+SteamVR were left running. No passthrough session or game was started.
+
+The production `scripts/obs-headset-source.py` relay reached its first local
+UDP packet in 0.65–1.15 seconds across several runs. A 12-second wall-clock
+capture of its MPEG-TS packets contained 325 H.264 frames at 1280×720,
+spanning 10.83 seconds of video timestamps: 30.0 fps. All 324 adjacent frame
+intervals were 33.333–33.334 ms, with none over 50 ms. The 826 captured TS
+packets had zero sync-byte, transport-error-indicator, or per-PID continuity
+errors. Six final TS packets arrived after the receiver's 12-second cutoff and
+were not included in those counts. Static standby pixels cannot establish
+whether a moving game would drop frames.
+
+After the fix, the `--height 1080 --fps 60 --no-audio` fallback reached its
+first packet in 0.597 seconds. An eight-second wall-clock capture contained
+447 H.264 frames at 1920×1080 over 7.45 seconds of video timestamps: 60.0 fps.
+All frame intervals were 16.666–16.667 ms, none over 25 ms, and its 756 TS
+packets had zero continuity or transport-error-indicator errors. It had no
+audio stream, as requested. The helper exited 0 on Stop, and the owned lock
+was released.
+
+The stream also contained 48 kHz stereo AAC. A 440 Hz synthetic tone played
+through the Frame's default speaker output with real-time pacing appeared in
+the capture for about 0.89 seconds; decoded audio had a -21.0 dB peak. This
+proves an audio signal reached the output monitor and OBS transport. It does
+not prove audible monitoring, real game audio, or audio/video sync: there was
+no simultaneous visible marker to compare with the tone.
+
+The production MP4 recording commands were run separately for six seconds,
+then Stop, remux, and copy to the host completed. Stop returned after 7.27
+seconds from Start, including six seconds of recording; the remote ffmpeg
+exited 0. The copied 36,929-byte MP4 contained 188 H.264 frames at 1920×1080
+and 30 fps (6.266 seconds), plus 281 AAC packets (5.994 seconds). One decoded
+frame at two seconds had a single color, RGB `(22, 27, 53)`, across all
+2,073,600 pixels. The test's remote files were removed; the host copy stayed
+under `/tmp` for inspection.
+
+The relay previously returned an error when the app deliberately closed its
+control pipe, because its SSH child commonly exits 255 after termination.
+The same test reproduced this (`helper_exit: 1`) on the real Frame. The follow-up
+fix recognizes deliberate Stop and adds bounded startup and stall timeouts,
+with fake-SSH regression tests. A new locked real-Frame check after the fix
+received its first 1,316-byte UDP datagram in 0.697 seconds and returned
+`helper_exit_after_stop: 0` after closing the app control pipe. The longer
+transport and MP4 measurements above were taken before the code change; the
+fix does not alter codecs or capture commands.
+
+Prior [OBS 30 Media Source evidence](obs-media-source-real-2026-10-25.md)
+records a real Frame stream in OBS on Linux. This follow-up measured the relay
+with an FFmpeg receiver; OBS itself was not relaunched. Windows and macOS
+application paths, wearer-visible image latency, real game sound, audible
+playback, perceptual A/V sync, and active passthrough pixels remain unverified.
@@ -0,0 +1,48 @@
+# OBS Media Source on a real Frame, 2026-10-25 AEDT
+
+The Linux x86_64 AppImage from PR #174's exact head `69fff152` had SHA-256
+`4902ac80b77fbf98ec918db29df9cf9260b8abd6763a5b5055572335869f038a`.
+Its extracted resources passed `app/build/check-resources.js`, including the
+OBS helper, and the app launched under Xvfb with an isolated profile and a
+dummy SSH alias. Its bundled server served the page with HTTP 200.
+
+For the device test, the PC was lxso2. The real Frame was reached as `ssh frame`
+under an atomically acquired `/tmp/frame-test.lock`. Battery read 100% Full
+before and after. SteamVR 2.18.2 reported `activity_level: 3` (standby). The
+mirror service and `/dev/video99` were active. The test cleaned its temporary
+remote WAV and released only its own lock.
+
+OBS 30.0.2 ran in a disposable Ubuntu 24.04 container on lxso2, with Xvfb and
+host loopback networking. A Media Source opened `udp://127.0.0.1:15099` with
+input format `mpegts`. A synthetic pattern and tone first verified the OBS
+scene: its saved 43.733-second MKV had H.264 video and AAC audio with a
+`-17.9 dB` audio peak. The real Frame test then ran the helper from the
+extracted AppImage resources **before** OBS opened the source, so OBS joined
+an ongoing stream. OBS's saved 37.600-second MKV had H.264 video and AAC audio.
+The standby mirror appeared in decoded frames by five seconds. A 440 Hz tone
+played briefly to the Frame's default PulseAudio output appeared in the OBS
+audio recording at seconds 20–21; decoded audio peaked at `-34.4 dB`. A
+separate direct recording of `@DEFAULT_MONITOR@` during the same type of tone
+peaked at `-34.5 dB`. These measurements verify non-silent headset output
+audio passed through the helper and OBS into the saved recording.
+
+The first OBS attempt opened its Media Source well before the Frame sent
+packets. Its output had a silent AAC track until the mirror appeared late.
+Starting the helper before OBS fixed this in the second run. The setup guide
+now recommends starting the source in Frame Control before adding or activating
+the OBS Media Source.
+
+The exact-head AppImage was then launched on an isolated Xvfb display and
+profile with the real `frame` alias. In **Tools → Capture & Live**, clicking
+**Start OBS source** changed the UI to **Stop OBS source** and showed
+`udp://127.0.0.1:15099` after the first stream packet. The packaged Python
+helper was running with `--frame frame`. Clicking **Stop OBS source** returned
+the UI to **Start OBS source**; the helper and its remote `/dev/video99` ffmpeg
+process were gone. The app exited through **File → Quit**. Battery again read
+100% Full, and the owned lock was released.
+
+**Limits:** Nobody listened to OBS audio monitoring or the Frame speakers.
+Audio/video sync was not measured. The headset was unworn and in standby, so
+this test does not answer whether active passthrough pixels appear in the
+mirror. The OBS MKVs were temporary local test artifacts and are not included
+in the repository.
@@ -0,0 +1,32 @@
+# SteamOS PC OBS host feasibility check, 2026-10-25 UTC
+
+The available x86_64 host, lxso2, runs Ubuntu 24.04.3. It has no `flatpak`
+command, OBS installation, SteamOS 3.9.5 VM or physical Steam Machine. This
+check therefore does **not** verify that Frame Control or Flatpak OBS runs on
+a SteamOS desktop or a read-only-root PC host.
+
+The downloaded v0.4.27 Linux x86_64 AppImage matched GitHub's SHA-256 digest
+`42d774653c69b193c3d577743c32b8fe8dfeee7ea1f8cdf7369902962d647b83`.
+With `APPIMAGE_EXTRACT_AND_RUN=1`, it launched under Xvfb using an isolated
+profile and its bundled server returned HTTP 200. FUSE mounting, physical
+display rendering and SteamOS-specific dependencies were not tested.
+
+The v0.4.27 tagged OBS helper then ran against the real Frame under the shared
+`/tmp/frame-test.lock`. Frame OS was 0.5.6 and SteamVR activity level was 3
+(standby). A receiver bound to `127.0.0.1:15099` on lxso2 accepted 497
+MPEG-TS packets, 93,436 bytes. Every datagram had complete 188-byte packets
+with sync bytes. `ffprobe` found H.264 video and AAC audio. Closing the
+helper's control pipe made it exit 0; no owned remote stream process remained.
+Battery read 100% Full before and after, and the owned lock was released. The
+temporary `.ts` file was removed. This proves the local UDP sender path on an
+Ubuntu host; it does not prove Flatpak OBS could receive it on SteamOS.
+
+The public
+[OBS Flatpak manifest](https://github.com/flathub/com.obsproject.Studio/blob/master/com.obsproject.Studio.json)
+lists `--share=network`, which permits use of the host network. We read that
+manifest but did not install or run the Flatpak. A future check needs a real
+SteamOS 3.9.5 desktop host or VM with Flatpak OBS: launch the AppImage without
+root changes, start the source, record from the Media Source at
+`udp://127.0.0.1:15099`, verify video and audible game audio, then stop and
+confirm cleanup. The standby test cannot establish real game audio, A/V sync
+or active passthrough in the mirror.
@@ -0,0 +1,125 @@
+# OBS end-to-end validation — 25 October 2026
+
+**Passthrough: yes.** Real room pixels behind SteamVR panels appeared in the
+live `/dev/video99` mirror, the saved OBS recording, and a decoded frame at
+four seconds in a production MP4. The Frame was safely woken with
+`vrcmd --handlewakeup`; no camera, power or compositor settings were changed.
+This establishes the checked SteamVR mirror, not every game/mode or Steam's
+own clips. Treat recordings as potentially showing the room.
+
+## Environment and provenance
+
+- Host: lxso2, Linux x86_64. Real OBS 30.0.2 in disposable Ubuntu 24.04/Xvfb,
+  using software llvmpipe rendering and the Media Source `ffmpeg_source`.
+- Frame: SteamOS 0.5.6, build `20261022.6153909`, SteamVR 2.18.2, reachable
+  with the existing `ssh frame` connection. Hardware use was serialized with
+  coordinator mppkd9qczt through `/tmp/frame-test.lock` and a unique owner.
+- Released v0.4.30 AppImage SHA-256:
+  `b1335bb06130f2cce64a0dd40a8cb60a52c68effc258dc4bc35f8c40c822d5bb`.
+  The long recording started through this app's actual Electron IPC, Python
+  helper and SSH stream. Robustness checks then used that released runtime
+  with the final changed resources and repacked `app.asar`; this was not a
+  newly built AppImage. No OBS plugin or host FFmpeg is required by the app.
+- Windows release ZIP SHA-256:
+  `a393cc1653f14f162b4a3e56803f7fe9bea7b04904d18577b0b2d7d7c2d95b03`.
+  Checked against release SHA256SUMS; bundled Python 3.12.14.
+
+Machine-readable measurements and the manual stimulus/analysis programs are
+in [obs-validation-2026-10-25/](obs-validation-2026-10-25/).
+Room images and videos remain private under `/tmp/obs-aacapv3evh` on lxso2;
+only their hashes are committed in `private-artifacts.json`.
+
+## Recording, sound, sync and latency
+
+| Check | Measured result | What it establishes |
+| --- | --- | --- |
+| Real OBS recording | 187.367 s; 15,784,412 bytes; H.264 1280×720 at 30 fps; 5,621 decoded video frames; AAC 48 kHz stereo | More than three minutes through the packaged Linux path |
+| OBS dropped frames | 0 encoder skips; 90 render lag/stall frames, approximately 1.6% of recording frames | The software-rendered host was not lossless; this is not a hardware-rendered performance benchmark |
+| Audio | 1 kHz stimulus; FFT peak 996.094 Hz at 11.719 Hz bin resolution; peak −13.207 dBFS; 0 clipped samples; measured harmonic energy −81.32 dB relative to fundamental | Non-silent, no numerical clipping or large harmonic distortion in the checked tone; no listening or real-game quality verdict |
+| Baseline A/V | Audio leads video by median 426.67 ms; range 360–426.67 ms across 36 pulses | Default OBS setup needs sync checking; not suitable for a claim of automatic accurate sync |
+| Live image latency | 1,431.4 ms, n=1; clock exchange RTT 3.409 ms; screenshot polling about 20–35 ms | Overlay submission to OBS source screenshot, not physical headset motion-to-photon latency |
+| Production MP4 | 5.121 s; 1920×1080, 30 fps, 153 video frames; AAC stereo; request to saved result 7.435 s | A separate production recorder saved room passthrough pixels too |
+
+The manual stimulus places an owned black/white OpenVR marker over the mirror
+and plays a 200 ms, 1 kHz tone every five seconds through the Frame's default
+output. `pa_simple_get_latency` estimates when the submitted samples play;
+marker submission is aligned to that estimate. This measures software output,
+not an externally measured loudspeaker/physical-display event. Most submission
+jitter was below 0.2 ms; compositor timing and the 30 fps/10 ms analysis grids
+still limit precision. FFmpeg decodes both tracks; the analysis detects marker
+edges and groups AAC pre-echo onsets within 100 ms.
+
+A separate initial +400 ms OBS Sync Offset trial left 83.33 ms of audio lead.
+Changing the offset during an already active source from 0 to +367 ms did not
+improve that run (366.67 ms before, 370 ms after). Do not assume a universal
+offset or that a live setting change has taken effect: reopen the source and
+verify another recording. Three subsequent fresh-source trials, setting the offset **before activating**
+the Media Source, measured 480 ms audio lead at 0 ms, 70 ms lead at +400 ms,
+and **0 ms at +480 ms** across three pulses (30 fps video and 10 ms audio
+analysis resolution). This proves a setup-specific workaround, not a universal
+default. See `calibration-initial.json`. Full trial measurements are retained. Zero OBS
+buffering caused missing/distorted sound and was rejected. Zero mux delay
+and alternate timestamp experiments did not improve latency and were not
+merged. The default capture/encoding settings remain unchanged.
+
+## Robustness and fixes
+
+| Failure or scenario | Fix / result | Proof |
+| --- | --- | --- |
+| Stop during asynchronous Python discovery could still launch later | Cancel the pending generation; expose Stop while starting | Controller regression test |
+| Late stderr containing an earlier ready message changed stopping back to running | Only accept ready while starting; ignore stale child events | Original released block reproduced in `race-before.json`; controller regression |
+| A non-responsive SSH process defeated timeout termination | Bounded terminate/wait then kill; SSH connection/keepalive bounds | Real SSH child deliberately stopped with SIGSTOP; clear UI failure in 15.009 s including 5 s forced cleanup; both processes gone |
+| Timeout with the app's stdin still open aborted Python at shutdown | Read the control descriptor directly, avoiding a blocked buffered-stdin daemon lock | Previously reproduced fatal shutdown; final real stall shows `The Frame OBS video stopped for 10 seconds`; subprocess regression holds stdin open |
+| Three Start/Stop cycles | First packets 0.890 / 0.701 / 0.709 s; Stop to idle 61.7 / 52.7 / 53.0 ms | Final patched packaged runtime, ports 15101–15103, `robustness.json` |
+| Restart after stall | First packet 0.691 s | Same runtime and real Frame |
+| Quit while streaming | No surviving helper at 2.021 s | Same runtime; final audit found no test FFmpeg/stimulus process |
+| Port 15099 occupied | App now offers a validated alternate port and matching copyable URL | OBS occupied 15099 while real packets arrived on alternate ports; UDP cannot identify or guarantee the receiver |
+| OBS before/after Start; receiver restarts | Live decoding verified, including recreated sources while relay stays active; an already-open stalled receiver may need hide/show or properties OK | Documented recovery, not automatic OBS control |
+| Standby/wake | Safe wake changed a blank mirror to visible room/panels | Private mirror and saved recordings |
+
+A forced SSH stall tests the transport failure and error/cleanup behavior.
+It does **not** prove real Wi-Fi loss or full headset suspend/resume. No physical
+network interface was disabled and no headset reset was performed. There is
+no automatic reconnect: restore connectivity and press Start. Valid blank
+standby frames do not trigger a packet timeout.
+
+## Windows and macOS
+
+**Windows controls remain hidden.** A disposable Windows 11 VM ran the final
+helper using the released app's bundled Python and a native executable SSH
+fixture. It stayed alive for three seconds without a UDP receiver, then sent
+1,316-byte packets when a receiver opened. Closing its control pipe returned
+exit 0 with no surviving SSH child (`windows-pipe.json`; stop measured below
+the VM timer's resolution in the final run). The helper hides the SSH console
+and tolerates Winsock's delayed UDP receiver-unreachable error.
+
+The real-headset Windows attempt delivered zero packets through a temporary
+host SSH bridge. Native Windows OBS, direct Windows-to-Frame SSH, firewall
+behavior and packaged app Start/Stop have therefore not passed end to end.
+No local FFmpeg was installed; encoding belongs on the Frame. No firewall
+exception, headset authorized key, or Windows scheduled task was installed.
+
+**macOS:** no physical Mac or macOS VM was available. Python tests and the
+five controller lifecycle tests run in the macOS CI matrix; these cannot
+establish capture performance, audio quality, packaged launch or OBS behavior
+on a physical Mac.
+
+## Validation and remaining limits
+
+Local suite: **1,514 Python tests passed, 16 skipped**, 46 app tests and 18
+site tests passed. The latest helper additionally passed all 11 focused OBS
+tests; the controller passed all five focused lifecycle tests. Cross-platform
+CI results belong to the linked PR, not these host measurements.
+
+Still unverified: perceptual listening, real-game audio routing, accurate
+default A/V sync, broad latency/performance across hosts, hours-long sessions,
+physical Wi-Fi drop/full suspend recovery, physical macOS and native Windows
+OBS. The app/docs now explain copyable URL/format, receiver recovery, port
+selection, passthrough privacy and OBS Virtual Camera's video-only limit.
+The Discord guide provides the corresponding audio-sharing choices.
+
+Cleanup completed: Steam and vrcompositor remained running, battery 98%,
+no test FFmpeg/stimulus process remained, UDP ports 15099/15101/15102/15103/15105
+were bindable, task guest SSH config and the temporary bridge were removed,
+and the owned headset lock was released. The disposable Windows VM was
+stopped with its disk retained. See `cleanup.json`.
@@ -0,0 +1,23 @@
+import json,subprocess,sys,statistics
+from pathlib import Path
+import numpy as np
+from scipy import signal
+video=Path(sys.argv[1]); root=video.parent
+v=np.frombuffer(subprocess.check_output(['ffmpeg','-v','error','-i',str(video),'-map','0:v','-vf','scale=64:36','-pix_fmt','rgb24','-f','rawvideo','-']),dtype=np.uint8).reshape(-1,36,64,3)
+a=np.frombuffer(subprocess.check_output(['ffmpeg','-v','error','-i',str(video),'-map','0:a','-ac','1','-ar','48000','-f','f32le','-']),dtype='<f4')
+# Locate the high contrast square marker, excluding the background's low variations.
+gray=v.astype(float).mean(axis=3); spread=np.percentile(gray,98,axis=0)-np.percentile(gray,2,axis=0)
+y,x=np.unravel_index(spread.argmax(),spread.shape); track=gray[:,y,x]; lo,hi=np.percentile(track,[2,98]); white=track>(lo+hi)/2;onsets=np.where(np.diff(white.astype(int))==1)[0]+1
+rms=np.sqrt(np.mean(a[:len(a)//480*480].reshape(-1,480)**2,axis=1)); audible=rms>.003;beeps=(np.where(np.diff(audible.astype(int))==1)[0]+1)/100
+beeps=beeps[np.r_[True,np.diff(beeps)>.1]]
+visual=onsets/30; offsets=[]
+for t in visual:
+ if len(beeps):
+  b=beeps[np.argmin(abs(beeps-t))]
+  if abs(b-t)<2:offsets.append(float((b-t)*1000))
+active=a[abs(a)>.003]; peaks,props=signal.find_peaks(rms,height=.003,distance=100)
+# Spectrum of one well inside a tone, with Hann window; harmonic distortion estimate.
+start=int((beeps[2]+.05)*48000) if len(beeps)>2 else 0;sample=a[start:start+4096];freq=np.fft.rfftfreq(len(sample),1/48000);power=abs(np.fft.rfft(sample*np.hanning(len(sample))))**2
+base=power[(freq>960)&(freq<1040)].sum();harm=sum(power[(freq>h*1000-40)&(freq<h*1000+40)].sum() for h in range(2,10))
+result={'duration_s':len(v)/30,'video_frames':len(v),'marker_pixel_xy':[int(x),int(y)],'marker_levels':[float(lo),float(hi)],'visual_markers_s':visual.tolist(),'audio_onsets_s':beeps.tolist(),'audio_minus_video_ms':offsets,'offset_median_ms':statistics.median(offsets) if offsets else None,'offset_min_max_ms':[min(offsets),max(offsets)] if offsets else None,'peak_dbfs':float(20*np.log10(abs(a).max())),'clipped_samples':int((abs(a)>=.999).sum()),'tone_frequency_hz':float(freq[power.argmax()]),'harmonics_to_fundamental_db':float(10*np.log10(harm/base)),'rms_peak':float(rms.max())}
+(root/(video.stem+'-analysis.json')).write_text(json.dumps(result,indent=2));np.save(root/(video.stem+'-marker-spread.npy'),spread);print(json.dumps(result,indent=2))
@@ -0,0 +1,136 @@
+{
+  "duration_s": 187.36666666666667,
+  "video_frames": 5621,
+  "marker_pixel_xy": [
+    50,
+    0
+  ],
+  "marker_levels": [
+    0.0,
+    255.0
+  ],
+  "visual_markers_s": [
+    9.766666666666667,
+    14.766666666666667,
+    19.766666666666666,
+    24.766666666666666,
+    29.766666666666666,
+    34.766666666666666,
+    39.766666666666666,
+    44.766666666666666,
+    49.766666666666666,
+    54.766666666666666,
+    59.766666666666666,
+    64.76666666666667,
+    69.76666666666667,
+    74.76666666666667,
+    79.76666666666667,
+    84.76666666666667,
+    89.76666666666667,
+    94.76666666666667,
+    99.76666666666667,
+    104.76666666666667,
+    109.76666666666667,
+    114.76666666666667,
+    119.76666666666667,
+    124.76666666666667,
+    129.76666666666668,
+    134.76666666666668,
+    139.76666666666668,
+    144.7,
+    149.7,
+    154.7,
+    159.7,
+    164.7,
+    169.7,
+    174.7,
+    179.7,
+    184.7
+  ],
+  "audio_onsets_s": [
+    9.34,
+    14.34,
+    19.34,
+    24.34,
+    29.34,
+    34.34,
+    39.34,
+    44.34,
+    49.34,
+    54.34,
+    59.34,
+    64.34,
+    69.34,
+    74.34,
+    79.34,
+    84.34,
+    89.34,
+    94.34,
+    99.34,
+    104.34,
+    109.34,
+    114.34,
+    119.34,
+    124.34,
+    129.34,
+    134.34,
+    139.34,
+    144.34,
+    149.34,
+    154.34,
+    159.34,
+    164.34,
+    169.34,
+    174.34,
+    179.34,
+    184.34
+  ],
+  "audio_minus_video_ms": [
+    -426.66666666666765,
+    -426.66666666666765,
+    -426.66666666666583,
+    -426.66666666666583,
+    -426.66666666666583,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666623,
+    -426.6666666666765,
+    -426.6666666666765,
+    -426.6666666666765,
+    -359.9999999999852,
+    -359.9999999999852,
+    -359.9999999999852,
+    -359.9999999999852,
+    -359.9999999999852,
+    -359.9999999999852,
+    -359.9999999999852,
+    -359.9999999999852,
+    -359.9999999999852
+  ],
+  "offset_median_ms": -426.6666666666623,
+  "offset_min_max_ms": [
+    -426.6666666666765,
+    -359.9999999999852
+  ],
+  "peak_dbfs": -13.2072114944458,
+  "clipped_samples": 0,
+  "tone_frequency_hz": 996.09375,
+  "harmonics_to_fundamental_db": -81.32048537168609,
+  "rms_peak": 0.15280573070049286
+}
@@ -0,0 +1,123 @@
+[
+  {
+    "duration_s": 21.033333333333335,
+    "video_frames": 631,
+    "marker_pixel_xy": [
+      50,
+      0
+    ],
+    "marker_levels": [
+      0.0,
+      255.0
+    ],
+    "visual_markers_s": [
+      4.9,
+      9.9,
+      14.9,
+      19.9
+    ],
+    "audio_onsets_s": [
+      4.42,
+      9.42,
+      14.42,
+      19.42
+    ],
+    "audio_minus_video_ms": [
+      -480.00000000000045,
+      -480.00000000000045,
+      -480.00000000000045,
+      -479.9999999999969
+    ],
+    "offset_median_ms": -480.00000000000045,
+    "offset_min_max_ms": [
+      -480.00000000000045,
+      -479.9999999999969
+    ],
+    "peak_dbfs": -13.202757835388184,
+    "clipped_samples": 0,
+    "tone_frequency_hz": 996.09375,
+    "harmonics_to_fundamental_db": -83.94567523863627,
+    "rms_peak": 0.15256504714488983,
+    "offset_ms": 0,
+    "recording": "2026-10-25 06-31-15.mkv"
+  },
+  {
+    "duration_s": 21.066666666666666,
+    "video_frames": 632,
+    "marker_pixel_xy": [
+      50,
+      0
+    ],
+    "marker_levels": [
+      0.0,
+      255.0
+    ],
+    "visual_markers_s": [
+      10.6,
+      15.6,
+      20.6
+    ],
+    "audio_onsets_s": [
+      5.62,
+      10.53,
+      15.53,
+      20.53
+    ],
+    "audio_minus_video_ms": [
+      -70.00000000000028,
+      -70.00000000000028,
+      -70.00000000000028
+    ],
+    "offset_median_ms": -70.00000000000028,
+    "offset_min_max_ms": [
+      -70.00000000000028,
+      -70.00000000000028
+    ],
+    "peak_dbfs": -13.215741157531738,
+    "clipped_samples": 0,
+    "tone_frequency_hz": 996.09375,
+    "harmonics_to_fundamental_db": -83.99685616364809,
+    "rms_peak": 0.15322808921337128,
+    "offset_ms": 400,
+    "recording": "2026-10-25 06-31-46.mkv"
+  },
+  {
+    "duration_s": 21.0,
+    "video_frames": 630,
+    "marker_pixel_xy": [
+      50,
+      0
+    ],
+    "marker_levels": [
+      0.0,
+      255.0
+    ],
+    "visual_markers_s": [
+      7.6,
+      12.6,
+      17.6
+    ],
+    "audio_onsets_s": [
+      7.6,
+      12.6,
+      17.6
+    ],
+    "audio_minus_video_ms": [
+      0.0,
+      0.0,
+      0.0
+    ],
+    "offset_median_ms": 0.0,
+    "offset_min_max_ms": [
+      0.0,
+      0.0
+    ],
+    "peak_dbfs": -13.219660758972168,
+    "clipped_samples": 0,
+    "tone_frequency_hz": 996.09375,
+    "harmonics_to_fundamental_db": -83.85259564406981,
+    "rms_peak": 0.15266509354114532,
+    "offset_ms": 480,
+    "recording": "2026-10-25 06-32-18.mkv"
+  }
+]
@@ -0,0 +1,22 @@
+import json,sys,time,subprocess,os
+from pathlib import Path
+sys.path.insert(0,'/tmp/obs-aacapv3evh');from control import OBS
+r=Path('/tmp/obs-aacapv3evh');o=OBS();
+try:o.request('RemoveInput',{'inputName':'Frame mirror'})
+except RuntimeError:pass
+time.sleep(1)
+h=subprocess.Popen([sys.executable,'scripts/obs-headset-source.py','--control-stdin'],stdin=subprocess.PIPE,stderr=(r/'calibration-initial-helper.log').open('w'))
+p=subprocess.Popen(['ssh','frame','XDG_RUNTIME_DIR=/run/user/1000 timeout 100 python3 /tmp/obs-aacapv3evh/stimulus.py'],stdout=(r/'calibration-initial-stimulus.jsonl').open('w'),stderr=(r/'calibration-initial-stimulus.log').open('w'))
+results=[]
+try:
+ for offset in (0,400,480):
+  name='Frame calibration '+str(offset)
+  data=o.request('CreateInput',{'sceneName':'Scene','inputName':name,'inputKind':'ffmpeg_source','inputSettings':{'is_local_file':False,'input':'udp://127.0.0.1:15099','input_format':'mpegts','buffering_mb':2,'restart_on_activate':True},'sceneItemEnabled':False})
+  o.request('SetInputAudioSyncOffset',{'inputName':name,'inputAudioSyncOffset':offset})
+  print('setting',o.request('GetInputAudioSyncOffset',{'inputName':name}),flush=True)
+  o.request('SetSceneItemEnabled',{'sceneName':'Scene','sceneItemId':data['sceneItemId'],'sceneItemEnabled':True})
+  time.sleep(7);o.request('StartRecord');time.sleep(21);rec=o.request('StopRecord');video=r/Path(rec['outputPath']).name
+  env=dict(os.environ,PYTHONPATH=str(r/'deps'));a=json.loads(subprocess.check_output([sys.executable,str(r/'analyse.py'),str(video)],env=env));a.update(offset_ms=offset,recording=video.name);results.append(a);print(json.dumps(a),flush=True)
+  o.request('RemoveInput',{'inputName':name})
+finally:
+ h.stdin.close();h.wait(timeout=10);p.terminate();p.wait(timeout=10);(r/'calibration-initial-result.json').write_text(json.dumps(results,indent=2))
@@ -0,0 +1,88 @@
+{
+  "offset_ms": 367,
+  "records": [
+    {
+      "duration_s": 19.966666666666665,
+      "video_frames": 599,
+      "marker_pixel_xy": [
+        50,
+        0
+      ],
+      "marker_levels": [
+        0.0,
+        255.0
+      ],
+      "visual_markers_s": [
+        6.133333333333334,
+        7.266666666666667,
+        12.266666666666667,
+        17.266666666666666
+      ],
+      "audio_onsets_s": [
+        6.9,
+        11.9,
+        16.9
+      ],
+      "audio_minus_video_ms": [
+        766.6666666666666,
+        -366.66666666666623,
+        -366.66666666666714,
+        -366.66666666666714
+      ],
+      "offset_median_ms": -366.6666666666667,
+      "offset_min_max_ms": [
+        -366.66666666666714,
+        766.6666666666666
+      ],
+      "peak_dbfs": -13.215461730957031,
+      "clipped_samples": 0,
+      "tone_frequency_hz": 996.09375,
+      "harmonics_to_fundamental_db": -84.12980132719696,
+      "rms_peak": 0.15284518897533417,
+      "phase": "before",
+      "recording": "2026-10-25 06-28-11.mkv"
+    },
+    {
+      "duration_s": 20.066666666666666,
+      "video_frames": 602,
+      "marker_pixel_xy": [
+        50,
+        0
+      ],
+      "marker_levels": [
+        0.0,
+        255.0
+      ],
+      "visual_markers_s": [
+        4.4,
+        9.4,
+        14.4,
+        19.4
+      ],
+      "audio_onsets_s": [
+        4.03,
+        9.03,
+        14.03,
+        19.03
+      ],
+      "audio_minus_video_ms": [
+        -370.0000000000001,
+        -370.000000000001,
+        -370.000000000001,
+        -369.99999999999744
+      ],
+      "offset_median_ms": -370.00000000000057,
+      "offset_min_max_ms": [
+        -370.000000000001,
+        -369.99999999999744
+      ],
+      "peak_dbfs": -13.167834281921387,
+      "clipped_samples": 0,
+      "tone_frequency_hz": 996.09375,
+      "harmonics_to_fundamental_db": -82.16381051643725,
+      "rms_peak": 0.15364883840084076,
+      "phase": "after",
+      "recording": "2026-10-25 06-28-34.mkv"
+    }
+  ]
+}
@@ -0,0 +1,16 @@
+{
+  "bindable_udp_ports": [
+    15099,
+    15101,
+    15102,
+    15103,
+    15105
+  ],
+  "remote_task_ffmpeg_and_stimulus_processes": 0,
+  "steam_and_vrcompositor_running": true,
+  "battery_percent": 98,
+  "headset_lock_released": true,
+  "guest_task_ssh_host_block_removed": true,
+  "temporary_ssh_bridge_stopped": true,
+  "persistent_headset_authentication_changes": false
+}
@@ -0,0 +1,46 @@
+{
+  "duration_s": 36.06666666666667,
+  "video_frames": 1082,
+  "marker_pixel_xy": [
+    50,
+    0
+  ],
+  "marker_levels": [
+    0.0,
+    255.0
+  ],
+  "visual_markers_s": [
+    9.433333333333334,
+    14.433333333333334,
+    19.433333333333334,
+    24.433333333333334,
+    29.433333333333334,
+    34.43333333333333
+  ],
+  "audio_onsets_s": [
+    9.35,
+    14.35,
+    19.35,
+    24.35,
+    29.35,
+    34.35
+  ],
+  "audio_minus_video_ms": [
+    -83.33333333333393,
+    -83.33333333333393,
+    -83.33333333333215,
+    -83.33333333333215,
+    -83.33333333333215,
+    -83.3333333333286
+  ],
+  "offset_median_ms": -83.33333333333215,
+  "offset_min_max_ms": [
+    -83.33333333333393,
+    -83.3333333333286
+  ],
+  "peak_dbfs": -13.15299129486084,
+  "clipped_samples": 0,
+  "tone_frequency_hz": 996.09375,
+  "harmonics_to_fundamental_db": -82.4335935832891,
+  "rms_peak": 0.15312190353870392
+}
@@ -0,0 +1,13 @@
+{
+  "clock": {
+    "rtt": 0.0034094941802322865,
+    "offset_remote_minus_host": -2894789.9195547644
+  },
+  "hits": [
+    {
+      "source_index": 1000,
+      "delay_ms": 1431.418131571263,
+      "query_ms": 11.743285227566957
+    }
+  ]
+}
@@ -0,0 +1,25 @@
+{
+    "programs": [
+
+    ],
+    "streams": [
+        {
+            "codec_name": "h264",
+            "width": 1920,
+            "height": 1080,
+            "r_frame_rate": "30/1",
+            "nb_read_frames": "153"
+        },
+        {
+            "codec_name": "aac",
+            "sample_rate": "48000",
+            "channels": 2,
+            "r_frame_rate": "0/0",
+            "nb_read_frames": "233"
+        }
+    ],
+    "format": {
+        "duration": "5.121000",
+        "size": "3932019"
+    }
+}
@@ -0,0 +1,10 @@
+{
+  "elapsed_s": 7.434504003729671,
+  "result": {
+    "state": "saved",
+    "file": "/tmp/obs-aacapv3evh/mp4/rec-20261025-062251.mp4",
+    "audio": true,
+    "seconds": 5,
+    "message": "Saved rec-20261025-062251.mp4 to /tmp OBS evidence"
+  }
+}
@@ -0,0 +1,210 @@
+{
+  "result": {
+    "outputPath": "/evidence/2026-10-25 06-08-22.mkv"
+  },
+  "samples": [
+    {
+      "elapsed": 30.000104404054582,
+      "obs": {
+        "activeFps": 30.000000300000007,
+        "availableDiskSpace": 9068.64453125,
+        "averageFrameRenderTime": 18.458413,
+        "cpuUsage": 20.24916849878798,
+        "memoryUsage": 543.7109375,
+        "outputSkippedFrames": 0,
+        "outputTotalFrames": 959,
+        "renderSkippedFrames": 4,
+        "renderTotalFrames": 1783,
+        "webSocketSessionIncomingMessages": 14,
+        "webSocketSessionOutgoingMessages": 16
+      },
+      "record": {
+        "outputActive": true,
+        "outputBytes": 2243010,
+        "outputDuration": 30866,
+        "outputPaused": false,
+        "outputTimecode": "00:00:30.866"
+      },
+      "app": {
+        "state": "running",
+        "alias": "frame",
+        "error": "",
+        "supported": true
+      }
+    },
+    {
+      "elapsed": 60.002103955019265,
+      "obs": {
+        "activeFps": 30.000000300000007,
+        "availableDiskSpace": 8942.09375,
+        "averageFrameRenderTime": 13.660508,
+        "cpuUsage": 23.863888888888887,
+        "memoryUsage": 544.56640625,
+        "outputSkippedFrames": 0,
+        "outputTotalFrames": 1859,
+        "renderSkippedFrames": 5,
+        "renderTotalFrames": 2683,
+        "webSocketSessionIncomingMessages": 16,
+        "webSocketSessionOutgoingMessages": 18
+      },
+      "record": {
+        "outputActive": true,
+        "outputBytes": 4951606,
+        "outputDuration": 60866,
+        "outputPaused": false,
+        "outputTimecode": "00:01:00.866"
+      },
+      "app": {
+        "state": "running",
+        "alias": "frame",
+        "error": "",
+        "supported": true
+      }
+    },
+    {
+      "elapsed": 90.0040782331489,
+      "obs": {
+        "activeFps": 30.000000300000007,
+        "availableDiskSpace": 8900.6015625,
+        "averageFrameRenderTime": 12.110281,
+        "cpuUsage": 23.680555555555557,
+        "memoryUsage": 545.74609375,
+        "outputSkippedFrames": 0,
+        "outputTotalFrames": 2759,
+        "renderSkippedFrames": 13,
+        "renderTotalFrames": 3583,
+        "webSocketSessionIncomingMessages": 18,
+        "webSocketSessionOutgoingMessages": 20
+      },
+      "record": {
+        "outputActive": true,
+        "outputBytes": 7552329,
+        "outputDuration": 90866,
+        "outputPaused": false,
+        "outputTimecode": "00:01:30.866"
+      },
+      "app": {
+        "state": "running",
+        "alias": "frame",
+        "error": "",
+        "supported": true
+      }
+    },
+    {
+      "elapsed": 120.0062853959389,
+      "obs": {
+        "activeFps": 30.000000300000007,
+        "availableDiskSpace": 8603.08984375,
+        "averageFrameRenderTime": 14.892247,
+        "cpuUsage": 24.66111111111111,
+        "memoryUsage": 546.52734375,
+        "outputSkippedFrames": 0,
+        "outputTotalFrames": 3659,
+        "renderSkippedFrames": 13,
+        "renderTotalFrames": 4483,
+        "webSocketSessionIncomingMessages": 20,
+        "webSocketSessionOutgoingMessages": 22
+      },
+      "record": {
+        "outputActive": true,
+        "outputBytes": 10124530,
+        "outputDuration": 120866,
+        "outputPaused": false,
+        "outputTimecode": "00:02:00.866"
+      },
+      "app": {
+        "state": "running",
+        "alias": "frame",
+        "error": "",
+        "supported": true
+      }
+    },
+    {
+      "elapsed": 150.00849257130176,
+      "obs": {
+        "activeFps": 30.000000300000007,
+        "availableDiskSpace": 8484.58203125,
+        "averageFrameRenderTime": 15.3434,
+        "cpuUsage": 23.169444444444444,
+        "memoryUsage": 548.5546875,
+        "outputSkippedFrames": 0,
+        "outputTotalFrames": 4559,
+        "renderSkippedFrames": 78,
+        "renderTotalFrames": 5383,
+        "webSocketSessionIncomingMessages": 22,
+        "webSocketSessionOutgoingMessages": 24
+      },
+      "record": {
+        "outputActive": true,
+        "outputBytes": 12643085,
+        "outputDuration": 150833,
+        "outputPaused": false,
+        "outputTimecode": "00:02:30.833"
+      },
+      "app": {
+        "state": "running",
+        "alias": "frame",
+        "error": "",
+        "supported": true
+      }
+    },
+    {
+      "elapsed": 180.01099411491305,
+      "obs": {
+        "activeFps": 30.000000300000007,
+        "availableDiskSpace": 8382.75,
+        "averageFrameRenderTime": 31.402812,
+        "cpuUsage": 23.717094301899365,
+        "memoryUsage": 548.51953125,
+        "outputSkippedFrames": 0,
+        "outputTotalFrames": 5459,
+        "renderSkippedFrames": 90,
+        "renderTotalFrames": 6283,
+        "webSocketSessionIncomingMessages": 24,
+        "webSocketSessionOutgoingMessages": 26
+      },
+      "record": {
+        "outputActive": true,
+        "outputBytes": 15130232,
+        "outputDuration": 180833,
+        "outputPaused": false,
+        "outputTimecode": "00:03:00.833"
+      },
+      "app": {
+        "state": "running",
+        "alias": "frame",
+        "error": "",
+        "supported": true
+      }
+    },
+    {
+      "elapsed": 185.01674677524716,
+      "obs": {
+        "activeFps": 30.000000300000007,
+        "availableDiskSpace": 8366.79296875,
+        "averageFrameRenderTime": 22.859219,
+        "cpuUsage": 23.766666666666666,
+        "memoryUsage": 510.28515625,
+        "outputSkippedFrames": 0,
+        "outputTotalFrames": 5609,
+        "renderSkippedFrames": 90,
+        "renderTotalFrames": 6433,
+        "webSocketSessionIncomingMessages": 26,
+        "webSocketSessionOutgoingMessages": 28
+      },
+      "record": {
+        "outputActive": true,
+        "outputBytes": 15580161,
+        "outputDuration": 185833,
+        "outputPaused": false,
+        "outputTimecode": "00:03:05.833"
+      },
+      "app": {
+        "state": "running",
+        "alias": "frame",
+        "error": "",
+        "supported": true
+      }
+    }
+  ]
+}
@@ -0,0 +1,26 @@
+[
+  {
+    "name": "2026-10-25 06-08-22.mkv",
+    "bytes": 15784412,
+    "sha256": "f2760ed28bf48274cc8c936428edbc389cd3a9f4b9cd2a61e699a04bf4487b50",
+    "published": false
+  },
+  {
+    "name": "rec-20261025-062251.mp4",
+    "bytes": 3932019,
+    "sha256": "c71de1a49b75159c587fddd012361b9e6626a4d5cc41b79696343a17b73c151a",
+    "published": false
+  },
+  {
+    "name": "mirror-wake.png",
+    "bytes": 1741004,
+    "sha256": "0754466948d5b9e8448f9ed67c8582e19802367df6ed4002afc64f42e1763f53",
+    "published": false
+  },
+  {
+    "name": "private-mp4-frame4.png",
+    "bytes": 1002068,
+    "sha256": "08d87bc9ab0e62115b42cca7dfcf7e4db11848a0ede273034a92a69297c6775b",
+    "published": false
+  }
+]
@@ -0,0 +1,15 @@
+{
+  "baseline": "d79efb4",
+  "after_stop": {
+    "state": "stopping",
+    "alias": "frame",
+    "error": "",
+    "supported": true
+  },
+  "after_late_stderr": {
+    "state": "running",
+    "alias": "frame",
+    "error": "",
+    "supported": true
+  }
+}
@@ -0,0 +1,70 @@
+[
+  {
+    "test": "start-stop",
+    "cycle": 1,
+    "port": 15101,
+    "first_packet_s": 0.890392117202282,
+    "packet_bytes": 1316,
+    "stop_s": 0.06173023069277406,
+    "state": {
+      "state": "idle",
+      "alias": "frame",
+      "port": 15101,
+      "error": "",
+      "supported": true
+    }
+  },
+  {
+    "test": "start-stop",
+    "cycle": 2,
+    "port": 15102,
+    "first_packet_s": 0.7008698149584234,
+    "packet_bytes": 1316,
+    "stop_s": 0.0526565620675683,
+    "state": {
+      "state": "idle",
+      "alias": "frame",
+      "port": 15102,
+      "error": "",
+      "supported": true
+    }
+  },
+  {
+    "test": "start-stop",
+    "cycle": 3,
+    "port": 15103,
+    "first_packet_s": 0.7092029112391174,
+    "packet_bytes": 1316,
+    "stop_s": 0.052990387193858624,
+    "state": {
+      "state": "idle",
+      "alias": "frame",
+      "port": 15103,
+      "error": "",
+      "supported": true
+    }
+  },
+  {
+    "test": "stalled-ssh",
+    "ssh_pid": 3025339,
+    "elapsed_s": 15.008651106152683,
+    "state": {
+      "state": "failed",
+      "alias": "frame",
+      "port": 15105,
+      "error": "OBS source stopped (1). The Frame OBS video stopped for 10 seconds",
+      "supported": true
+    },
+    "helper_gone": true,
+    "ssh_gone": true
+  },
+  {
+    "test": "restart-after-stall",
+    "first_packet_s": 0.6910299891605973
+  },
+  {
+    "test": "quit-streaming",
+    "checked_after_s": 2.020789209753275,
+    "surviving_helpers": []
+  }
+]
@@ -0,0 +1,46 @@
+import ctypes as C, json, math, os, signal, struct, subprocess, sys, threading, time
+# Put frame_media_player.py and its two imports beside this helper on the Frame.
+sys.path.insert(0, os.path.dirname(__file__))
+from frame_media_player import Overlay, OverlayBusy
+os.environ['XDG_RUNTIME_DIR']='/run/user/1000'
+class Spec(C.Structure):
+    _fields_=[('format',C.c_int),('rate',C.c_uint32),('channels',C.c_uint8)]
+class Attr(C.Structure):
+    _fields_=[(k,C.c_uint32) for k in ('maxlength','tlength','prebuf','minreq','fragsize')]
+p=C.CDLL('libpulse-simple.so.0'); p.pa_simple_new.restype=C.c_void_p
+p.pa_simple_new.argtypes=[C.c_char_p,C.c_char_p,C.c_int,C.c_char_p,C.c_char_p,C.POINTER(Spec),C.c_void_p,C.POINTER(Attr),C.POINTER(C.c_int)]
+p.pa_simple_write.argtypes=[C.c_void_p,C.c_void_p,C.c_size_t,C.POINTER(C.c_int)]
+p.pa_simple_get_latency.argtypes=[C.c_void_p,C.POINTER(C.c_int)];p.pa_simple_get_latency.restype=C.c_uint64
+p.pa_simple_free.argtypes=[C.c_void_p]
+err=C.c_int(); spec=Spec(3,48000,2); attr=Attr(0xffffffff,9600,0,1920,0xffffffff)
+stream=p.pa_simple_new(None,b'OBS validation',1,None,b'aligned marker',C.byref(spec),None,C.byref(attr),C.byref(err))
+if not stream: raise RuntimeError('pulse '+str(err.value))
+vr=Overlay(); handle=vr.create('framecontrol.obs.validation.aacapv3evh',2,1.5,order=100)
+quit=threading.Event(); events=[]
+signal.signal(signal.SIGTERM,lambda *_:quit.set())
+def wake():
+    while not quit.is_set():
+        subprocess.run(['/opt/steamvr/bin/linuxarm64/vrcmd','--handlewakeup'],stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL)
+        quit.wait(1)
+threading.Thread(target=wake,daemon=True).start()
+try:
+    previous=False
+    for i in range(19000):
+        if quit.is_set():break
+        tone= i>=500 and (i-500)%500<20
+        block=b''.join(struct.pack('<hh',int(5000*math.sin(2*math.pi*1000*(i*480+j)/48000)) if tone else 0,int(5000*math.sin(2*math.pi*1000*(i*480+j)/48000)) if tone else 0) for j in range(480))
+        b=C.create_string_buffer(block)
+        if p.pa_simple_write(stream,b,len(block),C.byref(err)):raise RuntimeError('write '+str(err.value))
+        if tone != previous or i==0:
+            latency=p.pa_simple_get_latency(stream,C.byref(err))/1e6
+            expected=time.monotonic()+latency-.01
+            time.sleep(max(0,expected-time.monotonic()))
+            before=time.monotonic()
+            try:vr.pixels(handle,(b'\xff\xff\xff\xff' if tone else b'\x00\x00\x00\xff')*64*64,64,64)
+            except OverlayBusy:continue
+            after=time.monotonic()
+            event={'tone':tone,'index':i,'expected_audio':expected,'visual_submit':before,'visual_return':after,'submit_minus_audio_ms':(before-expected)*1000,'pulse_latency_ms':latency*1000}
+            print(json.dumps(event),flush=True); events.append(event)
+        previous=tone
+finally:
+    quit.set();vr.close();p.pa_simple_free(stream)
@@ -0,0 +1,10 @@
+{
+  "alive_without_receiver": true,
+  "platform": "win32",
+  "has_udp_connreset": false,
+  "packet_bytes": 1316,
+  "ssh_pid": 2668,
+  "stop_seconds": 0.0,
+  "helper_exit": 0,
+  "ssh_child_alive": false
+}
@@ -0,0 +1,178 @@
+# Keyboard and trackpad through gamescope, 2026-10-24
+
+PR: [#66](https://github.com/saphid/frame-control/pull/66), `pad-gamescope`.
+Parent/main: v0.4.18 commit `0da1fe5`. Merge commit: `1737366`, with parents
+`cba23fb` (the existing PR) and `0da1fe5` (main). No history was rewritten.
+
+## Merge and implementation
+
+Both `/api/input` (keyboard/trackpad) and `/api/touch` (live-view Control)
+start and poll the gamescope helper. KDE Connect starts only when Unicode
+typing needs it. The existing ordered, bounded queue and switch cancellation
+remain in place; cross-service typing order is an estimate, not an application
+acknowledgement.
+
+The merge keeps main's intended-device validation and work reservation before
+a GET starts an input helper, immutable SSH routes, launch generations and
+serialized writes. Switching headsets also stops the power report and resets
+both input agents and queued typing before publishing the new route. The page
+keeps main's Tools sections, clipboard controls and single instances of the
+keyboard/trackpad and VR tools, with the PR's gamescope help text.
+
+The start/status regression tests now exercise the gamescope helper for both
+endpoints. An explicit `/api/input` test checks that start and poll use that
+helper without starting KDE Connect. Existing stale/missing-headset and
+route-reservation tests remain active.
+
+## Real Frame: focused click and ASCII keys received
+
+Host: lxso2, `ssh frame`. SteamOS **0.5.6**, BUILD_ID **20261015.6141207**,
+SteamVR **2.18.2**. At **11:05 UTC**, Game Mode was active, full Plasma was
+inactive, Steam and SteamVR were running, battery was **99%**, and gamescope's
+focusable/focused window lists were empty. The shared test lock was absent.
+Existing X11 tools and libX11 were available; Tk could not load its library.
+
+At **11:09:23 UTC**, an initial read-only preflight saw no focused window
+but activity level **0** (idle), rather than the required **3** (standby), and
+aborted before lock acquisition or input. At **11:09:57 UTC**, another task
+held the shared lock with a focused panel; that lock and panel were left alone.
+
+At **11:20:22 UTC**, read-only checks found the lock absent, no focused or
+focusable windows, activity **3** and battery **98%**. The bounded probe ran at
+**11:20:37 UTC** against implementation commit `5641d3c`:
+
+1. Rechecked empty focus and standby, acquired `/tmp/frame-test.lock` with
+   atomic `mkdir`, wrote a unique owner marker and rechecked both conditions.
+2. Created only a disposable 640×400 X11 event-recorder window on `:0`, tagged
+   with test app ID `2000999066`. It had a 45-second alarm and closed on stdin
+   EOF. No existing application, full desktop or dashboard was started.
+3. Waited for gamescope to report that exact window (`62914561`) focused.
+   Started the production server's `TouchAgent` over SSH; it reported ready.
+4. Called production `server.remote_touch` for positioning, then
+   `server.remote_input` with a left click, `Frame66` and the Enter key button.
+   Both responses reported `sent: true`. More importantly, the **window itself
+   recorded ButtonPress/Release (button 1), the ASCII key events in order and
+   Return**. `XLookupString` decoded exactly `Frame66\r`. The events were
+   delivered through gamescope's EIS socket, not fabricated with XSendEvent.
+5. Closed the helper by EOF and waited for exit, closed the recorder, checked
+   empty focus and standby, then removed only the owner-matching test lock.
+
+[State and received events](pad-gamescope-2026-10-24/readback.json) and the
+[probe](pad-gamescope-2026-10-24/probe.py)/[X11 recorder](pad-gamescope-2026-10-24/recorder.py)
+are retained. The archived scripts use checkout-relative source paths; the
+recorded run used the same harness from `/tmp`. Motion records omit an unused
+field that only has meaning for key/button events.
+
+Delayed readback at **11:21:46 UTC** confirmed no test lock or recorder process,
+empty focused/focusable lists, Game Mode active, full Plasma inactive, activity
+3 and battery 98%. The original Steam and vrserver PIDs were unchanged. No
+install, security/global setting change, dashboard/session switch, reset or
+reboot was performed. No headset helper or owned lock remained.
+
+This establishes **focused-panel click and ASCII key delivery on `:0`**.
+It does not establish wearer-visible presentation, Unicode delivery or GUI
+interaction. The absolute-position setup reached the recorder's edge
+(639,399), rather than its centre; pixel-accurate absolute pointing is **not**
+proved by this small-window probe. The trackpad click and typed keys still
+arrived in the owned focused window. The original PR's earlier acceptance-only
+observations remain historical; this observation adds actual window events.
+
+## Offline checks and remaining limits
+
+- `python3 -m unittest discover -s tests -p test_input.py -v`: **58 passed**.
+- `python3 -m unittest discover -s tests -p test_touch.py -v`: **43 passed**.
+- `python3 -m unittest discover -s tests -p test_service_regressions.py -v`:
+  **34 passed**.
+- `python3 -m unittest discover -s tests -v`: **1,403 ran, OK, 15 skipped**
+  (Linux x86_64, Python 3.12; 150.825 seconds).
+- Full fake-Frame e2e in task-specific Docker project `frame-control-pr66`:
+  **47 passed** after the lock fix (192.270 seconds). Both task containers,
+  their network and all three volumes were removed afterward. The run emitted
+  an unclosed test-socket ResourceWarning; the suite returned OK.
+- Node page suites: `ctrl_gestures.mjs`, `pad_queue.mjs`, `desk_panels.mjs`
+  passed, using the production page functions.
+- `node --test app/test/*.test.js`: **3 test files passed**.
+- `node --test site/test/*.test.mjs`: **2 test files passed**.
+- Python compilation, desktop/site JavaScript syntax and `git diff --check`
+  passed. Fake-Frame e2e and exact-head CI results are recorded in the PR after completion.
+
+The first full regression run executed 1,401 tests and found two tests still
+expecting `/api/input` to start the old KDE Connect helper. They were updated
+to the intended gamescope route. The final full run includes the lazy-KDE
+regression above and the lock-order regression below. The initial restricted-sandbox input run could not open
+loopback sockets; the focused rerun with managed network access passed.
+
+Review of the merged code then found a lock inversion: the Unicode worker
+held the pad-send lock while `InputAgent.start()` acquired the route lock,
+whereas a headset switch held the route lock before resetting the pad. A
+bounded subprocess regression reproduced the deadlock with the real
+`InputAgent.send/start` methods and an offline launch stub. Unicode delivery
+and resets now take the route lock before the pad lock; the route lock is
+reentrant so an agent can capture its route inside that reservation. The new
+regression passed after the fix, as did all **58 focused input tests** and
+the **1,403-test full suite** (15 skipped). The local fake-Frame suite also
+passed **47 tests after this fix**. Exact-head CI results are recorded in the PR.
+
+Remaining device work requires an idle, available Frame and the shared lock:
+verify Unicode in a real text field, ordering under real typing load and
+precise absolute pointing for small panels. Worn-headset presentation,
+packaged Electron pointer lock and Windows GUI execution remain separate
+checks. Automated Windows/macOS CI does not establish those interactions.
+
+
+## Review round 2: queue saturation and failure recovery
+
+The coordinator identified silent eviction in both `_queue_for_kde()` and the
+worker's retry path. Both sliced the oldest accepted events off at 200 entries,
+even though the page had already received `sent: true` and discarded its copy.
+
+Admission now serializes concurrent requests, checks capacity before any pointer
+or keyboard send, and returns `sent: false, state: waiting` if the whole batch
+will not fit. Text stays in the bounded queue while in flight, and is removed
+only after the helper accepts it. Rejected mixed batches send no clicks; retrying
+them cannot duplicate clicks already sent by this server. The page polls until
+it can retry. Pointer input stays usable while accepted text is pending.
+
+The old worker also left its worker marker and one-hour timing sentinel behind
+if `send()` raised. Failure/timeout handling now retains unsent text, clears the
+worker/timing state and exposes an error through input status. The page polls
+accepted text without requiring another keypress. **Try again** explicitly
+restarts the retained queue. Thread-start failures follow the same retention
+rule. A stale worker's exception cannot change the new route's state.
+
+The proposed send-to-enqueue headset-switch race was not reachable through the
+normal HTTP switch path: `Handler.do_POST()` reserves `working(meant)` across
+both operations; `devices_post()` shares `_work_lock` and refuses a moving
+operation while work is active. Connector configuration/reconnect paths defer
+changed headsets while work runs. A production-handler regression attempts a
+switch at both send and enqueue and passes even on the previous implementation.
+No separate connector change was needed. Atomic queue admission now uses the
+existing route-before-pad lock order as well, because starting either input
+agent can capture its route synchronously.
+
+Three deterministic saturation regressions fail on `215db7b` and pass with the
+fix: capacity during the typing delay, capacity during an unsuccessful-send
+retry, and two concurrent producers competing for the last slots. They check
+exact accepted event sequences, reject a mixed click/text batch before its
+pointer effects, and verify delivery exactly once after retry. Additional tests
+cover explicit recovery after timeout, helper errors, send exceptions and
+thread-start failure, stale-worker isolation, HTTP status/start behavior, and
+the production page's polling/error behavior.
+
+No new active headset test was performed: this change affects host queue
+admission/recovery and status handling, not Frame event translation or injection.
+The earlier real click/ASCII evidence remains scoped to its recorded commit.
+Real Unicode, packaged Electron pointer lock, Windows GUI, wearer-visible
+presentation and precise small-window absolute positioning remain unverified.
+`sent: true` means accepted by this server, not application delivery. The queue
+is in memory; switching headsets cancels it and server exit loses it. A transport
+failure after a partial write can still make delivery ambiguous; this is not an
+end-to-end exactly-once protocol.
+
+Round 2 local verification: **141 focused input/touch/service tests passed**
+(62 input, 43 touch, 36 service; 20.061 seconds), and **1,409 server tests ran, OK, 15 skipped**
+(Linux x86_64, Python 3.12, 153.198 seconds). All three production-page Node
+suites passed; app tests passed (3 files), site tests passed (2 files), Python
+compilation and `git diff --check` passed. The existing skipped tests require
+zsh, macOS/Swift or built native PC libraries. Current-head CI is tracked in
+PR #66; the previous 47-test local fake-Frame run above is historical.
@@ -0,0 +1,129 @@
+"""Active real-Frame evidence probe: aborts unless idle, then owns the shared lock.
+
+Run manually on an authorised host: python3 docs/evidence/pad-gamescope-2026-10-24/probe.py
+The recorded run used /tmp paths; archived paths are relative to this checkout.
+"""
+import base64
+import datetime
+import json
+import os
+from pathlib import Path
+import queue
+import shlex
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import uuid
+
+ROOT = Path(__file__).resolve().parents[3]
+data = tempfile.TemporaryDirectory(prefix='pr66-live-')
+os.environ.update(FRAME_CONTROL_DATA_DIR=data.name, FRAME_CONTROL_TELEMETRY='0', FRAME_PRIVATE_SSH='1')
+sys.path.insert(0, str(ROOT / 'ui'))
+import server
+
+SSH = ['ssh', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=5', 'frame']
+owner = 'pr66-' + uuid.uuid4().hex
+result = {'time': datetime.datetime.now(datetime.timezone.utc).isoformat(), 'owner': owner,
+          'base': '0da1fe5', 'route': 'production server.remote_input -> TouchAgent SSH -> frame_touch.py -> gamescope EIS',
+          'events': []}
+recorder = None
+locked = False
+rows = queue.Queue()
+
+def ssh(cmd):
+    return subprocess.run([*SSH, cmd], capture_output=True, text=True, timeout=15, check=True).stdout
+
+def focus():
+    return json.loads(server.ssh('python3 - focus', stdin=(ROOT/'ui/frame_touch.py').read_text(), timeout=15))
+
+def activity():
+    return json.loads(ssh('/opt/steamvr/bin/linuxarm64/vrcmd --stats'))[0]['activity_level']
+
+def read_rows():
+    for raw in recorder.stdout:
+        rows.put(json.loads(raw))
+
+def collect(seconds):
+    end = time.monotonic() + seconds
+    while time.monotonic() < end:
+        try:
+            result['events'].append(rows.get(timeout=max(0.01, end-time.monotonic())))
+        except queue.Empty:
+            break
+
+try:
+    result['initial_focus'] = focus()
+    result['initial_activity'] = activity()
+    assert not result['initial_focus'].get('window'), 'existing focused panel; do not interrupt'
+    assert result['initial_activity'] == 3, 'headset is not in standby'
+    ssh('mkdir /tmp/frame-test.lock && printf %s ' + shlex.quote(owner) + ' > /tmp/frame-test.lock/owner')
+    locked = True
+    result['lock_acquired'] = True
+    assert not focus().get('window') and activity() == 3, 'session changed during lock acquisition'
+    code = base64.b64encode(Path(__file__).with_name('recorder.py').read_bytes()).decode()
+    command = 'python3 -u -c ' + shlex.quote("import base64;exec(compile(base64.b64decode('" + code + "'),'pr66-recorder','exec'))")
+    recorder = subprocess.Popen([*SSH, command], stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                stderr=subprocess.PIPE, text=True)
+    threading.Thread(target=read_rows, daemon=True).start()
+    initial = rows.get(timeout=8)
+    result['recorder'] = initial
+    assert initial.get('ready'), initial
+    window = initial['window']
+    for _ in range(20):
+        current = focus()
+        if current.get('window') == window:
+            break
+        time.sleep(0.2)
+    result['focused_panel'] = current
+    assert current.get('window') == window and current.get('display') == ':0', 'owned panel did not obtain focus; no input sent'
+    server.remote_input({})
+    for _ in range(50):
+        if server._touch.status.get('state') in ('ready', 'error'):
+            break
+        time.sleep(0.1)
+    result['agent_status'] = dict(server._touch.status)
+    assert result['agent_status'].get('state') == 'ready', result['agent_status']
+    target = {'window': window, 'display': ':0'}
+    assert focus().get('window') == window and activity() == 3
+    result['position_response'] = server.remote_touch({'events': [dict(target, fx=0.5, fy=0.5)]})
+    time.sleep(0.2)
+    assert focus().get('window') == window and activity() == 3
+    result['pad_response'] = server.remote_input({'events': [{'singleclick': True}, {'key': 'Frame66'}, {'specialKey': 12}]})
+    collect(2)
+    received = result['events']
+    result['received_text'] = ''.join(e.get('text', '') for e in received if e.get('type') == 2)
+    result['click_received'] = any(e.get('type') == 4 and e.get('code') == 1 and e.get('window') == window for e in received)
+    result['release_received'] = any(e.get('type') == 5 and e.get('code') == 1 and e.get('window') == window for e in received)
+    result['passed'] = result['click_received'] and result['release_received'] and result['received_text'] == 'Frame66\r'
+    assert result['passed'], 'event recorder did not observe expected click and keys'
+except Exception as e:
+    result['error'] = str(e)
+finally:
+    proc = server._touch.proc
+    server.reset_pad_route()
+    if proc:
+        try:
+            proc.wait(timeout=8)
+            result['input_helper_exited'] = True
+        except subprocess.TimeoutExpired:
+            proc.terminate()
+            proc.wait(timeout=5)
+            result['input_helper_terminated'] = True
+    if recorder:
+        recorder.stdin.close()
+        recorder.wait(timeout=8)
+        collect(0.2)
+        result['recorder_exit'] = recorder.returncode
+        result['recorder_stderr'] = recorder.stderr.read()[-1000:]
+    if locked:
+        result['final_focus'] = focus()
+        result['final_activity'] = activity()
+        ssh('test "$(cat /tmp/frame-test.lock/owner)" = ' + shlex.quote(owner)
+            + ' && rm /tmp/frame-test.lock/owner && rmdir /tmp/frame-test.lock')
+        result['owned_lock_released'] = True
+    Path('/tmp/pr66-live.json').write_text(json.dumps(result, indent=2) + '\n')
+    print(json.dumps(result, indent=2))
+    data.cleanup()
+sys.exit(0 if result.get('passed') else 1)
@@ -0,0 +1,280 @@
+{
+  "time": "2026-10-24T11:20:37.392607+00:00",
+  "owner": "pr66-7c2a8e8851f449bcb0bb6a040be94d99",
+  "base": "0da1fe5",
+  "route": "production server.remote_input -> TouchAgent SSH -> frame_touch.py -> gamescope EIS",
+  "events": [
+    {
+      "type": 6,
+      "window": 62914561,
+      "x": 320,
+      "y": 200,
+      "synthetic": false
+    },
+    {
+      "type": 6,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "synthetic": false
+    },
+    {
+      "type": 4,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 1,
+      "synthetic": false
+    },
+    {
+      "type": 5,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 1,
+      "synthetic": false
+    },
+    {
+      "type": 2,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 50,
+      "synthetic": false,
+      "text": "",
+      "keysym": 65505
+    },
+    {
+      "type": 2,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 41,
+      "synthetic": false,
+      "text": "F",
+      "keysym": 70
+    },
+    {
+      "type": 3,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 41,
+      "synthetic": false
+    },
+    {
+      "type": 3,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 50,
+      "synthetic": false
+    },
+    {
+      "type": 2,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 27,
+      "synthetic": false,
+      "text": "r",
+      "keysym": 114
+    },
+    {
+      "type": 3,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 27,
+      "synthetic": false
+    },
+    {
+      "type": 2,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 38,
+      "synthetic": false,
+      "text": "a",
+      "keysym": 97
+    },
+    {
+      "type": 3,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 38,
+      "synthetic": false
+    },
+    {
+      "type": 2,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 58,
+      "synthetic": false,
+      "text": "m",
+      "keysym": 109
+    },
+    {
+      "type": 3,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 58,
+      "synthetic": false
+    },
+    {
+      "type": 2,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 26,
+      "synthetic": false,
+      "text": "e",
+      "keysym": 101
+    },
+    {
+      "type": 3,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 26,
+      "synthetic": false
+    },
+    {
+      "type": 2,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 15,
+      "synthetic": false,
+      "text": "6",
+      "keysym": 54
+    },
+    {
+      "type": 3,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 15,
+      "synthetic": false
+    },
+    {
+      "type": 2,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 15,
+      "synthetic": false,
+      "text": "6",
+      "keysym": 54
+    },
+    {
+      "type": 3,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 15,
+      "synthetic": false
+    },
+    {
+      "type": 2,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 36,
+      "synthetic": false,
+      "text": "\r",
+      "keysym": 65293
+    },
+    {
+      "type": 3,
+      "window": 62914561,
+      "x": 639,
+      "y": 399,
+      "code": 36,
+      "synthetic": false
+    },
+    {
+      "cleaned": true
+    }
+  ],
+  "initial_focus": {
+    "window": null
+  },
+  "initial_activity": 3,
+  "lock_acquired": true,
+  "recorder": {
+    "ready": true,
+    "window": 62914561,
+    "pid": 317210,
+    "display": ":0",
+    "appid": 2000999066
+  },
+  "focused_panel": {
+    "window": 62914561,
+    "display": ":0",
+    "name": "Frame Control PR66 disposable input probe",
+    "x": 0,
+    "y": 0,
+    "width": 640,
+    "height": 400,
+    "root": [
+      1920,
+      1080
+    ],
+    "app": 2000999066
+  },
+  "agent_status": {
+    "state": "ready",
+    "focus": 62914561
+  },
+  "position_response": {
+    "state": "ready",
+    "focus": 62914561,
+    "sent": true
+  },
+  "pad_response": {
+    "state": "ready",
+    "focus": 62914561,
+    "sent": true
+  },
+  "received_text": "Frame66\r",
+  "click_received": true,
+  "release_received": true,
+  "passed": true,
+  "input_helper_exited": true,
+  "recorder_exit": 0,
+  "recorder_stderr": "",
+  "final_focus": {
+    "window": null
+  },
+  "final_activity": 3,
+  "owned_lock_released": true,
+  "implementation_commit": "5641d3c316dfe225321f7233840cc83ff8c3f527",
+  "device": {
+    "steamos": "0.5.6",
+    "build_id": "20261015.6141207",
+    "steamvr": "2.18.2",
+    "battery_before": 98,
+    "battery_after": 98
+  },
+  "delayed_cleanup": {
+    "time": "2026-10-24T11:21:46Z",
+    "shared_lock_absent": true,
+    "owned_recorder_absent": true,
+    "game_mode": "active",
+    "full_plasma": "inactive",
+    "steam_pid": 297826,
+    "vrserver_pid": 297506,
+    "focusable_windows": [],
+    "focused_windows": [],
+    "activity_level": 3
+  },
+  "limits": [
+    "No wearer or packaged Electron/GUI interaction",
+    "ASCII only; Unicode and cross-service ordering not tested on device",
+    "The positioning setup reached the recorder edge (639,399); pixel-accurate absolute targeting is not established by this probe"
+  ]
+}
@@ -0,0 +1,82 @@
+"""Disposable X11 event recorder used for the PR #66 focused-input observation."""
+import ctypes as C
+import json
+import os
+import select
+import signal
+import time
+
+X = C.CDLL('libX11.so.6')
+P, U = C.c_void_p, C.c_ulong
+for name, restype, args in [
+    ('XOpenDisplay', P, [C.c_char_p]), ('XDefaultRootWindow', U, [P]),
+    ('XCreateSimpleWindow', U, [P, U, C.c_int, C.c_int, C.c_uint, C.c_uint, C.c_uint, U, U]),
+    ('XInternAtom', U, [P, C.c_char_p, C.c_int]),
+    ('XChangeProperty', C.c_int, [P, U, U, U, C.c_int, C.c_int, P, C.c_int]),
+    ('XStoreName', C.c_int, [P, U, C.c_char_p]),
+    ('XSelectInput', C.c_int, [P, U, C.c_long]), ('XMapWindow', C.c_int, [P, U]),
+    ('XFlush', C.c_int, [P]), ('XPending', C.c_int, [P]),
+    ('XConnectionNumber', C.c_int, [P]), ('XNextEvent', C.c_int, [P, P]),
+    ('XLookupString', C.c_int, [P, P, C.c_int, P, P]),
+    ('XDestroyWindow', C.c_int, [P, U]), ('XCloseDisplay', C.c_int, [P]),
+]:
+    fn = getattr(X, name)
+    fn.restype, fn.argtypes = restype, args
+
+class InputEvent(C.Structure):
+    _fields_ = [('type', C.c_int), ('serial', U), ('send_event', C.c_int),
+               ('display', P), ('window', U), ('root', U), ('subwindow', U),
+               ('time', U), ('x', C.c_int), ('y', C.c_int), ('x_root', C.c_int),
+               ('y_root', C.c_int), ('state', C.c_uint), ('code', C.c_uint),
+               ('same_screen', C.c_int)]
+
+class Event(C.Union):
+    _fields_ = [('type', C.c_int), ('input', InputEvent), ('pad', C.c_long * 24)]
+
+def say(**row):
+    print(json.dumps(row), flush=True)
+
+def end(*_):
+    raise TimeoutError('probe ended')
+
+signal.signal(signal.SIGTERM, end)
+signal.signal(signal.SIGALRM, end)
+signal.alarm(45)
+d = X.XOpenDisplay(b':0')
+assert d, 'X display unavailable'
+w = 0
+try:
+    w = X.XCreateSimpleWindow(d, X.XDefaultRootWindow(d), 0, 0, 640, 400, 0, 0, 0x224466)
+    for name, value in [(b'STEAM_GAME', 2000999066), (b'_NET_WM_PID', os.getpid())]:
+        val = U(value)
+        X.XChangeProperty(d, w, X.XInternAtom(d, name, 0), 6, 32, 0, C.byref(val), 1)
+    X.XStoreName(d, w, b'Frame Control PR66 disposable input probe')
+    X.XSelectInput(d, w, 1 | 2 | 4 | 8 | 64 | 32768 | 2097152)
+    X.XMapWindow(d, w)
+    X.XFlush(d)
+    say(ready=True, window=w, pid=os.getpid(), display=':0', appid=2000999066)
+    while True:
+        while X.XPending(d):
+            event = Event()
+            X.XNextEvent(d, C.byref(event))
+            if event.type in (2, 3, 4, 5, 6):
+                e = event.input
+                row = dict(type=event.type, window=e.window, x=e.x, y=e.y,
+                           synthetic=bool(e.send_event))
+                if event.type != 6:
+                    row['code'] = e.code
+                if event.type == 2:
+                    buf, keysym = C.create_string_buffer(32), U()
+                    n = X.XLookupString(C.byref(e), buf, 32, C.byref(keysym), None)
+                    row.update(text=buf.raw[:n].decode('utf-8', 'replace'), keysym=keysym.value)
+                say(**row)
+        ready, _, _ = select.select([0, X.XConnectionNumber(d)], [], [], 0.2)
+        if 0 in ready and not os.read(0, 1024):
+            break
+except TimeoutError:
+    pass
+finally:
+    if w:
+        X.XDestroyWindow(d, w)
+    X.XCloseDisplay(d)
+    say(cleaned=True)
@@ -0,0 +1,43 @@
+{
+  "checkedAt": "2026-10-25T06:03:45.387452+00:00",
+  "method": "Read-only Python probe over the existing frame SSH alias; no device changes",
+  "baselineCommit": "d79efb4730becc781f9a641cc36cb27f6481667c",
+  "deckyStatus": {
+    "arch": "aarch64",
+    "frameOS": "0.5.6",
+    "variant": "vr",
+    "build": "20261022.6153909",
+    "cef": true,
+    "managed": false,
+    "running": false,
+    "version": null,
+    "upstreamInstall": false,
+    "plugins": [],
+    "upstreamPlugins": []
+  },
+  "platform": {
+    "userServiceManager": true,
+    "rootMountOptions": "rw,relatime,ssd,discard=async,space_cache=v2,subvolid=5,subvol=/",
+    "homeMountOptions": "rw,relatime",
+    "homebrewExists": false,
+    "cefMarkerExists": false,
+    "cefTargetTitles": [
+      "SteamVR - valve.steam.gamepadui.frame.menu.53930005 (53930005)",
+      "SteamVR - valve.steam.gamepadui.bar (53930000)",
+      "SteamVR",
+      "SteamVR - Notifications",
+      "SteamVR - valve.steam.gamepadui.floatingfooter (53930004)",
+      "SteamVR - valve.steam.gamepadui.volumelevel (53930003)",
+      "SteamVR - valve.steam.gamepadui.tooltip.53930002 (53930002)",
+      "SteamVR - valve.steam.gamepadui.barpopup.53930001 (53930001)",
+      "SteamVR - Keyboard",
+      "data:text/html,&lt;body&gt;&lt;%2Fbody&gt;",
+      "SharedJSContext"
+    ]
+  },
+  "limits": [
+    "No Decky install/update/uninstall repeated in this retry",
+    "No OS update or reboot performed",
+    "No wearer-visible menu or controller input verified"
+  ]
+}
@@ -0,0 +1,91 @@
+# Round 2 retry, 25 October 2026
+
+The provider retry completed four further fixes, each in an isolated child
+worktree with its own issue, branch, PR, tests, docs and Announcement draft.
+The coordinator reviewed each patch, independently ran focused tests, verified
+its exact head and complete CI, merged it, then read back GitHub's merged state.
+PR #113 was untouched. No social announcements were posted.
+
+## Merged fixes
+
+| Change | PR | Merge commit | Coordinator focused tests | Final CI |
+| --- | --- | --- | --- | --- |
+| Skip linked backup ancestors and recheck before packing | [#215](https://github.com/saphid/frame-control/pull/215) | `da34d94` | 34 passed | 11 checks passed at `8cc03c8` |
+| Clean orphan smoke metadata/shortcuts; POSIX runner without zsh | [#216](https://github.com/saphid/frame-control/pull/216) | `d5fa8fe` | 17 passed | 10 checks passed at `a5daa4a` |
+| Separate Steam clips by headset/account/full session ID | [#217](https://github.com/saphid/frame-control/pull/217) | `1255ef2` | 62 passed | 10 checks passed at `7dfe777` |
+| Retry failed automatic copies and bind listings to the captured headset | [#218](https://github.com/saphid/frame-control/pull/218) | `fdd60d3` | 33 passed | 10 checks passed at `af2bb17` |
+
+Two initial CI fixture failures were fixed before merging: macOS temporary-path
+aliases needed a resolved working directory in the wrapper test; Windows
+needed explicit UTF-8 when reading the Settings test's HTML fixture.
+Concurrent main changes #208/#209/#210 were preserved. Changelog conflicts
+retained both entries. No history was rewritten.
+
+## Integrated validation
+
+At main `1255ef2`, after all four merges:
+
+- `python3 -m unittest discover -s tests`: 1,559 tests, 16 skipped, passed in
+  157.335 seconds. Loopback networking was enabled for local HTTP fixtures.
+- `node --test app/test/*.test.js site/test/*.test.mjs`: 59 tests passed.
+- Worker backup validation also passed both Docker recovery-kit E2E tests in
+  an isolated Compose project, then removed its containers, volumes and network.
+- Local proof logs: `/tmp/frame-round2-integrated-tests.log` and
+  `/tmp/frame-round2-integrated-node.log`. Individual focused logs use
+  `/tmp/frame-round2-{backup,smoke,clips,autosync}-review.log`.
+
+## Real Frame smoke
+
+The current host is lxso2; its existing direct `ssh frame` alias works.
+Another OBS task initially held `/tmp/frame-test.lock`, so only read-only
+checks were done until it released the lock. This coordinator then acquired it
+atomically and labeled it `frame-round2-vdw4yh1xv8-20261025`.
+
+The merged `scripts/frame-smoke.sh` ran directly without zsh at 06:38:37 UTC.
+All 13 steps passed on SteamOS 0.5.6, BUILD_ID `20261022.6153909`. The ARM64
+and Proton titles ran. The x86-64 Linux title reported its runtime missing,
+an explicitly accepted smoke outcome rather than a successful execution.
+Installs/removals succeeded; the Windows title's remove
+step stopped five test-owned PIDs. Both final process sweeps were empty.
+Independent readback found no reserved title folders or metadata, SteamVR's
+PID was unchanged, and the three observed gamescope focus properties matched
+before/after. Battery went from 99% Charging to 100% Full. Only this task's
+lock was removed, and its absence was verified.
+
+[Sanitized structured proof](round2-smoke-2026-10-25.json). Raw local results:
+`/tmp/frame-round2-smoke-results/2026-10-25T063837Z-20261022.6153909.json`;
+console log `/tmp/frame-round2-headset-smoke.log`; state readbacks
+`/tmp/frame-round2-smoke-before.txt` and `/tmp/frame-round2-smoke-after.txt`.
+
+The headset was unworn. Visible rendering/controller input was not verified.
+No pairing, password/security change, reboot or factory reset was performed.
+The new backup/clip/auto-sync paths have local fixtures and cross-platform CI;
+this smoke does not establish a new real-data backup/clip/UI test. Synthetic
+orphan metadata was not seeded on the real device. Backup path checks retain
+a documented race with concurrent filesystem changes.
+
+## Prior round-two work reconciled
+
+The failed coordinator checkout was still at v0.4.7. It was first updated to
+main `d79efb4`, already v0.4.30. Earlier PRs had completed clipboard testing
+(#124), original smoke process cleanup (#126), Windows VM capture (#129),
+battery health (#125), setup doctor (#127), and read-only storage (#128).
+Later evidence already covered real clip export (#147/#149/#154/#156) and
+Return to Game Mode (#143/#157). These remain earlier evidence, not tests
+performed by this retry. Physical Windows GPU/input and current physical
+macOS checks remain incomplete; see the current support matrix.
+
+Decision: fix reproduced data/cleanup/retry defects rather than automate game
+moves without a verified transaction API or promise unverified phone-background
+sync. Prepare v0.4.31; publication still requires its Linux AppImage install test.
+
+## Delegation provenance
+
+All implementations completed. Task IDs use prefix
+`node:delegated-task:command%3Amcp%3Ad9bc35d8-0e9c-42c2-b798-25bd8af94d81%3Adelegate-task%3A`
+followed by one of:
+
+- `frame-r2-retry-smoke-orphans-20261025-r1`
+- `frame-r2-backup-symlink-20261025-r1`
+- `frame-r2-clip-collision-20261025-r1`
+- `frame-r2-autosync-retry-20261025-r1`
@@ -0,0 +1,123 @@
+{
+  "source_commit": "1255ef2bbf2e2e5fd86f8b984b592bed56f20780",
+  "started": "2026-10-25T06:38:37Z",
+  "os_release": {
+    "VERSION_ID": "0.5.6",
+    "VARIANT_ID": "vr",
+    "BUILD_ID": "20261022.6153909"
+  },
+  "passed": 13,
+  "failed": 0,
+  "paired": false,
+  "devkit_utils_there_before": true,
+  "battery_before": {
+    "capacity": 99,
+    "statuses": [
+      "Charging",
+      "Charging"
+    ]
+  },
+  "battery_after": {
+    "capacity": 100,
+    "statuses": [
+      "Full",
+      "Full"
+    ]
+  },
+  "steamvr_pid_before": 124586,
+  "steamvr_pid_after": 124586,
+  "observed_focus_properties_unchanged": true,
+  "reserved_files_and_processes_absent_after": true,
+  "own_shared_lock_released": true,
+  "headset_worn": false,
+  "steps": [
+    {
+      "step": "cleanup: leftovers from earlier runs",
+      "ok": true,
+      "seconds": 7.8,
+      "stopped_process_counts": [
+        0,
+        0
+      ]
+    },
+    {
+      "step": "devkit service: properties.json",
+      "ok": true,
+      "seconds": 0.0
+    },
+    {
+      "step": "status",
+      "ok": true,
+      "seconds": 0.6
+    },
+    {
+      "step": "arm64: install",
+      "ok": true,
+      "seconds": 7.7
+    },
+    {
+      "step": "arm64: launch",
+      "ok": true,
+      "seconds": 3.3,
+      "outcome": "running"
+    },
+    {
+      "step": "arm64: remove",
+      "ok": true,
+      "seconds": 6.4,
+      "stopped_process_counts": [
+        2,
+        0
+      ]
+    },
+    {
+      "step": "x86_64: install",
+      "ok": true,
+      "seconds": 7.6
+    },
+    {
+      "step": "x86_64: launch",
+      "ok": true,
+      "seconds": 3.2,
+      "outcome": "runtime missing"
+    },
+    {
+      "step": "x86_64: remove",
+      "ok": true,
+      "seconds": 6.2,
+      "stopped_process_counts": [
+        0,
+        0
+      ]
+    },
+    {
+      "step": "exe: install",
+      "ok": true,
+      "seconds": 7.5
+    },
+    {
+      "step": "exe: launch",
+      "ok": true,
+      "seconds": 3.3,
+      "outcome": "running"
+    },
+    {
+      "step": "exe: remove",
+      "ok": true,
+      "seconds": 6.5,
+      "stopped_process_counts": [
+        5,
+        0
+      ]
+    },
+    {
+      "step": "cleanup: everything this run installed",
+      "ok": true,
+      "seconds": 7.4,
+      "stopped_process_counts": [
+        0,
+        0
+      ]
+    }
+  ]
+}
@@ -0,0 +1,19 @@
+# Round 3 headset checks, 25 October 2026
+
+These checks used the real Frame after the device hold ended. SteamOS was
+0.5.6, build `20261022.6153909`. Each device session acquired
+`/tmp/frame-test.lock` atomically and released only its own lock. The battery
+read 100% and Full in the first check and after the OBS session; Steam and
+SteamVR were left running.
+
+| Question | Observation | Conclusion |
+|---|---|---|
+| Does active passthrough appear in SteamVR's `/dev/video99` mirror? | The mirror service was active. One 1920×1080 RGB frame read from `/dev/video99` had a single pixel value, `(24, 28, 53)`, throughout. The headset was unworn; no active passthrough session or wearer-visible room view was established. Frame Control has no verified remote passthrough toggle. The temporary frame was removed. | **Still unknown.** A uniform standby frame cannot answer whether SteamVR composites active passthrough into its mirror. No headset setting was changed. |
+| Can Frame Control prompt when a headset text box opens? | No desktop `plasmashell` process was running during this check. There is no verified cross-app focus event from SteamVR, Lepton and the nested desktop; KDE Connect's `keyboardstate` packet describes keyboard support, not a focused text field. | **Not built.** A prompt triggered by an unverified signal would be misleading. The existing **Type on the headset** control remains available. |
+| Does reverse clipboard exist? | Frame Control already has **Copy the headset's clipboard here**. Its earlier real Frame test used a temporary nested desktop and confirmed that text copied through Klipper reached a Linux PC clipboard. No desktop panel was open during this session, so it was not rerun here. | **Shipped and previously verified**, text only. Windows/macOS backends and arbitrary headset apps remain unverified on a real Frame. |
+| Is an 80% charge limit available and writable? | `steamosctl get-max-charge-level` returned `UnknownInterface: ...BatteryChargeLimit1`. No `charge_control_*` attribute was found under `/sys/class/power_supply`. Only `pm8550b-charger/charging_pause` and `charging_enable` were present, each mode `644`, owner `root:root`. | **No supported user-writable control.** No battery attribute was written. |
+
+The separate OBS transport check on the same build sent the mirror and the
+default-output monitor to a Linux PC. A 4.021-second temporary capture had
+H.264 video and AAC audio according to `ffprobe`. It was removed; OBS itself
+and audible playback were not tested. See the OBS source PR and guide.
@@ -0,0 +1,25 @@
+# Screenshot Save on a real Frame, 25 October 2026
+
+After PR #192 merged, Frame Control's production `list_shots()` and
+`save_shots()` paths were run from lxso2 against the real Frame. The test held
+the shared `/tmp/frame-test.lock` with an owner marker and removed only its own
+lock. A separate locked check earlier in this round found SteamVR at activity
+level 3 (standby). No new screenshot was created.
+
+- The Frame listed seven existing Steam screenshots.
+- One existing screenshot was copied to a temporary folder on the PC. Its
+  local size matched the reported remote size: **294,885 bytes**. The new
+  destination had four components below the temporary root: headset, Steam
+  account, game ID and filename.
+- Saving the same screenshot a second time returned zero new copies. A fresh
+  list then marked that screenshot as saved.
+- The temporary PC folder and its private image were removed at the end. The
+  source screenshot on the Frame was only read. Battery was **100% Full**
+  before and after.
+
+This verifies one real screenshot transfer and the repeat-save behavior. It
+does **not** reproduce two different real screenshots with the same filename;
+the account/game/headset collision case is covered by the fake-source test in
+`tests/test_shot_copy.py`. Windows and macOS physical-PC saves were not tested.
+Active passthrough in the recording mirror remains unknown because the Frame
+was in standby.
@@ -0,0 +1,70 @@
+# Steam clip export collision fixtures, 25 October 2026
+
+Base: `d79efb4` (Frame Control v0.4.30). Issue:
+[#212](https://github.com/saphid/frame-control/issues/212).
+Host: Linux 6.8.0-139-generic, Python 3.12.3, ffmpeg 6.1.1.
+
+## Baseline reproduction
+
+Loaded the unmodified `ui/frame_clips.py` from `d79efb4` into a temporary
+Python module and exported three fake sources into a temporary directory:
+
+```
+1/clips/clip_620/video/bg
+2/clips/clip_620/video/bg
+1/clips/clip_620/video/other
+```
+
+Each source's payload was its own ID. All three exports returned the same
+destination, `clip_620.mp4`; listing marked all three saved. The final file
+contained only the last source ID. No SSH or headset was used.
+
+## Regression coverage
+
+`tests/test_clips.py` exports five IDs on each of two fake headsets, including
+equal clip names across accounts, nested sessions with equal leaf names,
+different leaf names under one clip and the background/clip distinction.
+All ten payloads survive at distinct destinations. Listing marks only the
+identities already exported. A pre-existing flat MP4 retains its original
+bytes and does not mark any identity saved. Normal export still returns
+`message` and `file`, removes its remote temporary export and clears local
+staging; a failed re-export preserves the completed file.
+
+`tests/test_clip_copy.py` exercises the server's list and manual export
+functions and its actual auto-sync callbacks with fake transport. A manual
+copy is recognised by auto-sync, all other account/session identities copy,
+and switching to a second headset copies its own sources without overwriting
+the first. A delayed manual job refuses a changed headset with status 409.
+Both local phone mode and local headset runtime reject Steam clip list,
+export and auto-sync requests with status 400. The separate `Recorder` path
+is unchanged.
+
+## Validation
+
+- `PYTHONPATH=tests python3 -m unittest test_clips test_clip_copy test_autosync test_shot_copy test_headset_actions -v`
+  — 66 tests passed in 17.288 seconds, no skips. Includes real ffmpeg/ffprobe
+  export of a generated 65-second DASH fixture and recording stop/cleanup.
+- `PYTHONPATH=tests python3 -m unittest test_server -v`
+  — 44 tests passed in 12.315 seconds, no skips.
+- `node --test site/test/*.test.mjs` — 2 tests passed.
+- `python3 -m unittest discover -s tests -v` — 1,518 tests run in
+  181.025 seconds; OK, 16 skipped for unavailable platform/tool prerequisites.
+- `python3 -m py_compile ui/frame_clips.py ui/server.py tests/test_clips.py tests/test_clip_copy.py`
+  and `git diff --check` — passed.
+
+The server and full Python suites require localhost sockets and were run
+outside the network sandbox. Tests import `tests/sandbox.py` to isolate app
+data, SSH settings, home directories and service URLs.
+
+## Limits and upgrade behaviour
+
+No real headset was accessed: the shared device lock is held by other work.
+This is Linux fixture and server coverage, not a fresh packaged-app or
+Windows/macOS verification. Existing real-headset export evidence in the
+recording guide predates this destination change.
+
+Old flat exports cannot prove headset/account/session identity and are left
+untouched. Previously remembered auto-sync IDs retain their existing
+watermark/history behaviour; **Copy everything now** or manual **Export**
+creates an identified copy. No release, version bump, merge or social post
+is included. PR #113 is outside this task.
@@ -0,0 +1,22 @@
+# SteamOS 0.5.6 compatibility check, 25 October 2026
+
+The real Frame was accessed **after** the 00:00 AEDT hold, under a separately
+acquired `/tmp/frame-test.lock`. The coordinator had finished its v0.4.19 smoke
+test and released its lock first. This check took place approximately 00:04–
+00:08 AEDT (13:04–13:08 UTC). A device clock reading in the first snapshot was
+**00:04:58 AEDT**. The one temporary capture was removed and our lock was
+released. Steam and SteamVR were left running.
+
+| Check | Observation |
+|---|---|
+| OS | `VERSION_ID=0.5.6`, `VARIANT_ID=vr`, `BUILD_ID=20261022.6153909` |
+| Update channel | `atomupd-manager tracked-branch` returned `beta`; tracked variant `vr`; update status `idle`. `atomupd-manager status` and `check` returned D-Bus `AccessDenied` to the normal user. No root, update, or channel change was attempted. |
+| Discovery | `frame.local` and a sample `frame-0000.local` name were unresolved from the Linux host. Avahi was active on the Frame, but `/etc/avahi/avahi-daemon.conf` has `publish-addresses=no`. The configured `ssh frame` alias worked. The host reached the Frame over Tailscale, so a local-subnet scan and same-LAN cached-IP reconnection were not exercised. |
+| Script fallback | `steamos-session-select` was present and `holo-session-select` absent. The installed devkit utilities contained `steamos-prepare-upload` and `steamos-delete`; their `holo-*` replacements were absent. No session switch, install, or delete command was run. |
+| Battery and memory | Frame Control's `ui/frame_status.py` returned a system battery at 98%, Charging, with its source under `/sys/class/power_supply/max1720x_bat_7-36`; memory was 16,422,952,960 bytes total and 11,256,848,384 bytes available. The battery was 97% at the initial raw sysfs check and 98% at the final check while charging. |
+| Recording source | The user `steamvr-v4l2cam.service` and `/dev/video99` were present. A single frame from that device was black while the unworn headset was in standby. Frame Control's MP4 path reads that same SteamVR `system.HeadsetView` mirror and never opens a passthrough camera. Active passthrough inclusion in the mirror remains unverified. The sample image was not retained or published. |
+| Dominant eye | Neither standard `steamvr.vrsettings` path checked had a readable dominant-eye setting. No source or effect on the mirror was verified; Frame Control does not attach dominant-eye metadata. |
+
+This was a bounded compatibility check, not a rerun of the coordinator's
+13-step smoke test. The coordinator reported that smoke passed on this same
+build, with battery 95% to 96% while charging and cleanup complete.
@@ -0,0 +1,74 @@
+# Windows Wireless Adapter doctor verification, 24 October 2026
+
+PC-only implementation and verification. No Frame was contacted, before or
+after 13:00 UTC. No adapters or security settings were changed. This evidence
+does not establish a physical Steam wireless adapter fix or RF interference.
+
+## Windows VM
+
+An existing local Windows 11 VM (build 26200), Python 3.12.14 from the installed
+Frame Control bundle, ran the isolated suite from a task-specific Downloads
+folder:
+
+```powershell
+& 'C:\Users\frame\AppData\Local\Programs\Frame Control\resources\python\python.exe' -m unittest discover -s tests -p test_wireless.py -v
+```
+
+Result: **15 tests, OK, one skipped** (Node absent). This includes the real
+read-only PowerShell inventory and authenticated HTTP handler tests. The app's
+connector was never started. Existing test SSH credentials were used only for
+the Windows VM; no credentials were copied into the repository.
+
+- [Exact test output](windows-wireless-tests-2026-10-24.txt).
+- [Sanitized live inventory](windows-wireless-summary-2026-10-24.json): two
+  virtual-machine network devices, with PnP/presence/adapter/route sources
+  available. WLAN unavailable; channels/bands remained null. All PnP IDs,
+  device names and interface names were removed from this artifact.
+- The guest clock was approximately seven hours ahead of the host. `observedAt`
+  is retained as returned by Windows, not used to establish test timing.
+
+The first probe used a list of requested default prefixes. A missing IPv6
+route caused PowerShell to throw away available IPv4 data. The final query
+filters `Get-NetRoute` results instead, and the rerun above confirms routes
+are available. No network configuration was changed to make the query work.
+
+## Browser UI and local tests
+
+Production `ui/index.html` ran against a loopback-only synthetic API fixture,
+with no connector and no headset transport. Opening/revisiting the tool caused
+no wireless query; an explicit click rendered two distinct Wi-Fi Direct PnP
+instances and a 2.4 GHz PC interface while the headset state was offline.
+Unknown virtual-adapter channels, non-present/disabled status, and unconfirmed
+interference remained visible. Checked at 1280 and 640 CSS pixels without
+horizontal overflow.
+
+![Production browser UI with explicitly labelled synthetic Windows readings](windows-wireless-synthetic-2026-10-24.png)
+
+The screenshot uses synthetic readings, not the VM's two Ethernet interfaces.
+The yellow synthetic-data label was added by the browser fixture for this
+capture; it is not product UI.
+
+Local commands:
+
+```sh
+python3 -m unittest discover -s tests -p 'test_wireless.py' -v
+node tests/wireless.cjs
+python3 -m unittest discover -s tests -v
+python3 -m py_compile ui/*.py
+node --check /tmp/wireless-index-scripts.js
+```
+
+The targeted suite passed 15 tests with the live Windows-only test skipped;
+the direct Node run passed all four UI tests. The complete server suite passed
+1,423 tests with 16 skips before the additional missing-metadata test; a final
+complete run and Windows CI results are recorded in the PR. The syntax check
+used inline scripts extracted from the production HTML.
+
+## What remains unverified
+
+No physical Steam dongle, Razer headset, live Wi-Fi Direct session, channel
+reading from real wireless hardware, dropout reproduction or recovery action.
+The English netsh parser is fixture-tested; localised or denied readings remain
+unknown. Windows CI validates query execution on hosted virtual hardware.
+There is no adapter disable action because the available evidence cannot
+reliably identify a safe extra instance.
@@ -0,0 +1,40 @@
+{
+  "platform": "Windows-11-10.0.26200-SP0",
+  "python": "3.12.14",
+  "state": "partial",
+  "sources": {
+    "pnp": "ok",
+    "present": "ok",
+    "adapters": "ok",
+    "routes": "ok",
+    "wlan": "unavailable"
+  },
+  "observedAt": "2026-10-24T19:15:45.946191+00:00",
+  "deviceCount": 2,
+  "devicesWithoutIdentifiers": [
+    {
+      "present": true,
+      "pnpStatus": "OK",
+      "problemCode": 0,
+      "operational": 6,
+      "media": 0,
+      "defaultRoute": false,
+      "wifi": false,
+      "hardware": false,
+      "channel": null,
+      "band": null
+    },
+    {
+      "present": true,
+      "pnpStatus": "OK",
+      "problemCode": 0,
+      "operational": 1,
+      "media": 1,
+      "defaultRoute": true,
+      "wifi": false,
+      "hardware": true,
+      "channel": null,
+      "band": null
+    }
+  ]
+}
@@ -0,0 +1,24 @@
+test_ambiguous_adapter_join_never_selects_the_first_match (test_wireless.Inventory.test_ambiguous_adapter_join_never_selects_the_first_match) ... ok
+test_channels_require_exact_guid_and_band_is_never_guessed (test_wireless.Inventory.test_channels_require_exact_guid_and_band_is_never_guessed) ... ok
+test_counts_unique_pnp_ids_not_rows_or_suffix_order (test_wireless.Inventory.test_counts_unique_pnp_ids_not_rows_or_suffix_order) ... ok
+test_distinct_instances_presence_disabled_and_activity_are_separate (test_wireless.Inventory.test_distinct_instances_presence_disabled_and_activity_are_separate) ... ok
+test_friendly_name_is_only_a_candidate_and_other_duplicate_names_are_not_direct (test_wireless.Inventory.test_friendly_name_is_only_a_candidate_and_other_duplicate_names_are_not_direct) ... ok
+test_missing_interface_metadata_and_invalid_guids_stay_unknown (test_wireless.Inventory.test_missing_interface_metadata_and_invalid_guids_stay_unknown) ... ok
+test_missing_sources_are_unknown_and_adapter_fallback_is_retained (test_wireless.Inventory.test_missing_sources_are_unknown_and_adapter_fallback_is_retained) ... ok
+test_raw_ssid_mac_and_errors_are_not_returned (test_wireless.Inventory.test_raw_ssid_mac_and_errors_are_not_returned) ... ok
+test_concurrent_requests_do_not_spawn_more_probes (test_wireless.Probe.test_concurrent_requests_do_not_spawn_more_probes) ... ok
+test_failure_timeout_and_invalid_output_are_explicit_and_release_lock (test_wireless.Probe.test_failure_timeout_and_invalid_output_are_explicit_and_release_lock) ... ok
+test_http_is_authenticated_pc_only_and_never_calls_ssh (test_wireless.Probe.test_http_is_authenticated_pc_only_and_never_calls_ssh) ... GET "GET /api/host/wireless HTTP/1.1" 403 -
+GET "GET /api/host/wireless HTTP/1.1" 400 -
+GET "GET /api/host/wireless HTTP/1.1" 200 -
+ok
+test_live_windows_inventory (test_wireless.Probe.test_live_windows_inventory) ... ok
+test_non_windows_starts_nothing (test_wireless.Probe.test_non_windows_starts_nothing) ... ok
+test_static_noninteractive_local_command_and_timeout (test_wireless.Probe.test_static_noninteractive_local_command_and_timeout) ... ok
+test_ui_behavior (test_wireless.Probe.test_ui_behavior) ... skipped 'Node required'
+
+----------------------------------------------------------------------
+Ran 15 tests in 8.139s
+
+OK (skipped=1)
+Windows wireless smoke: partial {'pnp': 'ok', 'present': 'ok', 'adapters': 'ok', 'routes': 'ok', 'wlan': 'unavailable'} devices= 2
@@ -0,0 +1,81 @@
+# Frame Control extensions
+
+Extensions add a local panel to Frame Control's Tools page. They are plain HTML,
+CSS and JavaScript. Frame Control discovers them from its per-user data folder;
+there is no build step, server process, or headset installation. Open an extension
+to run it. Closing it unloads its page.
+
+## Install the example
+
+Copy [`examples/extensions/headset-glance`](../examples/extensions/headset-glance)
+to the `extensions` folder shown on Tools → Extensions, then select **Refresh**
+and **Open Headset Glance**. The folder is normally:
+
+- Linux: `~/.local/share/frame-control/extensions`
+- macOS: `~/Library/Application Support/Frame Control/extensions`
+- Windows: `%APPDATA%\Frame Control\extensions`
+
+To remove it, close the panel and delete only its `headset-glance` folder. The
+desktop app reads the folder on its computer. The iPhone app and the opt-in
+[SteamVR headset panel](headset-app.md) read the folder on the Frame. To use an
+extension in VR, copy its folder to
+`steamos@frame:~/.local/share/frame-control/extensions/`, then select
+**Extensions → Refresh extensions → Open** in the headset panel. The iframe,
+read-only bridge and asset rules are the same there.
+
+## Make an extension
+
+Create `extensions/your-id/manifest.json` and `index.html`. IDs use lowercase
+letters, digits and hyphens, start with a letter, and are at most 40 characters.
+The manifest ID must match the folder name:
+
+```json
+{
+  "id": "your-id",
+  "name": "Your feature",
+  "version": "1.0.0",
+  "apiVersion": 1,
+  "description": "What the panel does.",
+  "entry": "index.html"
+}
+```
+
+`apiVersion` selects the Frame Control bridge contract, independently of your
+extension's own `version`. This app supports integer `1`; a missing field means
+`1` for existing extensions. Unsupported versions appear as errors on Refresh,
+and their assets are not served. Declare it in new extensions so a future API
+change can fail clearly instead of running incompatible code. The runtime
+`capabilities` reply below reports the bridge version too.
+
+Put JavaScript in a separate `.js` file. Supported assets are HTML, JS, CSS,
+JSON, PNG, JPEG, GIF, WebP and SVG, all in the extension's top-level folder.
+Nested paths and symlinks are not served. No file may exceed 5 MiB. The panel
+uses an iframe with `sandbox="allow-scripts"`; its code has an opaque origin,
+cannot call Frame Control's HTTP API directly, and cannot navigate the app's
+top-level window. Content Security Policy restricts scripts, images, and
+`fetch` requests, but an extension can still navigate its own iframe to an
+external site. Treat third-party extensions as untrusted code and review them
+before installation.
+
+The version 1 bridge uses `postMessage`. Send a request to `parent` and match
+the numeric `id` in the reply. The [example JavaScript](../examples/extensions/headset-glance/main.js)
+shows a complete client:
+
+```js
+parent.postMessage({type: 'frame-control:request', id: 1, action: 'status'}, '*');
+// Reply: {type: 'frame-control:response', id: 1, value: {...}}
+```
+
+Supported actions:
+
+| Action | Value |
+| --- | --- |
+| `capabilities` | `{apiVersion: 1, actions: ['capabilities', 'status']}` |
+| `status` | `{connected, os: {version, build}, battery: {percent}, steamvr}` |
+
+`status` is the app's latest successful status snapshot. When that reading fails,
+`connected` is false and its fields are empty. No write actions are currently exposed. Future APIs
+should use explicit, narrow actions and keep the iframe isolated. A third-party
+extension is code you choose to run locally: inspect its files before copying
+them into the folder. A Decky plugin is a separate Steam client plugin and does
+not use this API.
@@ -58,6 +58,11 @@ counts them while they run.
  restore chosen parts after a factory reset, and **Return to Game Mode** when
  the headset is stuck in Desktop Mode. Sign-in files and keys are never copied.
  Not tested on a headset yet. See [backup-and-recovery.md](backup-and-recovery.md).
+- **Wireless Adapter doctor** (Windows, Tools → This PC): explicitly read local
+  PnP instances, presence/link states and available channel/band readings;
+  explain possible Wi-Fi Direct duplicates and 2.4 GHz audio overlap. No headset
+  access, automatic changes or disable button. See
+  [Windows wireless diagnosis](windows-wireless-doctor.md).
 - **Battery** with charging state: charge rate in watts, time to full or empty,
  charger type and wattage (for example USB-C PD 20 W), and battery temperature.
 - **Status**: storage, memory, temperature, Wi-Fi, uptime, and whether SteamVR,
@@ -79,7 +84,11 @@ counts them while they run.
 - **Volume** and mute (`wpctl`).
 - **Android apps**: search about 4,500 F-Droid apps rated for the Frame, install
  one with a click as its own Lepton instance (it keeps its data and shows in the
-  Steam library), then launch, stop, test or remove it. **Report an APK** records
+  Steam library), then launch, stop, test or remove it.
+  The catalogue can load while the installed-app list is still being read. If
+  that read fails, browsing remains available, but installation waits for a
+  confirmed list so Frame Control does not make a duplicate app instance.
+  **Report an APK** records
  whether any APK worked (F-Droid or not: pick a file, type a package, or use an
  installed app). Your reports are saved on your computer and change the verdicts
  you see. With **Share compatibility results** on (Privacy & updates), they also
@@ -8,13 +8,15 @@ installed; the desktop app does not bundle this command.

 ```sh
 scripts/frame-doctor.sh
-scripts/frame-doctor.sh --alias bedroom --lan frame.local
+scripts/frame-doctor.sh --alias bedroom --lan 192.168.1.40
 scripts/frame-doctor.sh --alias frame --lan 192.168.1.40
 ```

 Use only addresses belonging to your intended headset. The command tries the
 existing `frame` SSH alias first (Tailscale if setup configured it that way),
-then `frame.local`, then USB-C at `10.86.200.233`. `--alias`, `--lan` and `--usb`
+then an optional `--lan` address, then USB-C at `10.86.200.233`. SteamOS 0.5.6
+stopped publishing mDNS names, so use a known IP for `--lan` if `.local` no longer
+resolves. `--alias`, `--lan` and `--usb`
 override those defaults. It reports the successful path without printing its
 address. It neither discovers other devices nor enables Tailscale.

@@ -0,0 +1,62 @@
+# Write a plugin for Frame
+
+There are two paths. Choose the one that matches your feature.
+
+## Frame Control extension
+
+Use a Frame Control extension for a panel, status view, or guide that does not
+need to change the headset. Put `extension.json` and `index.html` in one folder
+under `~/.local/share/frame-control/extensions`. The opt-in headset panel lists
+the folder and opens it in a sandboxed iframe. The version 1 bridge has only
+`capabilities` and read-only `status`. It cannot call Steam, change settings,
+or run privileged code. See [the extension API](extensions.md) and its example.
+
+## Decky plugin
+
+Use a Decky plugin only if you need Decky's backend or Gamepad UI integration.
+Build an official-format ZIP with one top-level folder, `plugin.json`, and a
+frontend bundle in `dist/index.js`. A Python `main.py` backend is optional.
+Test on ARM64. If you ship an ELF helper, build it for AArch64 (ELF machine
+183). Avoid root, `sudo`, Steam Deck TDP controls, fixed x86 binaries, and
+paths under `/etc`. Frame Control's managed loader is a normal user service;
+it blocks root plugins and x86 archives. Keep data under your plugin folder or
+the user's home directory, and provide a removal path.
+
+The current Frame SteamVR shell does not expose Decky's Steam Deck Quick Access
+Menu. A backend `Loaded` log only proves backend startup. Test any frontend
+page, setting, notification, route, and controller input while wearing a Frame
+before describing it as working in VR. Until a QAM bridge is verified, a Frame
+Control extension is the simplest route for a self-contained read-only VR panel.
+
+Frame Control now has an experimental [Framey panel host](framey-loader.md)
+for API v2 Decky frontend bundles. It renders common settings controls in the
+separate SteamVR dashboard panel, but Steam library and store page patches
+remain unavailable. Wearer-visible use is not yet verified.
+
+To test safely, use a separate Frame Control managed Decky install, verify the
+ZIP digest from the official store, install one plugin at a time, and inspect
+`journalctl --user -u frame-control-decky.service`. Remove only your own
+plugin folder when you finish. See the current [compatibility table](decky-frame.md).
+
+## Framey API v2 compatibility
+
+Framey hosts a plugin's frontend in an isolated iframe in the Frame Control
+SteamVR panel. The table describes the current implementation and its tests;
+none of these frontend controls has passed a worn-headset check yet.
+
+| Decky API or UI feature | Framey behavior | Verified in |
+| --- | --- | --- |
+| `definePlugin` with `content`, `titleView` | Renders a React panel and optional title | Local browser with ProtonDB Badges; host unit test |
+| `PanelSection`, rows, buttons, toggles, dropdowns | Local touch-sized controls | Local browser and host unit test |
+| Optional `settings`, `frameyQuickActions` | Separate settings tab; up to eight actions with result text | Host unit test; these fields are Framey additions |
+| `serverAPI.call` / `callable` | Calls only that plugin's Decky Python backend via the headset service | Fake Frame e2e for get/set setting; host unit test |
+| `toaster.toast` | Visible toast inside the plugin panel; `dismiss` and optional `onClick` | Host unit test; no Steam system notification |
+| `routerHook.addRoute` / `removeRoute`, `Navigation.Navigate` / `NavigateBack` | Local routes inside this plugin panel only | Host unit test |
+| `routerHook.addPatch`, global components | No-op; cannot patch Steam routes | Not applicable |
+| Steam library/store patches, CEF tab injection | Unavailable; no matching target in the isolated panel | Frame CEF inspection |
+| `fetchNoCors`, Decky event listeners, file picker, root calls | Unavailable | Not supported by Framey |
+
+Keep routes local to the panel and give every operation a visible result. A
+plugin that calls `Navigation.Navigate('/decky/store')` will not open the
+Frame Control store; only paths registered by that same plugin can navigate.
+Toasts stay inside the panel, so keep essential errors in the plugin UI too.
@@ -0,0 +1,129 @@
+# Framey loader on Steam Frame
+
+Framey is an experimental bridge for Decky store plugins inside Frame Control's
+SteamVR dashboard panel. It is opt in. The panel and Decky backend are ordinary
+user services under `~/.local/share/frame-control`; neither needs root or a
+read-write SteamOS root filesystem. Decky's standard Quick Access menu still
+does not appear in the separate SteamVR CEF target.
+
+## Use in the headset
+
+Install **Frame Control in VR** and **Decky Loader on Frame** from Frame Control
+on your computer. Open the Frame Control tab in SteamVR, then choose **Decky
+plugins → Open official store**. Search the catalogue, confirm an install, and
+choose **Open panel** from the installed plugin list. The panel contains the
+plugin's own controls and settings. Update and Remove affect only plugin
+folders that Frame Control's store manager installed.
+Removing a plugin keeps its Decky settings. Removing the Frame Control headset
+panel or Decky backend keeps plugin folders until each is removed separately.
+
+Frame Control's existing official-store manager downloads a published ZIP from
+Decky's content-addressed CDN, verifies its store SHA-256 hash and manifest,
+rejects unsafe ZIP members and root plugins, and swaps one managed plugin
+folder with rollback on failure. It rejects non-ARM64 ELF and Windows binaries.
+The Decky user service restarts after a file change. Framey's panel host accepts
+only API v2 bundles with `dist/index.js`; other installed plugins remain
+manageable but have no Framey panel. The store manager does not currently
+screen a plugin's runtime network downloads.
+
+## What the compatibility host supplies
+
+The plugin bundle runs in an opaque-origin iframe in the Frame Control SteamVR
+panel. It receives React 18.3.1, a small `DFL` panel-control shim, and the
+Decky API v2 `call`/`callable` interface. Backend methods are sent by the
+authenticated parent to Steam's existing `SharedJSContext` CDP client, then
+through Decky's *existing* websocket connection. Framey never opens a second
+Decky websocket, because Decky allows only one frontend connection. The iframe
+does not receive Frame Control's UI key. React and ReactDOM are bundled for
+offline use under their MIT licenses in `ui/vendor`.
+
+The host currently supplies sections, rows, buttons, toggles, dropdowns,
+scroll containers, a modal, locale information, local panel routes and toasts,
+and backend calls for the plugin that owns the panel. Steam library/store page
+patches, global Steam UI components, file pickers, and privileged root methods
+have no VR target. A plugin that depends on them can render only part of its UI
+or show an incompatibility message. A Decky plugin's Python backend still runs as
+the headset user when Decky loads it, so review third-party code before opting
+in. The panel iframe can make HTTPS requests subject to ordinary browser CORS.
+
+ProtonDB Badges' current API v2 bundle rendered its settings in a local Chromium
+browser with a stubbed backend reply on 25 October 2026. Its controls accepted
+pointer input. This does **not** verify SteamVR visibility, controller input,
+live Decky settings persistence, or badges on Steam game pages. The last item
+has no supported injection target in the Frame Control panel.
+The [browser and fake Frame evidence](evidence/framey-browser-2026-10-25.md)
+records exactly what was exercised.
+
+The in-headset **Open official store** view loads the full official catalogue.
+Search matches names, authors, and descriptions. Filters show non-root plugins
+or installed plugins, and Previous/Next buttons browse 20 results per page.
+The root label is a compatibility warning; other APIs are checked only when a
+plugin is opened. The store still needs the managed Decky user service running
+before its Install or Update buttons are enabled.
+
+Install, Update, and Remove show the current job stage in the headset panel.
+The store verifies each downloaded archive and the headset applies it with a
+rollback if Decky cannot start. The panel remembers the current job ID for this
+browser session, so **Check result** can resume polling after a navigation or
+temporary connection error. Refresh the installed list before starting another
+operation after an error.
+
+## For plugin authors
+
+Publish a normal [Decky store](https://plugins.deckbrew.xyz/) API v2 release
+with `plugin.json`, a single `dist/index.js` ESM frontend entry point, and a
+Python backend if needed. Give the frontend a `content` React element returned
+by `definePlugin`, and build settings as panel controls from `@decky/ui`.
+Backend calls through `@decky/api` reach only that plugin's own backend.
+For best VR compatibility, keep the panel self-contained and use `PanelSection`,
+`PanelSectionRow`, `ButtonItem`, `ToggleField`, and `DropdownItem`. Handle a
+missing Steam UI route, store overlay, or `SteamClient` object gracefully.
+Avoid root, remote binary downloads, Steam library patches, and assumptions
+about Steam Deck hardware. Declare settings defaults so a fresh user service
+can render without pre-existing files. Test your ZIP with the store validator
+and the fake Frame flow before asking users to install it.
+
+An API v2 plugin's normal `content` is its default VR panel. Framey also shows
+an optional `settings` React element under a **Settings** tab and an optional
+`titleView` above it. For one-tap headset controls, return
+`frameyQuickActions: [{label: 'Refresh data', onClick: refreshData}]` from the
+plugin initializer. Framey displays up to eight actions and reports a pending,
+success, or failure state. These descriptor fields are Framey additions; Decky
+ignores them. Use a plugin backend method through `@decky/api` for work needing
+persistent state, and keep a quick action safe to repeat.
+See the [API v2 compatibility table](frame-plugin-author.md#framey-api-v2-compatibility)
+for tested behavior and remaining limits.
+
+The [Frame Control extension API](extensions.md) is an alternative for a
+Frame-specific panel. It needs only a local manifest, HTML, and the read-only
+`status` bridge; it does not need Decky.
+
+## Removal
+
+Use **Remove** on each installed Framey plugin, then **Remove managed Decky**
+and **Remove** under Frame Control in VR. These operations remove only
+Frame Control-owned folders and services. Settings, the Chromium profile, and
+other users' plugins are preserved. To remove one managed plugin manually,
+first inspect its `.frame-control-store.json` receipt in
+`~/.local/share/frame-control/decky/plugins/<folder>`, then delete only that
+folder and run `systemctl --user try-restart frame-control-decky.service`.
+The Decky and headset service manual removal commands are in
+[Decky on Frame](decky-frame.md#opt-in-and-remove) and
+[Frame Control in the headset](headset-app.md#remove).
+
+## Fast worn-headset check
+
+With an already installed Framey plugin and someone wearing the headset, run
+`python3 scripts/framey-worn-check.py` from a paired computer. The script
+atomically acquires `/tmp/frame-test.lock` before reading battery or SteamVR
+activity. If another job owns the lock, it makes no sensor reads. It releases
+its own lock without starting the interaction when the headset is in standby.
+Within 35 seconds, use a controller
+to open a managed plugin panel and touch one setting. The script records a
+fresh trusted pointer event, the panel-ready event, SteamVR overlay visibility,
+and a stereo screenshot with varied pixels. It deletes its own short-lived
+challenge and releases only its own lock. It records the screenshot hash and
+color count, then removes the private temporary image from both devices.
+Pixel variety alone cannot prove the UI text was legible; a person must still
+confirm the view in the headset. The script does not install or remove a plugin,
+alter Steam settings, or wake the headset.
@@ -0,0 +1,102 @@
+# Frame Control in the headset
+
+**Experimental, Frame OS 0.5.6.** Tools → Frame Control in VR installs a local
+panel in SteamVR's dashboard. It is a way to reach Frame Control while wearing
+the headset, independent of Decky's Quick Access Menu. The panel starts only
+after you opt in; its server binds to `127.0.0.1` and it uses a normal user
+service. No `sudo`, root filesystem change, or Steam client patch is needed.
+
+The companion copies its bundled UI over the existing trusted SSH connection.
+On the Frame, `frame-control-headset.service` runs a loopback server and one
+Chromium app window on gamescope. The window receives a dedicated `STEAM_GAME`
+id, so SteamVR registers `valve.steam.desktopgame.2001947813` as a dashboard
+panel. **Show in SteamVR** requests that dashboard tab; the wearer can select
+it again from SteamVR's dashboard. Closing the panel stops its browser and
+server. The service is not enabled at boot.
+
+The page shows battery, free home storage and SteamVR status.
+The **Large status screen** uses large read-only values for battery, SteamVR,
+free home storage and Frame OS, with a refresh button and clear unknown values.
+It is an at-a-glance view, not a crash diagnosis or a Decky plugin page.
+The headset must still be worn to verify that a person can see and use it.
+
+The page can request SteamVR's main Game Mode dashboard, list and force quit a running game after an
+unsaved-progress confirmation, save an OpenVR screenshot to
+`~/Pictures/FrameControl`, and record the SteamVR mirror to
+`~/Videos/FrameControl`. Recordings have a 20-minute limit and use a separate
+work folder from desktop Frame Control's recorder; they may have no audio if
+the monitor source is unavailable. Captures made in standby can be dark.
+
+The page also discovers extensions from
+`~/.local/share/frame-control/extensions` and opens them in sandboxed iframes.
+It offers the version 1 read-only `capabilities` and `status` bridge from
+[the extension guide](extensions.md). Installing an extension still means
+copying its folder to the Frame; the panel does not download third-party code.
+
+The opt-in [Framey loader](framey-loader.md) hosts compatible Decky plugin
+panels and settings in a separate sandboxed iframe on this SteamVR page. The
+existing official Decky store manager installs and removes their code. The
+frontend host is browser-tested, but wearer-visible VR use remains unverified.
+
+The panel also lists Decky plugins and can install, update, or remove compatible
+plugins from the official store when the opt-in managed loader is running.
+Each change asks for confirmation. The Frame VR shell does not show Decky's
+Steam Deck Quick Access Menu, so Decky plugin pages, settings, routes, and
+toasts are not available in this panel yet. The [compatibility table](decky-frame.md)
+separates backend loading from VR use. Authors can use the
+[Frame plugin and extension guide](frame-plugin-author.md).
+
+The per-run UI key is passed in the URL fragment, removed from the address bar after load,
+and sent in the `X-Frame-UI` header. The key is absent from the HTTP request
+line and server log. The usual host/origin and anti-framing checks still apply.
+
+## Real Frame test, 2026-10-25
+
+On Frame OS 0.5.6, build `20261022.6153909`, the opt-in install started the
+user service, served `/headset`, read live `/api/status` from the browser, and
+registered a mapped Chromium window with SteamVR under the dedicated overlay
+key. The server rejected a request with the wrong UI key. A read-only status
+probe reported the user service running and the overlay registered.
+
+The unworn headset was in standby (`activity_level` 3). SteamVR reported the
+new overlay as `not_visible` even after `ShowDashboard`. An OpenVR stereo
+screenshot was a uniform dark frame. The documented temporary wake attempt
+(`power.turnOffScreensTimeout` 5 → 3600, `--handlewakeup`, `ShowDashboard`)
+still left the overlay `not_visible`; the setting was restored to 5 and the
+dashboard hidden. The X window's `xwd` image was black too. These observations
+prove panel creation and page/API execution, **not wearer-visible pixels or
+laser/controller input**. A worn-headset check is still required before
+describing the panel as visually verified.
+
+The test then removed the managed service and app bundle. Its unit became
+inactive, port 47813 closed, the SteamVR overlay disappeared, and the Frame's
+battery was 100%. Steam and SteamVR were left running. The browser profile and
+extensions folder were deliberately kept.
+
+A second test on the same build installed the expanded panel with the
+`headset-glance` example extension. The headset's authenticated loopback API
+returned live status (99% battery), discovered and served the extension, and
+listed no running games. The Game Mode dashboard request succeeded; an invalid
+force-quit app ID was rejected with HTTP 400. Screenshot and recording actions
+saved a PNG and a 3.6 MB MP4 in the headset user's folders. The recording
+reported an audio source. The per-run UI key was absent from the server log.
+After another wake and dashboard request, SteamVR still reported the panel
+`not_visible`. No wearer-visible screenshot or controller interaction was
+obtained. The test removed its example extension and captured media, then
+uninstalled the service. The unit, port, bundle and overlay were absent after
+removal; Steam and SteamVR remained running.
+
+## Remove
+
+Use **Tools → Frame Control in VR → Remove**. If the companion is unavailable,
+run:
+
+```sh
+ssh frame 'systemctl --user stop frame-control-headset.service; rm -f ~/.config/systemd/user/frame-control-headset.service; systemctl --user daemon-reload; rm -rf ~/.local/share/frame-control/headset/bundle; rm -f ~/.local/share/frame-control/headset/receipt.json ~/.local/share/frame-control/headset/server.log'
+```
+
+That command removes only Frame Control's managed panel code. The Chromium
+profile remains in `~/.local/share/frame-control/headset/profile` so local
+extension data is not discarded. Inspect and delete that folder separately if
+you no longer want it. Third-party extensions are in
+`~/.local/share/frame-control/extensions` and are never removed by this tool.
@@ -31,6 +31,7 @@ Lepton (Android 11, podman container "lepton-dev") ← its own panel, app 305600
 | `gamescopectl screenshot <file>` (with `WAYLAND_DISPLAY=gamescope-0`) captures gamescope's flat layer. | Frame Control's capture |
 | The **headset view** (both eyes, fully composited: room, panels, dashboard, controllers) comes from OpenVR `IVRScreenshots::RequestScreenshot(VRScreenshotType_Stereo)`. It's callable from `python3` with `ctypes` against `/opt/steamvr/bin/linuxarm64/libopenvr_api.so` as an overlay app. The compositor appends `.png`, writing a 1920×1080 side-by-side image (960×1080 per eye) plus a left-eye preview, in about 0.3s. In standby the frame is blank. `vrcmd --screenshot` and `vrcmd --compositorcmd screenshot_request` wrote nothing, even with `steamvr/rawCapturePath` set. | `ui/frame_vrshot.py` |
 | SteamVR's `steamvr-v4l2cam.service` (`/opt/steamvr/bin/linuxarm64/v4l2cam --output=99`) copies the headset view (the `system.HeadsetView` mirror, one undistorted image) into the v4l2loopback device `/dev/video99` ("SteamVR"), 1920×1080 RGB24. `ffmpeg -f v4l2 -i /dev/video99` reads it at about 70 new frames/s; the first frame read can be black. The Frame's hardware encoder (`iris_encoder`, `/dev/video-enc0`) crashes ffmpeg's `h264_v4l2m2m`, so encode with `libx264 -preset ultrafast -tune zerolatency`: 720p30 takes about 0.7 of a core and 1080p60 about 1.7 (of 8). gamescope also publishes a PipeWire `gamescope` video source, but the Frame's GStreamer has no `pipewiresrc`. **Verified 2026-09-26.** | Frame Control's live video (`/api/stream`) |
+| **Passthrough in the mirror: yes on SteamOS 0.5.6**, build `20261022.6153909`, SteamVR 2.18.2. After `vrcmd --handlewakeup`, `/dev/video99` showed real room pixels behind panels. They also appeared in OBS's saved recording and a five-second production MP4. No camera setting was changed, and the private room images were not published. Other games/modes and Steam clips were not established. **Verified 2026-10-25.** | [OBS validation](evidence/obs-validation-2026-10-25.md) |
 | Battery: `/sys/class/power_supply/max1720x_bat_7-36` gives µV/µA (current is positive while charging), `time_to_full_now`/`time_to_empty_now` in seconds, and `temp` in tenths of °C. The charger shows up as `tcpm-source-psy-…` (`type=USB`, `usb_type=C PD [PD_PPS]`), for example 12 V × 1.67 A. | Frame Control's battery card |
 | `vrcmd --stats` reports `activity_level` (3 = standby). | Telling whether the headset is being worn |
 | **Testing VR apps without wearing the headset.** In standby SteamVR keeps OpenXR sessions hidden, so they render one frame and stop. `vrcmd` (in `/opt/steamvr/bin/linuxarm64`) settings use `section.key`: `vrcmd --set-settings-bool power.pauseCompositorOnStandby 0` and `vrcmd --set-settings-float power.turnOffScreensTimeout 3600`, then `vrcmd --handlewakeup`, keep the compositor running, and the scene app becomes visible. If it stays `visible-blurred`, the Steam dashboard is open: `SteamClient.OpenVR.VROverlay.HideDashboard()` in Steam's `SharedJSContext` (CDP on 8080) closes it. The headset view then captures with `ui/frame_vrshot.py`. Restore afterwards with `--set-settings-bool power.pauseCompositorOnStandby 1` and `--set-settings-float power.turnOffScreensTimeout 5`. The bool setter reads `true` as false, so use 1/0. A Steam launch that stalls in standby at `ShowInterstitials` or `CreatingProcess` (see `console_log.txt`) continues with `SteamClient.Apps.ContinueGameAction(<action id>, "<appid>", "<task>")`. **Verified 2026-09-27.** | Proving VR output remotely, [webxr-chromium.md](webxr-chromium.md) |
@@ -0,0 +1,118 @@
+# Linux Wireless Adapter doctor
+
+![Linux PC doctor before any checks run, with explicit hardware selection and read-only limits](img/linux-wireless-doctor.png)
+
+On the **Linux PC**, open **Settings → Linux Wireless Adapter doctor**, or
+**Devices & connection → Linux Wireless Adapter doctor**. It works without a
+connected headset. Choose **Read PC device inventory**, select the intended
+USB device or wireless interface, then **Check selected device**. Nothing runs
+until requested. Re-read the inventory after reconnecting a device.
+
+From a source checkout, the same collector is available without starting the
+app or its headset connection workers:
+
+```sh
+python3 ui/frame_wireless_doctor.py
+python3 ui/frame_wireless_doctor.py --device net:wlan0
+python3 ui/frame_wireless_doctor.py --device usb:1-2 --json > adapter-report.json
+```
+
+Use a selector actually listed on your PC. No device is selected automatically.
+All USB devices are included, including hubs and devices without a network
+interface. A product label, observed VID/PID, or a single available interface
+**does not identify Valve's adapter**. There is no trusted adapter ID table in
+this feature. Compare inventory before and after reconnecting the intended
+adapter when safe. For a USB device exposing multiple wireless interfaces,
+select the specific interface for radio/manager evidence.
+
+## Evidence and limits
+
+- **Presence and binding:** `/sys/bus/usb/devices` and `/sys/class/net` correlate
+  USB ancestry, wireless interfaces, driver links and module links. An absent
+  interface does not establish which driver should be installed. A missing
+  module link may mean a built-in driver. A bound driver does not prove Steam
+  streaming support.
+- **Permissions and udev:** `udevadm info --query=property` supplies a small
+  allowlist of driver, ID and tag fields. If available, the report includes USB
+  node mode, owner/group IDs and the current user's read/write access. Direct
+  USB access is not necessarily required by kernel networking; a restrictive
+  node alone is not diagnosed as the cause. No udev rules are installed or run.
+- **Radio blocks:** read-only WLAN rfkill sysfs entries are matched to the
+  selected interface's PHY name. An unrelated block cannot establish that
+  this adapter is blocked. Unavailable or unmatched entries remain unknown.
+- **Channel/band:** `iw dev IFACE info` provides the current channel and
+  frequency where reported; `iw phy PHY info` supplies enabled frequencies.
+  An idle interface may have no current channel. These observations do not
+  establish the channel used by a Steam streaming session, supported regions,
+  or the correct regulatory setting.
+- **Network managers:** visible `/proc/*/comm` process names show
+  NetworkManager, iwd and wpa_supplicant. `nmcli` reads only the selected
+  interface's general state, managed flag and driver. NetworkManager can use
+  iwd or wpa_supplicant as its backend, so coexistence is not itself a conflict.
+  If both backends are visible, the report suggests checking who owns this
+  exact interface. It does not claim a confirmed conflict or stop services.
+  Restricted process visibility and unverified backend ownership are explicit.
+
+Every command uses fixed read-only arguments, no shell, closed stdin and a
+three-second timeout. Optional tools are not installed automatically. Missing
+tools, denied reads, disappearing devices, and restricted VM/container hardware
+visibility remain unknown. A successful report is a snapshot, not a hardware
+health certificate. CLI exit 0 means collection is supported, not that the
+adapter works; unsupported platforms/headset-local mode return 2, as does an
+invalid/stale selector. JSON has schema version 1.
+
+The doctor never uses SSH, scans nearby Wi-Fi networks, opens a connection to
+the Frame, escalates privileges, loads drivers, changes security settings,
+changes channels, unblocks radios, changes network settings, or restarts
+services. Run it as your ordinary user, never with sudo. The app hides the
+entry on macOS, Windows and phone sessions; its API refuses collection in
+headset-local (`FRAME_LOCAL=1`) mode. The source CLI is intended only for the PC.
+
+Reports stay local unless you explicitly save, copy or share them. Exported
+fields include observed USB IDs/product labels, interface names, driver names
+and permission metadata. USB serials, Wi-Fi names, MAC/IP address fields,
+credentials, process arguments and raw command output are not exported. Review
+the report before posting it: hardware labels and local paths can identify
+parts of your setup.
+
+## Motivation and shipped comparison
+
+[The 23 October 2026 complaint](https://x.com/ExpressGinga81/status/2113457683143741720)
+says the Wi-Fi dongle does not work on Ubuntu/Kubuntu 26.04 while SteamVR works
+under Wayland. It supplies **no adapter VID/PID, driver, logs or established
+cause**. This feature helps gather that missing evidence; it does not claim to
+fix that complaint or certify Ubuntu/Kubuntu 26.04 support.
+
+Shipped **v0.4.18** has local network/gateway discovery in `frame_network.py`
+and headset connection management, but no local USB/driver/rfkill adapter
+report or adapter diagnostic UI. The existing `frame-doctor.sh` diagnoses the
+headset through SSH and is a different tool. This doctor never calls it.
+General SteamOS 3.9.5 / Frame OS 0.5.6 compatibility and OS backend transition
+notes are covered separately in
+[`docs/steamos-2026-10-compat.md`](https://github.com/saphid/frame-control/blob/9c7110c1f48d160b0fb3c3b9f658d4937bd2032d/docs/steamos-2026-10-compat.md)
+([PR #164](https://github.com/saphid/frame-control/pull/164)). Existing PC
+route/SSID diagnostics use NetworkManager's `nmcli` with an `iwgetid` SSID
+fallback, independently of whether NetworkManager uses wpa_supplicant (SteamOS
+3.9.5 new installs) or iwd (upgrades). This doctor reads actual PC evidence and
+does not infer a conflict, hardware identity or fix from those OS defaults.
+There is no adapter-specific device observation in that compatibility work.
+
+## Verification
+
+```sh
+python3 -m unittest discover -s tests -p test_wireless_doctor.py -v
+python3 -m unittest discover -s tests
+```
+
+Tests use an explicitly synthetic USB `1234:5678`, sysfs trees, command replies
+and loopback HTTP. They cover an unbound USB device, module binding, multiple
+interfaces, PHY-matched and unrelated rfkill entries, channel parsing, manager
+coexistence, missing/denied commands, stale/injected selectors, export field
+filtering, authentication and refusal to probe in headset-local mode. The
+HTTP tests instantiate the handler without starting headset workers.
+
+Linux host collection was exercised on kernel `6.8.0-139-generic`: an existing
+PC interface was visible with its `iwlwifi` binding and unblocked PHY; `iw` and
+`nmcli` were absent and reported as unavailable. This is **not a physical Steam
+Frame Wireless Adapter test**, an Ubuntu/Kubuntu 26.04 test, or a headset test.
+No Frame access is part of this work.
@@ -7,6 +7,12 @@ the Mac's own keyboard. Find it under **Tools → Mac in the headset** (macOS
 only). On Windows there's an experimental port,
 [PC in the headset](pc-in-headset.md).

+On a **whole Mac display** panel, click **Switch Mac app (⌘Tab)** to send one
+Command-Tab chord to the Mac. The button is absent from single-window panels;
+those already keep their own source. It requires the same Mac Accessibility
+permission as other viewer keyboard input. The chord and button have automated
+checks, but a worn-headset click has not been verified.
+
 The confidence labels are the same as in [ssh.md](ssh.md).

 ## Why this design
@@ -0,0 +1,144 @@
+# Headset view in OBS
+
+Frame Control can send SteamVR's headset mirror and the Frame's output audio to
+OBS on a Linux or macOS computer. A checkout helper is also available for Windows tests. The helper uses the same `/dev/video99` video
+source and default-output monitor as **Capture & Live → Record**. It sends a
+local MPEG-TS stream; no port is opened to the LAN or internet.
+
+1. Connect to the Frame and start SteamVR. OBS runs on the computer; the Frame
+   already has `ffmpeg`.
+2. In the **Frame Control desktop app**, open **Capture & Live** and click
+   **Start OBS source**. Keep Frame Control open; **Stop OBS source**, switching
+   headsets, or quitting the app closes its SSH stream. It uses the selected
+   headset and the app's bundled helper.
+3. Expand **OBS setup** in the app to copy the Input URL and format. The port
+   can be changed before Start if another program uses 15099. Use that same
+   port in OBS. The sender cannot identify which program is listening.
+4. In OBS, add a **Media Source**, clear **Local File**, set **Input** to
+   `udp://127.0.0.1:15099`, and set **Input Format** to `mpegts`. The source
+   carries video and AAC audio. Use OBS's audio mixer to choose monitoring and
+   recording levels.
+
+From a source checkout, you can instead install `python3` on the computer and
+run:
+
+   ```sh
+   python3 scripts/obs-headset-source.py
+   ```
+
+Ctrl+C stops the checkout helper. The app closes a control pipe when you click
+Stop or quit; the helper then closes its SSH child, including on Windows. Encoding runs on the Frame; the computer does not need FFmpeg. The desktop
+app bundles Python. A source checkout needs Python 3.8+ and OpenSSH Client.
+The Windows button is hidden: native Windows/Frame streaming and OBS have
+not passed an end-to-end test. A Windows 11 VM passed the helper control-pipe,
+late UDP receiver and child-cleanup fixture; its real-headset bridge delivered
+zero packets. These are separate results, not native Windows support.
+If no first packet arrives within 20 seconds, or an active stream sends no
+packet for 10 seconds, the helper closes SSH and shows an error instead of
+leaving **Start OBS source** waiting or a frozen source running indefinitely.
+
+To share the OBS view in a call, see the short
+[Discord setup guide](streaming-to-discord.md).
+
+`--height 1080 --fps 60` increases quality and Frame CPU use. The default is
+720p30. `--port 15100` selects another loopback port; use the same port in
+OBS. If the Frame's PulseAudio monitor cannot be read, the helper exits with
+an error. Use `--no-audio` only when a silent view is useful. To inspect the
+stream without OBS, run `ffprobe -v error -show_streams
+udp://127.0.0.1:15099` in a second terminal while the helper is running.
+
+This is the composited, undistorted one-eye **SteamVR mirror**, not a raw
+passthrough camera feed. The mirror may be blank when the headset is idle or
+unworn. **Room passthrough is verified** in this mirror and the saved OBS/MP4 outputs
+on SteamOS 0.5.6 after a safe SteamVR wake. Check the picture before sharing;
+other games and modes may differ.
+The helper does not send a microphone. It is designed for one local OBS
+receiver. **Verified 2026-10-25:** the helper bundled in the Linux AppImage
+sent a real Frame stream to OBS 30's Media Source. OBS recorded 37.6 seconds
+with H.264 video and AAC audio; a brief 440 Hz tone played to the Frame's
+default output was present in the saved audio. The headset was in standby, so
+the video showed the standby mirror. That initial check did not assess listening quality, A/V sync or active
+passthrough. The full validation below supersedes those gaps with measurements
+and a positive passthrough result, while listening remains unverified. See the
+[test evidence](evidence/obs-media-source-real-2026-10-25.md).
+The [follow-up Linux/Frame transport check](evidence/obs-followup-2026-10-25.md)
+measured packet continuity and a short MP4 recording on the current SteamOS
+build. The newer [full OBS validation](evidence/obs-validation-2026-10-25.md)
+records more than three minutes and measures audio, sync, latency and cleanup.
+
+## SteamOS / Steam Machine PC host
+
+Use **Desktop Mode** on the SteamOS PC. Download the Linux x86_64 AppImage to
+your home folder. Make it executable and open it there; SteamOS has a
+read-only system root, so these steps do not use `apt` or change `/usr`:
+
+```sh
+chmod +x ~/Downloads/Frame-Control-linux-x86_64.AppImage
+~/Downloads/Frame-Control-linux-x86_64.AppImage
+```
+
+If AppImage mounting reports a FUSE error, try
+`APPIMAGE_EXTRACT_AND_RUN=1 ~/Downloads/Frame-Control-linux-x86_64.AppImage`.
+This extracts to writable temporary space and needs enough free disk space.
+Set up the Frame's SSH connection in Frame Control, then use **Start OBS
+source** before you add or activate OBS's Media Source. Install OBS as the
+`com.obsproject.Studio` Flatpak through Discover or your normal user Flatpak
+setup. In that OBS Media Source, clear **Local File**, set **Input** to
+`udp://127.0.0.1:15099`, and set **Input Format** to `mpegts`. Make a short
+recording and check both picture and sound before a stream. Use **Stop OBS
+source** in Frame Control when done.
+
+The OBS Flatpak's published manifest includes `--share=network`, which is
+needed for its local UDP receiver. Check your installed permissions with
+`flatpak info --show-permissions com.obsproject.Studio` if OBS receives no
+packets. Frame Control's helper sends to loopback on this PC; it does not
+require an open LAN port or an OBS plugin. The PC does not need a system
+`ffmpeg` package for the helper; encoding runs on the Frame.
+
+**Test limit:** The v0.4.27 AppImage launched on an Ubuntu 24.04 x86_64 host
+under Xvfb. Its helper sent H.264 and AAC from a real Frame to a local UDP
+receiver on that host. No SteamOS 3.9.5 PC, Steam Machine, Flatpak OBS runtime,
+read-only-root host, or physical display was available for this check. The
+SteamOS steps and Flatpak receiver therefore remain **untested on SteamOS**.
+See the [test record](evidence/obs-steamos-host-2026-10-25.md).
+
+## Known issue: game audio in OBS
+
+A Frame owner [reported](https://x.com/AzizahStellazio/status/2114147449468293171)
+that OBS **Game Capture / Application Audio Capture** can lose game audio when
+the headset turns on. OBS support attributed this to Valve/SteamVR. Frame
+Control cannot change that game-audio routing. If it happens, use Frame
+Control's **Start OBS source** and OBS **Media Source** steps above to capture
+the headset view and its output audio. You can also try OBS **Desktop Audio
+Capture** for the computer's output, then check its meter and a short test
+recording before you stream. Do not leave two active sources for the same audio
+unless you want duplicate sound.
+
+The real Frame/OBS check above proved that a synthetic tone from the Frame's
+output reached the Media Source recording. It did **not** use a running game,
+listen to the audio, reproduce the reported Game Capture failure, or measure
+audio/video sync. Real game audio while the headset is awake remains unverified.
+
+## Check sync and recover a blank source
+
+Make a short recording of a visible click, clap or other simultaneous marker
+and sound before streaming. Open **Advanced Audio Properties** in OBS. If audio
+arrives early, hide/deactivate this Media Source, add a positive **Sync Offset
+(ms)** in Advanced Audio Properties, then show/reactivate it, record again,
+and check the result. Changing the offset during playback did not correct
+the tested OBS 30 source. Setting it before activation did: a +480 ms offset
+reduced a 480 ms lead to 0 ms within the test resolution in three pulses. The 2026-10-25 Linux software-rendering test measured
+about 0.4 seconds of audio lead with default OBS settings. This is a measured
+setup result, not a universal offset. Do not apply it blindly to another host.
+
+Start Frame Control's source before adding or activating the OBS Media Source.
+After Stop/Start or a connection failure, hide and show the Media Source, or
+reopen its properties and click OK, to reopen its UDP receiver. Keep only one
+receiver on a port. If another application owns 15099, stop the relay, choose
+another port in **OBS setup**, and change the OBS Input to match. Sending UDP
+packets does not confirm that OBS has received or decoded them.
+
+A stalled stream ends with an error. Wake or reconnect the Frame and press
+Start again; automatic reconnection is not implemented. Standby can produce
+valid but blank frames, so it does not necessarily trigger a packet timeout.
+A fully suspended Frame cannot be woken over an unavailable SSH connection.
@@ -1,10 +1,29 @@
 # Open questions and on-device checks

-Research as of 2026-09-25, eight days after the Frame's retail release
-(2026-09-18). Most first-party detail comes from Valve's Steamworks developer
-pages. Searches of Reddit and the Steam forums turned up **almost no
-end-user reports** about SSH, desktop streaming, or macOS. Treat that as
-"not documented yet", not "doesn't work".
+The September sections below record early checks after the Frame's retail
+release (2026-09-18). They are a historical test log, not a current setup
+guide. For current connection steps, see [SteamOS October 2026
+compatibility](steamos-2026-10-compat.md). For the charge-limit result, see
+[charge-limit.md](charge-limit.md).
+
+## Current Frame OS 0.5.6 status (2026-10-25)
+
+- `frame.local` no longer resolves on the checked 0.5.6 beta build
+  (`20261022.6153909`). Avahi was active but did not publish addresses. The
+  configured Tailscale SSH alias worked. Frame Control can use a saved IP on
+  the same network after verifying the pinned SSH key, or a manual IP/SSH
+  alias. Same-LAN fallback scanning was **not** tested on this Tailscale route.
+  See the [live compatibility check](evidence/steamos-compat-live-2026-10-25.md).
+- Read-only checks on that build found no SteamOS Manager
+  `BatteryChargeLimit1` interface or `charge_control_*` attribute. The vendor
+  charging switches are root-owned and managed by Valve's charger service.
+  No charging control was written. An 80% limit is **not supported** by Frame
+  Control; see [charge-limit.md](charge-limit.md) and the
+  [headset check](evidence/round3-headset-2026-10-25.md).
+- Passthrough in the MP4 and OBS mirror is **verified on 0.5.6**: after a safe
+  SteamVR wake, room pixels appeared behind panels in the actual mirror and
+  saved outputs. Per-game behavior and Steam's own clips remain unverified;
+  see the [OBS validation](evidence/obs-validation-2026-10-25.md).

 ## Verified on device (2026-09-25)

@@ -14,7 +33,9 @@ build 20260922.6101926, kernel 6.18, aarch64):
 - **1–2.** Developer Mode + Set User Password gave working SSH with no terminal
  steps. `sshd` is enabled and active. The user is `steamos` (in `wheel`) and
  the hostname is `frame`.
- **3.** `frame.local` resolves from the Mac; `avahi-daemon` is active.
+- **3.** `frame.local` resolved from the Mac on the September build;
+  `avahi-daemon` was active. This result does not apply to the checked 0.5.6
+  beta build; see the current status above.
 - **5.** `/etc/ssh/sshd_config` has `Include /etc/ssh/sshd_config.d/*.conf`.
  The existing drop-ins are `20-systemd-userdb.conf` and `99-archlinux.conf`, so
  `01-frame-keys-only.conf` would sort first as intended. (`--harden` itself
@@ -148,9 +169,9 @@ check in the headset:
 Can an 80% charge limit be set over SSH or adb? **Not safely yet.** SteamOS
 Manager's `BatteryChargeLimit1` (the interface Steam's own setting uses) has
 no backend in the Frame's device config, and the battery node is a
-`max1720x` fuel gauge with no `charge_control_end_threshold`. Research and
-read-only headset checks are in [charge-limit.md](charge-limit.md). Not tested
-on a headset.
+`max1720x` fuel gauge with no `charge_control_end_threshold`. Read-only checks
+on the real Frame confirmed this on 0.5.6 beta; no charge setting was written.
+See [charge-limit.md](charge-limit.md).

 ## Unconfirmed claims made in these docs

@@ -1,5 +1,9 @@
 # PC in the headset (Experimental)

+For Steam's own Linux Wayland desktop-sharing flow, see the separate
+[Steam desktop sharing helper](steam-pipewire.md). It does not enable this
+feature on Linux.
+
 **Tools → PC in the headset**, on Windows only. It's the Windows version of
 [Mac in the headset](mac-in-headset.md): a whole screen on your PC
 becomes its own SteamVR panel in the Frame. Individual windows are available only
@@ -9,6 +13,12 @@ whole screens. Place the panel with the dashboard's Float
 in World, Move and Size, point and click with the laser, scroll with the
 thumbstick, and type on the PC's keyboard.

+On a whole-screen panel, click **Switch PC window (Alt+Tab)** to switch the
+foreground Windows window. It sends one explicit Alt-Tab chord through the
+viewer's existing input channel. The button is absent from single-window panels
+when a WGC-enabled build supports them. A real Windows/Frame button click has
+not been verified; use the PC keyboard if focus does not move as expected.
+
 **It's experimental.** A Windows 11 VM has captured its real desktop with
 Desktop Duplication and encoded it with Media Foundation and JPEG. Physical PCs,
 hardware encoding and physical laser input remain unverified. See
@@ -0,0 +1,141 @@
+# Plugin and modding research
+
+Checked **2026-10-25**. Decision: keep the experimental, reversible Decky manager
+and ship Frame Control's own sandboxed panel API as the supported way to add
+local features. Both implementations already landed in the replacement job
+while the original job was unavailable. This report consolidates their evidence
+and the original research questions; it does not claim another loader was built.
+
+## Can Decky run on Frame?
+
+**Its ARM64 backend and Steam shared-context injection work on the tested build.
+A usable Decky menu inside VR remains unverified.** Do not equate an active
+service or a JavaScript plugin registration with a working headset interface.
+
+| Requirement | Evidence | Consequence |
+| --- | --- | --- |
+| ARM64 Linux binary | Upstream [3.3.0](https://github.com/SteamDeckHomebrew/decky-loader/releases/tag/v3.3.0) has `PluginLoader-arm64`; Frame reports `aarch64` | ARM is not itself a blocker. Individual plugins may still ship x86 binaries or assume Deck hardware. |
+| Steam Gamepad UI and CEF | Loopback `127.0.0.1:8080/json/list` exposes `SharedJSContext` plus distinct SteamVR pages | The shared context exists; the VR shell is a separate integration target. |
+| CEF enable marker | `~/.steam/steam/.cef-enable-remote-debugging` is absent, but CEF already answers | No marker or Steam launch flag change is needed on this build. |
+| User service manager | `systemctl --user show-environment` succeeds | A per-user service works without installing an upstream root service. The manager is degraded by a stale failed Decky unit, although its unit file is gone. |
+| Filesystem | `/` currently mounts `rw` on Btrfs, `/home` mounts `rw` | This is an observation of this device, not a stock-image guarantee. Do not disable SteamOS read-only protection or install packages in `/usr`. |
+| Homebrew folder | `~/homebrew` is absent | It is an installer convention, not a preinstalled SteamOS plugin API. Frame Control uses a separate managed directory. |
+| Visible menu | Earlier tests registered Decky's tab only in shared JavaScript; SteamVR had no Decky overlay; headset was in standby | QAM visibility, controller input and a real plugin's visible result remain unverified. |
+
+The fresh [read-only probe](evidence/plugins-2026-10-25.json) records SteamOS
+`0.5.6`, `VARIANT_ID=vr`, build `20261022.6153909`. It confirms CEF, architecture,
+mounts, user-service availability, and absence of a running managed or upstream
+Decky installation. This retry did not install anything or restart Steam.
+
+The replacement job's initial [test record](decky-frame.md) reports:
+
+- Decky 3.3.0 started as the normal `steamos` user and injected into
+  `SharedJSContext`.
+- Install → status → update → status → remove → status succeeded on the Frame.
+  Removal left the unit, binary and port 1337 absent, while preserving user data.
+- ProtonDB Badges 1.1.0 loaded as a passive plugin and appeared in Decky's
+  shared-context registry. Its badge or menu was not seen inside VR.
+- Injected frontend code can outlive backend removal until Steam's web helper
+  restarts. An earlier helper-restart test cleared the globals; this retry did
+  not repeat it.
+
+These are prior documented results, separate from the fresh read-only probe.
+The coordinator then ran a separate, locked
+[official-store compatibility audit](decky-frame.md#official-store-plugin-audit-2026-10-25)
+on the same Frame OS build. Seven plugins logged backend loads. A managed
+ProtonDB Badges 1.3.4 store install, update and remove also succeeded. The
+headset stayed unworn, so these results still do not establish VR UI use.
+
+## Installer and update choice
+
+The upstream [installer at e42a3c8](https://github.com/SteamDeckHomebrew/decky-installer/blob/e42a3c828de90673959b4de26cf5c5d2c7830554/cli/install_release.sh)
+escalates through sudo, creates `~/homebrew/plugins` and `services`, writes the
+CEF marker and a system unit under `/etc/systemd/system`, and starts Decky as
+root. Its architecture switch supports `aarch64|arm64`. Running this installer
+is unnecessary for a compatibility check and grants more access than a panel
+extension needs.
+
+Frame Control's [manager](../ui/frame_decky.py) instead downloads the official
+ARM64 asset, checks GitHub's published SHA-256 and the ELF machine, and writes
+only under `~/.local/share/frame-control/decky` and `~/.config/systemd/user`.
+It refuses an upstream system-service installation, requires active CEF before
+install/update, and restores the previous binary, receipt and unit if applying
+an update fails. Existing tests exercise that rollback with a failed service
+start. These checks do not prove every possible OS or Steam update is safe.
+
+The binary is downloaded on demand, not bundled. Plugin discovery lists the
+managed directory and upstream `~/homebrew/plugins`. The later
+[store manager](../ui/frame_decky_store.py) exposes official entries in the PC
+app and opt-in headset panel. It verifies archive digests, blocks root and
+non-ARM64 binaries, and changes only its own plugin folders. That is file and
+backend support, not a working VR plugin page. Decky plugins can execute
+backend code and are not isolated by Frame Control's HTML extension sandbox.
+
+Home-directory state is expected to survive SteamOS image updates, based on
+SteamOS's layout; **an actual OS update and reboot persistence test has not been
+performed**. Steam frontend changes, CEF availability, libc requirements and
+plugin hardware assumptions can still break Decky. On failure, remove the user
+service using [the documented removal command](decky-frame.md#opt-in-and-remove);
+its removal path does not require a working CEF target. Test the sequence again
+on each supported OS build before expanding support claims.
+
+## Other paths
+
+| Path | What it enables | Current limits and choice |
+| --- | --- | --- |
+| Decky plugins | Steam frontend hooks, optional Python backends | Seven official-store plugins logged backend loads on ARM64. Store install/update/remove worked for ProtonDB Badges. VR pages and controller input remain unverified. Keep experimental. |
+| [CSS Loader](https://github.com/suchmememanyskill/SDH-CssLoader) / [DeckThemes](https://docs.deckthemes.com/) | Stylesheets applied to Steam UI | CSS Loader 2.1.3 backend loaded on Frame. No theme was applied or visually tested. Deck themes do not establish compatibility with Frame's separate VR shell. |
+| User home / SteamOS homebrew | User services, user Flatpaks, files and helpers | Use owned folders and explicit uninstall. A folder named `homebrew` supplies no discovery or security boundary by itself. No rootfs changes needed for the chosen path. |
+| Android / Lepton | Sideloaded apps, game-specific content and per-app settings | Frame Control already manages APKs and ADB. Lepton runs Android containers, not Steam's CEF UI; an Android mod does not add a Steam dashboard tab. No new Android mod was tested here. See [APKs](apks.md), [VR APKs](vr-apks.md), and [game mods](mods.md). |
+| Frame Control extensions | Third-party HTML/CSS/JS panels with a small read-only bridge | Shipped in [#194](https://github.com/saphid/frame-control/pull/194), with a manifest, local folder, sandbox, example and [author guide](extensions.md). No Python imports, arbitrary SSH commands or write actions are exposed. |
+| Frame Control's headset panel | Runs the local tools and extensions as a SteamVR panel | Shipped in [#198](https://github.com/saphid/frame-control/pull/198), expanded in [#201](https://github.com/saphid/frame-control/pull/201). Page/API execution and uninstall were tested; wearer-visible pixels and controller interaction remain unverified. See [test record](headset-app.md). |
+
+The extension iframe has `sandbox="allow-scripts"`, an opaque origin, restrictive
+CSP and a `postMessage` bridge accepting only `capabilities` and a reduced
+`status` snapshot from the active frame. It is useful for local dashboards and
+small tools today. It cannot replace the full Decky API. Third-party code still
+needs review: an iframe may navigate itself externally, and local installation
+does not establish publisher trust.
+
+Extensions are loaded only when opened and are removed by closing their panel
+and deleting their own directory. They modify no SteamOS files. The
+[compatibility follow-up](https://github.com/saphid/frame-control/pull/209) adds
+manifest `apiVersion` validation during discovery and asset serving, with
+existing manifests defaulting to version 1. It rejects incompatible panels
+even when requested through a direct asset URL.
+
+## Licences: separate download versus bundling
+
+Decky's [licence](https://github.com/SteamDeckHomebrew/decky-loader/blob/00cd202872b85868071b041c8f1b34e734147195/LICENSE)
+is GPL version 2. Frame Control is MIT-licensed. The integration contains its
+own service-management code and downloads the upstream executable as a separate
+program. It does not incorporate Decky source or ship its binary in Frame
+Control installers. Keep the upstream licence/source links visible to users
+who opt in; installing a separate GPL program does not by itself relicense
+Frame Control's independent code.
+
+If a future release bundles or mirrors Decky binaries, the distributor must
+preserve copyright/licence notices and satisfy GPLv2's corresponding-source
+requirements for the exact binary, including modifications and build scripts
+as applicable. A link to an evolving default branch is not a substitute for
+meeting those distribution obligations. Mere aggregation and deriving or
+linking a combined work are different questions; reassess the boundary if
+Decky code is incorporated. Each plugin, theme and bundled dependency has its
+own licence and assets to check independently. The existing
+[third-party notices](../THIRD_PARTY_NOTICES.md) describe software already
+distributed with Frame Control.
+
+## Next checks
+
+1. On a worn Frame, establish an accessible Decky menu or implement an adapter
+   for the VR shell. Verify a plugin's visible result and controller navigation
+   before describing store-installed plugins as usable inside VR.
+2. Verify the Frame Control panel and example extension visually, including
+   opening, refreshing and closing with the controllers.
+3. Test a normal Steam restart, reboot and SteamOS update with a disposable
+   managed install; confirm removal still works with CEF unavailable. Retain
+   the experimental label until those checks pass.
+
+The release coordinator owns those ongoing headset-integration checks. This
+retry leaves the headset untouched and hands over the research and compatibility
+follow-up instead of running concurrent loader experiments.
@@ -1,6 +1,9 @@
 # Recording and Steam clips

-Frame Control can record what the headset shows, with its sound, and save it as
+For a live OBS Media Source with headset output audio, see
+[Headset view in OBS](obs-headset-source.md).
+
+Frame Control can record SteamVR's mirrored headset view, with its sound, and save it as
 an `.mp4` on your computer. It can also export the clips and background
 recordings from Steam's own game recording, at any length, as one `.mp4` each.
 Both are on **Tools → Capture & Live**. Everything is saved to
@@ -47,15 +50,51 @@ the Frame, converted to `.mp4` there (without re-encoding) and copied to

 Recording and **Live** can run together; both read the same device.

+### Does Record include passthrough?
+
+**Yes, the MP4 recording and OBS mirror can include room passthrough.** On
+25 October 2026, SteamOS 0.5.6 build `20261022.6153909`, a safe SteamVR wake
+produced real room pixels behind panels in `/dev/video99`. Room pixels also
+appeared in decoded frames of both the OBS recording and a five-second MP4
+made with the packaged production recorder. The private room images are not
+published. See the [test record](evidence/obs-validation-2026-10-25.md).
+
+Both paths read SteamVR's `system.HeadsetView` mirror. Frame Control does not
+open raw passthrough cameras or add a camera layer. The observed mirror includes
+SteamVR's composited room and panels; it is not limited to a game's image.
+This does not promise that every game or passthrough mode appears the same way.
+The mirror can be blank in standby. Steam's own **Steam clips** use a separate
+game recording path and were not checked for passthrough in this test.
+
 ## Steam clips

 **Steam clips** lists what Steam's game recording has kept on the Frame: saved
 clips and background recordings, newest first, with the game, length and size.
-**Export** joins one into a single `.mp4` in `~/Videos/SteamFrame`, named after
-its folder (for example `clip_620_20261020_202134.mp4`), however long it is.
+**Export** joins one into a single `.mp4` under `~/Videos/SteamFrame`, named after
+its clip folder (for example `clip_620_20261020_202134.mp4`), however long it is.
 Steam's own export is reported to stop at about 60 seconds. Exports run in the
 background; ones already on your computer are marked.

+Each export keeps its headset, Steam account and complete recording session ID:
+
+```
+~/Videos/SteamFrame/headset-<id>/<account>/clips/<clip>/video/<session>/<clip>.mp4
+~/Videos/SteamFrame/headset-<id>/<account>/video/<session>/<session>.mp4
+```
+
+The headset folder uses the same short device-identity hash as screenshots.
+All folders in the Steam clip ID are kept, including nested sessions, so equal
+clip names across accounts, headsets or sessions keep separate files. Manual
+**Export** and automatic copying use the same path and saved marker. Exporting
+the same identified session again replaces only that session's export.
+
+Existing exports in the old flat `~/Videos/SteamFrame/<clip>.mp4` layout stay
+untouched. Their source identity cannot be proved, so they do not mark a clip
+as saved. Export again or use **Copy everything now** to make an identified
+copy. Automatic copying still remembers IDs copied before the upgrade; use
+**Copy everything now** to copy those again. This destination change has local
+fixture coverage; it has not been tested on a real headset.
+
 How it works: Steam keeps each recording as MPEG-DASH segments, one folder per
 recording session.

@@ -89,6 +128,18 @@ about once a minute and copies what's new with the same code as **Save** and
 **Export**: screenshots to `~/Pictures/SteamFrame`, clips to
 `~/Videos/SteamFrame`.

+Each newly saved screenshot lives under
+`~/Pictures/SteamFrame/headset-<id>/<Steam account>/<game ID>/<filename>`.
+The headset folder uses a short hash of Frame Control's device identity.
+Steam can use the same screenshot filename for two games or accounts; these
+folders keep both originals. Existing screenshots in the old flat
+`~/Pictures/SteamFrame/<filename>` layout stay where they are. They cannot be
+matched reliably to one headset and game, so **Copy everything now** can create
+a new, correctly identified copy. It never overwrites the old file.
+One real Frame screenshot was copied through this path on 25 October 2026;
+see the [test record](evidence/screenshot-copy-2026-10-25.md). The collision
+case was tested with separate fake sources, not two real same-name screenshots.
+
 - **Only what's new.** It copies what you take after turning it on, so the
  shots and clips already on the headset don't all arrive at once. **Copy
  everything now** copies everything that isn't on this computer yet, once.
@@ -107,18 +158,29 @@ about once a minute and copies what's new with the same code as **Save** and
 - **When this computer is full** (under 512 MB free, or a copy runs out of
  space) it pauses and says so in Settings and above the lists. Free some space
  and press **Resume**.
- **With several headsets** it copies from the one you're connected to.
+- **When one file keeps failing** it tries at most three times, then leaves
+  the problem visible in Settings. Fix the source problem and press **Resume**
+  to allow another three attempts without restarting Frame Control. **Copy
+  everything now** also resets failed attempts and includes older files.
+  Resume keeps the history of successful copies, so it does not recopy them.
+- **With several headsets** each check and copy belongs to the headset selected
+  when the check began. Switching between lists or copies stops that pass;
+  another headset's saved files cannot become part of its copy history.

 Settings shows when it last checked, how many files it last copied and when,
 and the last problem it had. The screenshot and clip lists say when it's on.
+Retry and switch handling have offline regression coverage with fake sources;
+see the [test record](evidence/autosync-reliability-2026-10-25.md).

 ## For developers

 `ui/frame_clips.py` holds the logic, so other features can reuse it (automatic
 copying, in `ui/frame_autosync.py`, does):

- `list_clips(run_frame)` and `export_clip(id, run_frame, run, fetch)` are the
-  computer's side; the server passes how to reach the Frame.
+- `list_clips(run_frame, device_id=...)` and
+  `export_clip(id, run_frame, run, fetch, device_id=...)` are the computer's
+  side; the server passes how to reach the Frame and its pinned device identity.
+  Both use `clip_local_path(id, device_id, folder=None)` for the destination.
 - `list_recordings(userdata)` and `export(userdata, id)` are the Frame's side,
  run as `python3 - list` / `python3 - export ID` with the file on stdin.
 - `Recorder` runs one recording from Start to the copy.
@@ -141,7 +203,8 @@ The API, with the same guards as every other request:
 They aren't available when the server runs on the Frame itself (the iPhone
 app), since they save to a computer.

-Tests: `tests/test_clips.py`, and `tests/test_autosync.py` for automatic
+Tests: `tests/test_clips.py`, `tests/test_clip_copy.py` for server destinations
+and collision coverage, and `tests/test_autosync.py` for automatic
 copying (with a fake headset). They run the recording's shell under bash with a
 stand-in `ffmpeg`, so Stop, the time limit and the clean-up are tested as they
 run on the Frame. Where `ffmpeg` is installed, they also make a 65-second DASH
@@ -13,7 +13,9 @@ count. So a build reaches people only when you publish it, after testing it.
   ```

   `.github/workflows/release.yml` builds macOS, Windows and Linux, and
-   attaches everything to a **draft** release for that tag. Nobody is
+   attaches everything to a **draft** release for that tag. After all eight
+   installers upload, the workflow also attaches `SHA256SUMS` built from
+   GitHub's SHA-256 digests of those uploaded bytes. Nobody is
   offered a draft. Editing a draft while installers are uploading can make
   GitHub temporarily show its tag as `untagged-…`. The workflow finds that
   draft by its exact version title, restores the tag association and retries
@@ -32,7 +34,9 @@ count. So a build reaches people only when you publish it, after testing it.
   ```

   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
+   are attached, each with the SHA-256 digest GitHub records. It also checks
+   that the uploaded `SHA256SUMS` digest matches a fresh list of those eight
+   installer digests. 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
@@ -46,14 +46,14 @@ unless your router's DNS registers DHCP client names.

 ```sh
 ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_frame -N '' -C "mac->steam-frame"
-ssh-copy-id -i ~/.ssh/id_ed25519_frame.pub steamos@frame.local
+ssh-copy-id -i ~/.ssh/id_ed25519_frame.pub steamos@192.168.1.40
 ```

 `~/.ssh/config` block (managed between marker lines by the script):

 ```
 Host frame
-  HostName frame.local
+  HostName 192.168.1.40
  User steamos
  IdentityFile ~/.ssh/id_ed25519_frame
  IdentityFile ~/.ssh/id_rsa_frame_devkit
@@ -62,6 +62,10 @@ Host frame
 ```

 The script only asks for the password if the pairing below doesn't work.
+Replace the example IP with the one in the Frame's Quick Settings. SteamOS
+0.5.6 stopped publishing `.local` names; an existing SSH alias or the headset's
+current IP is more reliable. Frame Control remembers authenticated IPs per
+network and checks the saved SSH identity on reconnect.

 ## Password-free pairing (SteamOS devkit service)

@@ -0,0 +1,92 @@
+# Steam desktop sharing on a Linux PC
+
+**Tools → Steam desktop sharing** helps with Steam's own `steam -pipewire`
+desktop-in-headset flow on a local Wayland PC. It needs no Frame connection.
+It is separate from Frame Control's [PC in the headset](pc-in-headset.md),
+which remains disabled on Linux. Steam and the desktop portal own the capture,
+screen picker and headset flow; this helper does not provide a stream.
+
+## Launch Steam with PipeWire
+
+Save your game and use **Steam → Exit** first. Then click **Launch Steam with
+PipeWire**. Frame Control checks this user's local processes, finds `steam` on
+PATH, and requests `steam -pipewire`. This flag applies to that launch only.
+No Steam settings, login files or startup entries are changed. An existing
+Steam session is never stopped, signalled or silently switched.
+
+If Steam or a Steam launcher/helper is running, the button explains that Steam
+must be exited first. If the process inventory cannot be read, it refuses to
+launch. It also refuses root, SSH, headless, X11 and Flatpak-sandboxed Frame
+Control sessions. Run Frame Control as your normal user in the local Wayland
+desktop with its session bus.
+
+For a Flatpak-only Steam install without a `steam` command on PATH, the helper
+provides a manual command instead of choosing an installation for you. After
+exiting Steam, run `flatpak run com.valvesoftware.Steam -pipewire` in a local
+terminal. Flatpak Steam processes are included in the existing-session check.
+
+A successful request is **not confirmation of a picker or stream**. Steam may
+exit or fail after the initial check, and another launcher can race the local
+process check. Do not start Steam elsewhere at the same time. If nothing opens,
+run the command yourself in a terminal to see Steam's error.
+
+## Reset screen-share choice
+
+Click **Reset screen-share choice…** to request KDE's **Application Permissions**
+page. This button does **not** revoke anything or report a completed reset.
+Frame Control cannot reliably map a Steam runtime display name to a
+Steam-specific portal grant or restore token across backends. It never reads,
+edits or clears the portal permission store or Steam tokens.
+
+On KDE:
+
+1. Open **System Settings → Applications → Application Permissions** if the
+   button cannot open it.
+2. Find the entry for Steam. The Ubuntu 26.04 KDE report showed **Steam Linux
+   Runtime 3.0**. That display name alone is not proof that every session there
+   is safe to remove; verify the session belongs to your Steam desktop share.
+3. Under **Screen sharing**, choose **Manage 1 Session** (the count may differ).
+4. Choose **Revoke** for that verified session only. **Do not use Revoke All**
+   or change another application's grants. If ownership is ambiguous, stop.
+5. Retry Steam's desktop sharing flow. The reporter saw the portal picker again
+   after revoking that session. Results can differ by Steam and portal version.
+
+The reported entry sometimes appeared intermittently. If it is missing, do not
+clear other entries or the whole portal store. Check again when Steam's sharing
+session is present. If **Application Permissions** itself is missing on
+Ubuntu/Kubuntu, check your distribution's `kde-config-flatpak` package: the
+reporter needed that package and a reboot before the page appeared. Frame
+Control does not install packages, reboot, request root or change security
+settings. Older KDE modules may lack this page; other desktops receive guidance
+only, with no automatic reset or guessed permission target.
+
+The launcher uses `kcmshell6 --list` to verify the exact module, then
+`kcmshell6 kcm_app-permissions`. It does not substitute the older Flatpak-only
+page. A request to open the page does not prove that a window became visible.
+
+## Evidence and limits
+
+- User-supplied report and screenshot description:
+  [ExpressGinga81's thread and replies](https://x.com/ExpressGinga81/status/2113242533530911058).
+  The report describes Ubuntu 26.04 KDE, the initial picker appearing once,
+  the Steam Linux Runtime 3.0 entry, and Revoke making the picker reappear.
+  This is reported behavior, not a live test performed for this feature.
+- KDE upstream [`flatpak-kcm`](https://github.com/KDE/flatpak-kcm):
+  `CMakeLists.txt` and `kcm_app-permissions.json` identify Application
+  Permissions; `ui/SessionList.qml` distinguishes Revoke from Revoke All.
+- Automated tests mock Steam, processes and KDE commands. HTTP tests verify
+  request guards, no actions on GET, and no headset work. Existing CI discovers
+  these tests on Linux, macOS and Windows; they do not need a desktop portal.
+- lxso2 has no interactive Wayland/PipeWire portal for a chooser test.
+  **No live chooser, revoke, Steam launch or headset display is verified here.**
+  No Frame access was performed for this task, including during the hold before
+  2026-10-24 13:00 UTC. The helper never invokes SSH or Frame controls.
+
+## Announcement
+
+Linux Wayland users can now find **Steam desktop sharing** under Tools to
+request Steam with `-pipewire` after exiting Steam, or open KDE's Application
+Permissions to revoke only a verified Steam screen-sharing session and try the
+picker again. Frame Control does not clear permissions automatically. This is
+help for Steam's own desktop-sharing flow; Frame Control's Linux capture
+feature remains disabled. Live picker behavior still needs desktop validation.
@@ -0,0 +1,67 @@
+# SteamOS October 2026 compatibility
+
+SteamOS 3.9.5 is the **PC host / Steam Machine** update. It is not the Frame
+headset OS. The headset release discussed here is **SteamOS 0.5.6 beta**.
+
+## Finding and connecting to the headset
+
+SteamOS 0.5.6 stopped publishing mDNS names, including `frame.local`. Existing
+addresses in Frame Control still work if they resolve, and the app tries all
+saved addresses. After an authenticated connection through a `.local` name,
+Frame Control also remembers the numeric IP on that network. If the name stops
+resolving, it tries that IP and checks the same pinned SSH identity before using
+it. The IP is never reused automatically on a different network.
+
+In **Devices**, **Find on this network** checks the SteamOS devkit advertisement,
+known IPs and the local IPv4 `/24`. It offers scan results only when their SSH
+key matches the headset's saved key. The scan is bounded to a private subnet;
+it cannot find a headset across a router or on another subnet. Enter the IP
+shown in the headset's Quick Settings in the address field in those cases.
+For initial pairing, **Set Up Connection** accepts a manual IP and reuses an
+existing `~/.ssh/config` `HostName` before trying mDNS. A configured SSH alias
+continues to work. Frame doctor no longer assumes `frame.local`: supply
+`--lan <IP>` when a separate LAN route is needed.
+
+## SteamOS script names
+
+Session switching already prefers `holo-session-select` over
+`steamos-session-select`, after the Frame's `steamosctl` control. Desktop
+process detection accepts `holo-nested-desktop` and its old name. The sideload
+helper prefers `holo-prepare-upload` and `holo-delete` if a future devkit
+provides them, falling back to the vendored `steamos-*` scripts. The devkit
+service name `_steamos-devkit._tcp` is a protocol identifier, so it is not
+renamed.
+
+## SteamOS 3.9.5 Linux PC hosts
+
+NetworkManager's `nmcli` supplies the active SSID and route diagnostics; the
+SSID reader falls back to `iwgetid`. Neither depends on whether NetworkManager
+uses wpa_supplicant (new installs) or iwd (upgraded installs). The current code
+does not manage either backend or the Steam Frame Wireless Adapter. An adapter
+doctor belongs in its own PC host feature.
+
+## Android APKs and telemetry
+
+The 0.5.6 Desktop Mode **Add to Steam** action for `.apk` files is another way
+to make a Steam library entry. Frame Control already creates a non-Steam
+shortcut for every installed APK through the running Steam client's API, with
+its own persistent Lepton instance and artwork. It does not edit
+`shortcuts.vdf` or require a Steam restart, so no extra shortcut option is
+needed in its install flow.
+
+The battery reader selects a system battery by power-supply `type` and `scope`
+and reads standard sysfs fields. The memory reader uses `/proc/meminfo`.
+Neither relies on the performance overlay's labels or hard-coded SteamOS
+paths. SteamOS 0.5.6's improved overlay reporting does not establish a sysfs
+path change. A live check on build `20261022.6153909` confirmed that Frame
+Control's existing readers return battery and memory values. The dominant-eye
+setting is not read yet; recording metadata must not claim an eye until its
+source and effect on `/dev/video99` are verified. The same check found the
+`beta` update branch, but the normal user could not query update availability
+through Atomupd; no update was applied. See the
+[live evidence](evidence/steamos-compat-live-2026-10-25.md).
+
+Sources: [SteamOS 3.9 news](https://store.steampowered.com/news/app/1675200),
+[Frame OS news](https://steamcommunity.com/app/4165890/allnews/), and the
+Frame Control implementation in `ui/frame_network.py`, `ui/frame_status.py`,
+`ui/frame_android.py`, `ui/frame_link.py` and `frame/android/steam_shortcuts.py`.
@@ -0,0 +1,20 @@
+# Share the Frame view in Discord
+
+1. Start the **OBS source** in Frame Control and add it to OBS as described in
+   [Headset view in OBS](obs-headset-source.md). Confirm that OBS shows the
+   headset mirror and that its audio meter moves before joining a call.
+2. In OBS, click **Start Virtual Camera**. In Discord's **Voice & Video**
+   settings, select **OBS Virtual Camera** as the camera, then turn it on in the
+   call. This sends the OBS scene as video.
+3. If the call needs the Frame's game sound, route OBS's monitored Media Source
+   audio to a virtual audio input installed on your computer, then select that
+   input as Discord's microphone. Keep headphones on to avoid feedback. Test
+   this in a private call first; a virtual camera alone carries no audio.
+4. Stop the OBS source in Frame Control when you finish. It closes the SSH
+   stream; OBS may keep showing its last frame until the source is hidden.
+
+Frame Control sends the Frame's **output audio**, not its microphone. Discord
+audio routing differs by computer and requires a separate virtual audio device
+if you want game sound in the call. This guide has not been verified in a real
+Discord call. The SteamVR mirror can be blank while the headset is idle, and
+the mirror can include real room passthrough behind panels. Check the scene before sharing.
@@ -154,10 +154,31 @@ 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).

-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.
+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.)
+
+The server keyboard queue holds at most 200 events, including text being sent.
+A batch with an accent sends its whole keyboard part through KDE Connect, and
+later keys follow it there while typing is pending. If the batch will not fit,
+the server rejects it before sending any clicks or keys; the page keeps it and
+retries after polling. Accepted events are never evicted to make room. A timeout
+or helper failure retains unsent text and shows **Try again**; that button resumes
+the retained queue. The queue lives in memory and is lost if the server exits.
+Switching headsets cancels queued text and stops both input helpers before the
+new route is published. Both controls validate the intended headset before they
+start. Ordering between the two input services uses a typing-time estimate;
+neither service acknowledges when characters reach the application.
+
+[PR #66 verification on 2026-10-24](evidence/pad-gamescope-2026-10-24.md)
+records an owned focused X11 panel receiving a click and `Frame66` plus Enter
+on a real Frame with SteamOS 0.5.6, after the shared headset became available.
+The helper, window and owner-marked lock were cleaned up. This is ASCII input
+proof, not wearer-visible, Unicode or packaged Electron GUI verification.

 **Verified 2026-09-28** (SteamOS 0.4.1, build 20260925.6191901):

@@ -52,6 +52,7 @@
 <body>
 <main>
  <h1>Frame Control 0.3.1: features by OS</h1>
+  <p><strong>This is a September 2026 archive.</strong> For current coverage and hardware limits, read the <a href="current-support-matrix.md">v0.4.25 support matrix</a>.</p>
  <p class="sub">Which features are built for each OS, and which were tested against a real Steam Frame
    (SteamOS 0.3.0, build 20260922.6101926). Status as of 26 September 2026, for
    <a href="https://github.com/saphid/steam-frame/pull/2">PR #2</a> (0.3.1). Every build now bundles its own
@@ -12,6 +12,31 @@ A fourth, a SteamOS VM, may come later ([issue #6](https://github.com/saphid/ste

 ## Unit tests

+Automatic screenshot and clip copying has offline coverage in
+`tests/test_autosync.py`:
+
+```sh
+python3 -m unittest discover -s tests -p test_autosync.py -v
+```
+
+Fake sources exercise the three-attempt limit, visible exhausted errors,
+Resume/Copy everything now recovery, successful-copy deduplication, disk-full
+pauses and headset changes around lists and transfers. Server tests use the
+production `working(meant)` reservation and listing/copy adapters; a Node test
+executes the Settings renderer to check that Resume is available after an error.
+These tests use no headset. See the
+[auto-sync reliability test record](evidence/autosync-reliability-2026-10-25.md).
+
+The gamescope keyboard/trackpad route has focused suites in `test_input.py`,
+`test_touch.py` and `test_service_regressions.py`. They cover pad translation,
+ASCII/modifier keys, Unicode queuing/retries, stale panel targets, release
+handling, route cancellation, and intended-headset start/status guards.
+`tests/page/pad_queue.mjs` and `tests/page/ctrl_gestures.mjs` execute the page's
+real queue and gesture functions in Node. These are offline tests; their
+acknowledgements do not prove that a real application received input.
+See [the 2026-10-24 PR #66 evidence](evidence/pad-gamescope-2026-10-24.md)
+for the real focused-panel click/key observation, cleanup and remaining limits.
+
 The read-only power/heat sampler has fixture and transport tests in
 `tests/test_power_sample.py`. Run
 `python3 -m unittest discover -s tests -p test_power_sample.py -v`.
@@ -178,6 +203,11 @@ scripts/frame-smoke.sh           # needs `ssh frame` to work without a password
 scripts/frame-smoke.sh --pair    # also pairs a throwaway key: approve it in the headset
 ```

+The wrapper uses POSIX `sh` and Python 3 on macOS or Linux; zsh is not required.
+It resolves the checkout path independently of the current working directory.
+`/path/to/checkout/scripts/frame-smoke.sh --help` is safe to run offline and
+does not contact the headset.
+
 It checks `properties.json` and the status, then installs, launches and
 removes three tiny titles built from bytes by `tests/smoke/tiny_programs.py`
 (an ARM64 and an x86-64 static Linux program that sleep for ten seconds, and
@@ -198,6 +228,14 @@ isn't reachable.
 Smoke process cleanup runs before and after title removal and during the
 initial/final leftover sweeps. It targets only the reserved `fc_smoke_arm64`,
 `fc_smoke_x86_64`, `fc_smoke_exe` IDs and their legacy `fc-smoke-` equivalents.
+Each leftover sweep checks all six IDs, even if no title directory or install
+record remains. It removes their exact `-argv.json`, `-env.json`,
+`-settings.json` and `-framecontrol.json` files, syncs Steam's shortcuts, then
+syncs again to verify that none of those IDs is still registered. Missing
+devkit utilities are copied before syncing and removed at the end if they
+were absent before the run. Metadata or shortcuts that remain, or a reported
+sync failure, fail cleanup. Similarly named titles and their metadata are
+outside the deletion boundary.
 On the target, `tests/smoke/stop_processes.py` requires the SSH user's uid and
 an exact title directory in `/proc` cwd/exe or an individual absolute command
 argument; similarly named folders and shell command substrings do not count.
@@ -221,12 +259,23 @@ The `fc_smoke_exe` launch ran under Proton Experimental (ARM64), and its
 remove step stopped five test-owned wrapper/Proton PIDs before removing the
 title; the following process sweep found none. The final cleanup found no
 test titles or processes, the test desktop was closed, and the battery
-remained at 99%. The `scripts/frame-smoke.sh` zsh wrapper could not run
-on lxso2 because zsh is absent; `python3 tests/smoke/frame_smoke.py` ran
-the same entry point instead.
+remained at 99%. That historical run used the Python entry point directly;
+the current POSIX wrapper has local offline coverage on a PATH without zsh.
+The current runner and all-six-ID cleanup sweeps passed another 13-step real
+Frame run on 25 October, build `20261022.6153909`, at source commit `1255ef2`.
+The Windows title's remove step stopped five test-owned Proton/wrapper PIDs;
+the final sweep and independent readback found no reserved files or processes.
+SteamVR stayed running, observed focus properties matched before/after, and
+this task's shared lock was released. The headset was unworn. This run did
+not seed synthetic orphan metadata or shortcuts; those cases use local
+fixtures. [Sanitized results](evidence/round2-smoke-2026-10-25.json).
 The local regression suite runs real Linux processes in temporary fake title
 directories (including deleted folders and a TERM-resistant wrapper); it checks
-exit, escalation and survival of unrelated processes without SSH or a headset:
+exit, escalation and survival of unrelated processes. Local filesystem commands
+with mocked SSH/Steam also cover orphan metadata, shortcut-only leftovers,
+sync failures and exact ID boundaries. Wrapper tests check offline help,
+argument forwarding and exit status from another working directory. None of
+these local tests contacts a headset:

 ```sh
 python3 -m unittest discover -s tests -p test_smoke_cleanup.py -v
@@ -473,3 +522,19 @@ rule, which the original source-only assertion missed. Check computed wrapping,
 the complete explanation, tooltip punctuation, Refresh bounds and selection
 after **Use this headset** when changing these styles. This fixture does not
 exercise Electron integration or a real SSH identity change.
+
+
+## PC-only Windows wireless diagnosis
+
+```sh
+python3 -m unittest discover -s tests -p 'test_wireless.py' -v
+node --test tests/wireless.cjs
+```
+
+The checks workflow runs this targeted suite on Windows, including the real
+read-only PowerShell query, and the normal server suite includes it on all
+platforms. HTTP tests instantiate only a handler, never the app connector.
+Fixtures cover duplicate instance identity, unknown states, GUID matching,
+localised/denied channel data and 6 GHz ambiguity. No tests contact a real Frame.
+A Windows CI runner/VM cannot prove physical Steam dongle behaviour or audio RF
+interference. See [sources and limits](windows-wireless-doctor.md).
@@ -0,0 +1,141 @@
+# Windows Wireless Adapter doctor
+
+Open **Tools → This PC → Wireless Adapter doctor**, then choose **Read PC
+adapters**. It works without a headset connection. It only queries this Windows
+PC, with no automatic polling, changes, elevation or UAC prompt. It never
+contacts the Frame. A direct `#wireless` link on another platform explains that
+Windows is required.
+
+The snapshot shows:
+
+- Exact network PnP instance IDs, including non-present devices, with separate
+  presence, PnP status/problem code, operational state and media connection state.
+- Microsoft Wi-Fi Direct Virtual Adapter candidates and their distinct instance
+  count. `SWD\WIFIDIRECT\` is enumerator evidence; an English device-name match
+  is explicitly labelled **Name only**. A repeated row for one ID is counted once.
+- PC Wi-Fi interfaces, hardware-interface status and whether Windows has a
+  default route configured on an interface. Neither a route nor **Up** proves
+  that Steam uses that adapter. Multiple configured defaults are possible.
+- Reported channel and band, when `netsh wlan show interfaces` supplies recognised
+  English fields and an exact matching interface GUID. Missing, localised,
+  disconnected or denied readings remain **Unknown**. There is no name-based
+  channel association. A PC's router channel is not the Steam dongle's channel.
+- Possible spectrum overlap when an interface reports **2.4 GHz**, without
+  claiming interference. With no such reading, overlap stays **Unknown**:
+  unreported virtual/proprietary radios and audio dongles may still use 2.4 GHz.
+  Channel 1–14 alone does not identify a band: 6 GHz reuses low channel numbers.
+
+## Why there is no disable button
+
+[夕凪's report](https://x.com/Oo_yuunagi_oO/status/2113904070352343135)
+(24 October 2026) says extra Microsoft Wi-Fi Direct Virtual Adapter instances
+appear when their wireless adapter becomes unavailable, and disabling the newly
+appeared one *seems* to stop recurrence. This is useful owner evidence, but does
+not establish which instance would be safe to disable on another PC.
+
+Windows can legitimately create several Wi-Fi Direct virtual interfaces.
+A `#2` suffix is not a creation timestamp; non-present, down, or disconnected
+status is not proof of an unused instance. The inventory does not reliably map
+Steam's active radio/session to an expendable PnP instance. Disabling the wrong
+one could interrupt streaming, PC Wi-Fi, Mobile Hotspot or wireless displays.
+Frame Control therefore supplies evidence and guidance, with no disable,
+re-enable, driver removal or other write endpoint. It never changes security or
+location settings, requests administrator access, or bypasses execution policy.
+
+Before any manual changes, retain the exact instance IDs and compare snapshots
+before/after a drop with Steam Support. Do not disable a device based only on
+this report. A future disable feature needs a verified Steam adapter/session
+mapping, fresh protection for primary/active instances, explicit confirmation
+for one exact instance, and a tested recovery path that re-enables that same ID.
+
+## When a stream drops immediately or the adapter will not reconnect
+
+Read PC adapters **before** starting a stream, then refresh immediately after a
+drop. Compare the *exact* PnP instance IDs, presence and problem codes. Note
+whether the PC's own Wi-Fi drops too. A new `#2` name is not proof that this
+instance caused the failure. Keep the time of the drop and the two snapshots
+for Steam Support; the doctor does not save or upload them.
+
+The app shows **Changes since previous read** after the second click. It
+compares exact PnP IDs, known status fields and reported channels/bands; an
+unknown value is never treated as a state change. If the PnP source was
+unavailable in either read, it declines to compare devices. Each successful
+read becomes the baseline for the next one. **Forget previous read** clears the
+baseline and comparison; closing the app clears them too. The before/after
+comparison stays in local memory and is not uploaded or added to telemetry.
+Reported changes can reflect sequential query timing or a service recovering,
+not a fault or permission to disable any instance.
+
+To narrow a drop at stream start, try one condition at a time: wired PC
+networking instead of PC Wi-Fi, wired headphones instead of 2.4 GHz audio, and
+spacing the USB radio dongles apart. Recheck the stream after each change. The
+PC Wi-Fi channel in this report is not the Steam dongle's channel, so a matching
+or different number does not establish interference.
+
+If the adapter will not reconnect, stop the failed stream and close Steam's
+streaming session before touching its USB connection. Refresh the inventory. If
+the dongle is absent, reconnect it once at the PC, understanding that this
+interrupts any connection using it, then refresh again. If the **same exact**
+PnP instance now reports problem code 22 (disabled), review that instance in
+Windows Device Manager and its normal enable action. Do not enable or disable a
+different numbered instance by guesswork. For a missing device or another
+problem code, record the before/after ID and code for Steam Support; do not
+guess a driver or change security settings.
+
+These are user-controlled checks, not an automatic repair. We have no physical
+Steam Wireless Adapter dropout to reproduce and no verified mapping from a
+Wi-Fi Direct virtual instance to Steam's active session. An in-app disable and
+re-enable control remains deferred until that mapping and a recovery path are
+tested on real hardware.
+
+## Checking a 2.4 GHz audio conflict
+
+[Deko's report](https://x.com/DekoDrak/status/2113412044644897023)
+(22 October 2026) describes Razer wireless-headset interference and temporarily
+disabling the Steam Frame dongle. It also mentions a PC/Wi-Fi shutdown during
+Windows Update and asks whether the dongle caused it. The post does not prove
+that connection or specify a measured audio radio channel. Treat the suggested
+2.4 GHz conflict as a hypothesis, not a diagnosis of the shutdown.
+
+Try wired audio briefly, separate radio dongles with a USB extension lead, or
+compare PC Ethernet / an existing 5 or 6 GHz network. Change one thing at a time
+and record whether symptoms recur. The doctor cannot measure RF congestion,
+read an audio dongle's channel, identify a faulty driver, or prove a dropout fix.
+
+## Sources, privacy and limits
+
+The single local PowerShell process uses `Get-PnpDevice -Class Net`, its
+`-PresentOnly` variant, `Get-NetAdapter -IncludeHidden`, `Get-NetRoute` for
+IPv4/IPv6 defaults, and `netsh wlan show interfaces`. Each source reports
+availability separately. Access denial, unavailable cmdlets/services and
+unsupported features produce partial/unknown results; there is no permission
+workaround. Queries run sequentially, so even one snapshot can span a state
+change. One probe runs at a time, with a 20-second process timeout.
+
+SSIDs, MAC addresses and raw command/error output are omitted from the API/UI.
+PnP IDs and adapter/interface names can identify this PC; review before sharing.
+The tool does not send or save reports, and does not add these readings to
+telemetry or problem-report diagnostics. Copy relevant text manually if needed.
+
+The shipped basic network-identity probe (`frame_network.py`) finds a gateway,
+network name and Tailscale state. It does not inventory virtual adapters or
+check channel overlap. The new doctor is a separate, explicit PC query.
+
+## Verification
+
+`tests/test_wireless.py` checks duplicate identity, presence/disabled/link
+separation, ambiguous joins, partial sources, privacy filtering, 6 GHz/channel
+ambiguity, localisation, missing band and denied output. HTTP tests require the
+UI key, reject headset-local mode, and assert no SSH call. `tests/wireless.cjs`
+executes the production UI with boundary fixtures: navigation starts no query,
+clicks query once, unknown values and failure/retry remain visible, and PnP IDs
+and names are escaped as text.
+
+Windows CI also executes the real read-only PowerShell probe against the
+runner's network devices. That proves Windows query execution, not a physical
+Steam dongle, Wi-Fi Direct session or Razer headset. See the PR for exact CI
+results. An existing local Windows 11 VM passed 15 targeted tests (one UI test skipped
+because Node is absent), including the live query. PnP, presence, adapters and
+routes were available; WLAN was unavailable in this VM. See
+[VM evidence](evidence/windows-wireless-2026-10-24.md). No Frame was accessed; no physical
+adapter/dropout fix or RF measurements are claimed.
@@ -0,0 +1,43 @@
+# Wired connection doctor
+
+If you use a USB-C cable because the Wireless Adapter is unreliable, open
+**Devices & connection → Wired connection doctor** in the desktop app. Enter
+the headset's configured SSH alias and click **Check cable connection**. From
+a source checkout, run `python3 scripts/frame-wired-doctor.py --alias frame`.
+
+The on-demand check reads the computer's selected route to the Frame USB
+address, checks whether port 22 answers, then runs remote `true` over SSH with
+the existing pinned host key. It does not change network settings or the
+headset, accept a new key, or attempt a password. A failure is shown as unknown
+or warning; the doctor never claims a cable works from an IP address alone.
+
+The known address is `10.86.200.233` on the Frame's `10.86.200.232/29` USB
+network. A Mac with the Frame attached used `10.86.200.234/29` and completed a
+strict SSH login on 2026-09-28; see [the observed link](how-the-frame-works.md).
+If the route check says unknown, first confirm a data-capable USB-C cable, a
+visible PC network interface and a current Frame OS build. Other OS builds may
+use another subnet. If the port answers but SSH identity fails, connect using
+the normal pinned headset alias and resolve the pairing or key warning there;
+do not disable host-key checking.
+
+This checks **Frame Control's SSH route**, not whether SteamVR's game stream
+uses the cable. The Wireless Adapter and Steam streaming can follow a different
+path. No cable is attached to the Linux test host, so this exact UI has only
+synthetic route/SSH tests. Windows and Linux physical USB-C behavior, and a
+fresh wired readback on the current Frame OS, remain unverified.
+
+## If SSH works but the game stream stops
+
+If the stream fails on USB, Wi-Fi and the Wireless Adapter, but this doctor
+reports a working SSH route, check SteamVR on the **PC**. Frame Control's
+`frame.local` reconnect only restores its headset management connection. It
+does not restart PC SteamVR or repair the game stream. On a Windows or Linux
+PC, save your work and close the VR game. Exit SteamVR from Steam on that PC,
+then start it again. This can show whether a PC SteamVR session is stuck; it
+does not fix the cause of repeated drops. SteamVR on macOS is not a supported
+PC streaming host.
+
+Frame Control has no verified cross-platform command that safely stops only
+the intended PC SteamVR session. A forced restart could close a running game
+and lose unsaved progress. For that reason the app gives manual steps and does
+not add a one-click restart button.
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<link rel="stylesheet" href="style.css">
+<title>Headset Glance</title>
+<main>
+  <h1>Headset Glance</h1>
+  <p id="summary">Reading the headset status…</p>
+  <button id="refresh">Refresh</button>
+</main>
+<script src="main.js"></script>
+</html>
@@ -0,0 +1,29 @@
+let nextId = 0;
+const pending = new Map();
+
+window.addEventListener('message', event => {
+  if (event.source !== parent || event.data?.type !== 'frame-control:response') return;
+  const resolve = pending.get(event.data.id);
+  if (resolve) {
+    pending.delete(event.data.id);
+    resolve(event.data.value);
+  }
+});
+
+function request(action) {
+  return new Promise(resolve => {
+    const id = ++nextId;
+    pending.set(id, resolve);
+    parent.postMessage({type: 'frame-control:request', id, action}, '*');
+  });
+}
+
+async function refresh() {
+  const status = await request('status');
+  document.getElementById('summary').textContent = status.connected
+    ? `Frame OS ${status.os.version || 'unknown'} · Battery ${status.battery.percent ?? '?'}% · SteamVR ${status.steamvr ? 'running' : 'stopped'}`
+    : 'No headset status is available yet.';
+}
+
+document.getElementById('refresh').addEventListener('click', refresh);
+refresh();
@@ -0,0 +1,8 @@
+{
+  "id": "headset-glance",
+  "name": "Headset Glance",
+  "version": "1.0.0",
+  "apiVersion": 1,
+  "description": "Shows a small read-only summary of the connected Steam Frame.",
+  "entry": "index.html"
+}
@@ -0,0 +1,4 @@
+body { margin: 0; background: #101820; color: #dcdedf; font: 16px system-ui, sans-serif; }
+main { padding: 24px; }
+h1 { font-size: 20px; }
+button { border: 0; border-radius: 4px; padding: 8px 14px; background: #1a9fff; color: #fff; cursor: pointer; }
@@ -73,7 +73,11 @@ discover_devkit() {
 pick_host() {
  local candidates=()
  [[ -n "$host_arg" ]] && candidates+=("$host_arg")
-  [[ -z "$host_arg" ]] && candidates+=("$FRAME_ALIAS.local" "$FRAME_ALIAS")
+  if [[ -z "$host_arg" ]]; then
+    local saved=$(ssh -G "$FRAME_ALIAS" 2>/dev/null | awk '$1 == "hostname" {print $2; exit}')
+    [[ -n "$saved" && "$saved" != "$FRAME_ALIAS" && "$saved" =~ $HOST_RE ]] && candidates+=("$saved")
+    candidates+=("$FRAME_ALIAS.local" "$FRAME_ALIAS")
+  fi
  local h
  for h in "${candidates[@]}"; do
    if reachable "$h"; then
@@ -224,6 +228,7 @@ pair_with_devkit() {
 print "==> Looking for the Steam Frame"
 if ! HOST=$(pick_host); then
  print -u2 "Could not reach the Frame on port 22 or $DEVKIT_PORT."
+  print -u2 "SteamOS 0.5.6 stopped publishing .local names; use its IP from Quick Settings."
  print -u2 "Check: Developer Mode on + user password set; same Wi-Fi; no client isolation."
  print -u2 "Then re-run with the IP from Quick Settings: scripts/connect.sh 192.168.x.y"
  exit 1
@@ -1,8 +1,9 @@
-#!/usr/bin/env zsh
+#!/bin/sh
 # Mac or Linux: the headset smoke test. Installs, launches and removes tiny
 # test titles on the Frame (the `frame` alias) and records the results with
 # its BUILD_ID under tests/smoke/results/. See docs/testing.md.
 #
 # Usage: scripts/frame-smoke.sh [--pair]   (--pair needs you in the headset to approve)
-set -euo pipefail
-exec python3 "${0:A:h:h}/tests/smoke/frame_smoke.py" "$@"
+set -eu
+smoke_root=$(CDPATH= cd "$(dirname "$0")/.." && pwd -P)
+exec python3 "$smoke_root/tests/smoke/frame_smoke.py" "$@"
@@ -0,0 +1,10 @@
+#!/usr/bin/env python3
+"""Source-checkout entry point for the PC's read-only USB-C route checks."""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / 'ui'))
+from frame_wired_doctor import main  # noqa: E402
+
+if __name__ == '__main__':
+    raise SystemExit(main())
@@ -293,7 +293,7 @@ def load_baseline(path):
 def main(argv=None):
    parser = argparse.ArgumentParser(description='Read-only Frame setup diagnostics. Never pairs, repairs or asks for a password.')
    parser.add_argument('--alias', default='frame', help='Existing trusted SSH alias (default: frame)')
-    parser.add_argument('--lan', default='frame.local', help='LAN fallback host/IP')
+    parser.add_argument('--lan', help='Optional LAN IP or host name; SteamOS 0.5.6 no longer publishes .local names')
    parser.add_argument('--usb', default='10.86.200.233', help='USB fallback IP; use only with the intended headset connected')
    parser.add_argument('--plan', action='store_true', help='Print a read-only repair plan from recognized evidence')
    parser.add_argument('--save-report', metavar='FILE', help='Create a local JSON baseline (never overwrite an existing file)')
@@ -307,6 +307,8 @@ def main(argv=None):
            print('UNKNOWN Baseline: Cannot read a valid doctor report; no comparison performed.')
            return 2
    for value in (args.alias, args.lan, args.usb):
+        if value is None:
+            continue
        if not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,252}', value):
            parser.error('Use a plain alias, hostname or IP address.')
    print('Frame doctor: read-only; no passwords, pairing, repairs or raw logs. Reports are saved only with --save-report.')
@@ -327,7 +329,11 @@ def main(argv=None):
        print('UNKNOWN Baseline: SSH target configuration differs; comparison refused.')
        return 2
    source = Path(__file__).read_text()
-    for label, host in (('configured alias (Tailscale if configured)', None), ('LAN', args.lan), ('USB-C', args.usb)):
+    routes = [('configured alias (Tailscale if configured)', None)]
+    if args.lan:
+        routes.append(('LAN', args.lan))
+    routes.append(('USB-C', args.usb))
+    for label, host in routes:
        result = run(ssh_args(args.alias, host, identity) + ['python3 -B - --probe'], timeout=90, input=source)
        if result is not None and result.returncode == 0:
            try:
@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Bounded, opt-in real Frame check. Run only while someone wears the headset.
+
+Requires an already installed Frame Control VR panel, Decky user service, and
+one Framey-managed plugin. It never installs, restarts, or removes a service.
+"""
+import datetime
+import hashlib
+import json
+from pathlib import Path
+import re
+import secrets
+import shlex
+import subprocess
+import sys
+import time
+
+ROOT = Path(__file__).resolve().parents[1]
+SSH = ['ssh', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=5', 'frame']
+LOCK = '/tmp/frame-test.lock'
+
+
+def remote(command, stdin=None, timeout=15):
+    run = subprocess.run([*SSH, command], input=stdin, capture_output=True,
+                         text=True, timeout=timeout)
+    if run.returncode:
+        raise RuntimeError((run.stderr or run.stdout).strip() or f'SSH exited {run.returncode}')
+    return run.stdout
+
+
+PROBE = r'''
+import json, pathlib, subprocess
+power=[]
+for item in pathlib.Path('/sys/class/power_supply').glob('*/capacity'):
+    try:
+        if (item.parent/'type').read_text().strip() == 'Battery':
+            power.append({'name':item.parent.name,'percent':int(item.read_text().strip())})
+    except (OSError,ValueError): pass
+stats=subprocess.run(['/opt/steamvr/bin/linuxarm64/vrcmd','--stats'],capture_output=True,text=True,timeout=5)
+try: activity=json.loads(stats.stdout)[0]['activity_level'] if stats.returncode == 0 else None
+except (ValueError,KeyError,IndexError,TypeError): activity=None
+panels=subprocess.run(['/opt/steamvr/bin/linuxarm64/vrcmd','--overlays'],capture_output=True,text=True,timeout=5)
+panel=next((line.strip() for line in panels.stdout.splitlines() if 'valve.steam.desktopgame.2001947813' in line),None)
+base=pathlib.Path.home()/'.local/share/frame-control/decky/plugins'
+plugins=[]
+if base.is_dir() and not base.is_symlink():
+    for folder in base.iterdir():
+        if folder.is_symlink(): continue
+        try:
+            p=json.loads((folder/'.frame-control-store.json').read_text())
+            manifest=json.loads((folder/'plugin.json').read_text())
+            if isinstance(p.get('storeId'),int): plugins.append({'id':p['storeId'],'name':manifest['name']})
+        except (OSError,ValueError,KeyError): pass
+service=subprocess.run(['systemctl','--user','is-active','frame-control-headset.service'],capture_output=True,text=True)
+print(json.dumps({'battery':power,'activity':activity,'panel':panel,
+                  'panelService':service.returncode==0,'plugins':plugins}))
+'''
+
+OVERLAY_PROBE = r'''
+import ctypes as C, json
+vr=C.CDLL('/opt/steamvr/bin/linuxarm64/libopenvr_api.so')
+vr.VR_InitInternal2.argtypes=[C.POINTER(C.c_int),C.c_int,C.c_char_p]
+vr.VR_GetGenericInterface.argtypes=[C.c_char_p,C.POINTER(C.c_int)]
+vr.VR_GetGenericInterface.restype=C.c_void_p
+error=C.c_int()
+vr.VR_InitInternal2(C.byref(error),3,None)
+result={'visible':None,'dashboardVisible':None,'error':error.value}
+if not error.value:
+    try:
+        table=C.cast(vr.VR_GetGenericInterface(b'FnTable:IVROverlay_028',C.byref(error)),C.POINTER(C.c_void_p))
+        if not error.value and table:
+            handle=C.c_uint64()
+            find=C.CFUNCTYPE(C.c_int,C.c_char_p,C.POINTER(C.c_uint64))(table[0])
+            if find(b'valve.steam.desktopgame.2001947813',C.byref(handle))==0:
+                result['visible']=bool(C.CFUNCTYPE(C.c_bool,C.c_uint64)(table[45])(handle))
+                result['dashboardVisible']=bool(C.CFUNCTYPE(C.c_bool)(table[68])())
+    finally: vr.VR_ShutdownInternal()
+print(json.dumps(result))
+'''
+
+
+def probe():
+    return json.loads(remote('python3 -', stdin=PROBE))
+
+
+def check_file():
+    code = "import pathlib;print((pathlib.Path.home()/'.local/share/frame-control/headset/worn-check.json').read_text())"
+    return json.loads(remote('python3 -c ' + shlex.quote(code)))
+
+
+def color_count(text):
+    return len(set(re.findall(r'#[0-9A-Fa-f]{6,8}', text)))
+
+
+def main():
+    result = {'time':datetime.datetime.now(datetime.timezone.utc).isoformat(), 'proof':'worn-headset check'}
+    token = 'framey-' + secrets.token_hex(12)
+    locked = False
+    challenge = False
+    try:
+        # Do not read even standby status until this task owns the device lock.
+        remote('mkdir ' + LOCK + ' && { printf %s ' + shlex.quote(token) +
+               ' > ' + LOCK + '/owner || { rm -f ' + LOCK + '/owner; rmdir ' + LOCK + '; exit 1; }; }')
+        locked = True
+        before = probe()
+        result['before'] = before
+        if not before['battery'] or min(x['percent'] for x in before['battery']) < 20:
+            raise RuntimeError('Battery capacity unavailable or below 20%; no device session started')
+        if before['activity'] is None or before['activity'] >= 3:
+            raise RuntimeError('SteamVR is in standby; no worn-headset check started')
+        if not before['panelService'] or not before['plugins']:
+            raise RuntimeError('Install and open the Frame Control panel and a Framey plugin before this check')
+        after_lock = probe()
+        if after_lock['activity'] >= 3 or min(x['percent'] for x in after_lock['battery']) < 20:
+            raise RuntimeError('Activity or battery changed after acquiring the lock')
+        state = json.dumps({'nonce':token,'started':time.time()})
+        code = "import pathlib; p=pathlib.Path.home()/'.local/share/frame-control/headset/worn-check.json'; p.write_text(" + repr(state) + ")"
+        remote('python3 -c ' + shlex.quote(code))
+        challenge = True
+        print('In the worn headset: open SteamVR dashboard → Frame Control → a managed Decky plugin → Open panel. Touch a setting with the controller. Waiting up to 35 seconds.', flush=True)
+        deadline = time.monotonic() + 35
+        while time.monotonic() < deadline:
+            state = check_file()
+            if state.get('nonce') == token and state.get('panel') and state.get('input'):
+                break
+            time.sleep(1)
+        result['interaction'] = state
+        result['after'] = probe()
+        result['worn'] = isinstance(result['after']['activity'], int) and result['after']['activity'] < 3
+        result['overlay'] = json.loads(remote('python3 -', stdin=OVERLAY_PROBE, timeout=15))
+        result['panelVisible'] = result['overlay']['visible'] is True
+        installed_ids = {p['id'] for p in before['plugins']}
+        result['controllerInput'] = bool(state.get('input', {}).get('at', 0) > state.get('started', 0))
+        result['pluginPanelReady'] = bool(state.get('panel', {}).get('at', 0) > state.get('started', 0)
+                                          and state['panel'].get('pluginId') in installed_ids)
+        if result['panelVisible'] and result['pluginPanelReady']:
+            shot = json.loads(remote('python3 -', stdin=(ROOT/'ui/frame_vrshot.py').read_text(), timeout=20))['path']
+            local = Path('/tmp')/('framey-worn-' + token + '.png')
+            try:
+                with local.open('wb') as out:
+                    copy = subprocess.run([*SSH, 'cat ' + shlex.quote(shot)], stdout=out, stderr=subprocess.PIPE, timeout=20)
+                if copy.returncode: raise RuntimeError('Could not copy the SteamVR screenshot')
+                result['screenshotSha256'] = hashlib.sha256(local.read_bytes()).hexdigest()
+                pixels = subprocess.run(['convert', str(local), '-resize', '64x64!', 'txt:-'],
+                                        capture_output=True, text=True, timeout=15)
+                result['screenshotColors'] = color_count(pixels.stdout) if pixels.returncode == 0 else None
+            finally:
+                local.unlink(missing_ok=True)
+                remote('rm -f ' + shlex.quote(shot))
+        result['passed'] = (result['worn'] and result['panelVisible'] and result['controllerInput'] and
+                            result['pluginPanelReady'] and (result.get('screenshotColors') or 0) > 8)
+    except Exception as exc:
+        result['error'] = str(exc)
+    finally:
+        if challenge:
+            code = "import json,pathlib; p=pathlib.Path.home()/'.local/share/frame-control/headset/worn-check.json'; d=json.loads(p.read_text()); p.unlink() if d.get('nonce')==" + repr(token) + " else None"
+            try: remote('python3 -c ' + shlex.quote(code))
+            except Exception as exc: result['challengeCleanupError'] = str(exc)
+        if locked:
+            try:
+                remote('test "$(cat ' + LOCK + '/owner)" = ' + shlex.quote(token) +
+                       ' && rm ' + LOCK + '/owner && rmdir ' + LOCK)
+                result['lockReleased'] = True
+            except Exception as exc: result['lockCleanupError'] = str(exc)
+    print(json.dumps(result, indent=2))
+    return 0 if result.get('passed') else 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())
@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""Send the Frame's SteamVR mirror and output audio to a local OBS Media Source.
+
+OBS opens udp://127.0.0.1:15099 with input format mpegts. Nothing is bound to
+the network: this process sends MPEG-TS packets to the computer's loopback.
+"""
+import argparse
+import os
+import shlex
+import signal
+import socket
+import subprocess
+import sys
+import threading
+import time
+
+
+PACKET = 188
+DATAGRAM = PACKET * 7
+STARTUP_TIMEOUT = 20
+STREAM_STALL = 10
+CHILD_STOP_TIMEOUT = 5
+
+
+def remote_command(height=720, fps=30, audio=True):
+    if height not in (720, 1080) or fps not in (30, 60):
+        raise ValueError('height must be 720 or 1080; fps must be 30 or 60')
+    rate = 3 if height == 720 else 6
+    clock = '-thread_queue_size 1024 -use_wallclock_as_timestamps 1'
+    video = f'{clock} -f v4l2 -video_size 1920x1080 -i /dev/video99'
+    sound = f' {clock} -f pulse -i @DEFAULT_MONITOR@' if audio else ''
+    maps = '-map 0:v:0 -map 1:a:0' if audio else '-map 0:v:0'
+    encode = (f'-vf fps={fps},scale=-2:{height},format=yuv420p '
+              f'-c:v libx264 -preset ultrafast -tune zerolatency -g {fps * 2} -bf 0 '
+              f'-b:v {rate}M -maxrate {rate}M -bufsize {rate}M '
+              '-x264-params repeat-headers=1')
+    if audio:
+        encode += ' -af aresample=async=1 -c:a aac -b:a 160k'
+    return ("export XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR:-/run/user/$(id -u)}; "
+            "test -e /dev/video99 || { echo 'SteamVR mirror /dev/video99 is missing' >&2; exit 3; }; "
+            f'ffmpeg -hide_banner -loglevel warning -nostdin {video}{sound} '
+            f'{maps} {encode} -f mpegts -flush_packets 1 -')
+
+
+def relay(source, destination, on_packet=None):
+    """Preserve 188-byte MPEG-TS packet boundaries in loopback datagrams."""
+    pending = bytearray()
+    total = 0
+    while data := source.read(DATAGRAM):
+        pending.extend(data)
+        size = min(len(pending) // PACKET * PACKET, DATAGRAM)
+        if size:
+            destination.send(bytes(pending[:size]))
+            if on_packet:
+                on_packet()
+            del pending[:size]
+            total += size
+    if pending:
+        raise RuntimeError('Frame stream ended with an incomplete MPEG-TS packet')
+    return total
+
+
+def stop_child(proc):
+    """Bound cleanup even if a stalled SSH process does not handle termination."""
+    if proc.poll() is not None:
+        return
+    try:
+        proc.terminate()
+        proc.wait(timeout=CHILD_STOP_TIMEOUT)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait()
+    except ProcessLookupError:
+        pass  # another shutdown path already reaped it
+
+
+def watch_control(fd, proc, stopped):
+    """A desktop app closes its pipe to stop SSH, including on Windows.
+
+    Windows TerminateProcess does not run Python's finally block. The pipe also
+    closes if the app crashes, so the SSH connection is closed in either case.
+    Read the descriptor directly: a blocked daemon must not hold sys.stdin's
+    buffered-I/O lock when a timeout makes the main thread exit.
+    """
+    try:
+        os.read(fd, 1)
+    except OSError:
+        pass
+    stopped.set()
+    stop_child(proc)
+
+
+class StreamWatchdog:
+    """Close SSH if the first packet or a later packet takes too long."""
+
+    def __init__(self, proc, startup=None, stall=None):
+        self.proc = proc
+        self.startup = STARTUP_TIMEOUT if startup is None else startup
+        self.stall = STREAM_STALL if stall is None else stall
+        self.condition = threading.Condition()
+        self.last_packet = time.monotonic()
+        self.ready = False
+        self.closed = False
+        self.reason = ''
+        self.thread = threading.Thread(target=self._watch, daemon=True)
+        self.thread.start()
+
+    def packet(self):
+        with self.condition:
+            self.ready = True
+            self.last_packet = time.monotonic()
+            self.condition.notify()
+
+    def close(self):
+        with self.condition:
+            self.closed = True
+            self.condition.notify()
+        self.thread.join(timeout=1)
+
+    def _watch(self):
+        with self.condition:
+            while not self.closed:
+                left = self.last_packet + (self.stall if self.ready else self.startup) - time.monotonic()
+                if left <= 0:
+                    self.reason = (f'The Frame sent no OBS video for {self.startup:g} seconds' if not self.ready
+                                   else f'The Frame OBS video stopped for {self.stall:g} seconds')
+                    break
+                self.condition.wait(left)
+            else:
+                return
+        stop_child(self.proc)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--frame', default='frame', help='SSH host or alias (default: frame)')
+    parser.add_argument('--port', type=int, default=15099, help='local OBS UDP port (default: 15099)')
+    parser.add_argument('--height', type=int, choices=(720, 1080), default=720)
+    parser.add_argument('--fps', type=int, choices=(30, 60), default=30)
+    parser.add_argument('--no-audio', action='store_true', help='video only when the Frame audio monitor is unavailable')
+    parser.add_argument('--control-stdin', action='store_true', help=argparse.SUPPRESS)
+    args = parser.parse_args(argv)
+    if not 1024 <= args.port <= 65535:
+        parser.error('port must be between 1024 and 65535')
+    if not args.frame or args.frame.startswith('-') or any(c.isspace() for c in args.frame):
+        parser.error('frame must be one SSH host or alias')
+    command = remote_command(args.height, args.fps, not args.no_audio)
+    ssh = ['ssh', '-T', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10',
+           '-o', 'ServerAliveInterval=5', '-o', 'ServerAliveCountMax=2',
+           args.frame, 'bash', '-lc', shlex.quote(command)]
+    target = ('127.0.0.1', args.port)
+    print(f'Sending Frame view to udp://127.0.0.1:{args.port} for OBS; press Ctrl+C to stop.', file=sys.stderr)
+    signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
+    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as udp:
+        options = {'creationflags': subprocess.CREATE_NO_WINDOW} if sys.platform == 'win32' else {}
+        proc = subprocess.Popen(ssh, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, **options)
+        stopped = threading.Event()
+        watchdog = StreamWatchdog(proc)
+        if args.control_stdin:
+            threading.Thread(target=watch_control, args=(sys.stdin.fileno(), proc, stopped), daemon=True).start()
+        try:
+            amount = relay(proc.stdout, _Sender(udp, target), watchdog.packet)
+            code = proc.wait(timeout=10)
+            if stopped.is_set():
+                return 0
+            if watchdog.reason:
+                raise RuntimeError(watchdog.reason)
+            if code or not amount:
+                raise RuntimeError(f'Frame stream stopped (SSH exit {code}; {amount} bytes). '
+                                   'Check SteamVR and the audio monitor; try --no-audio if needed.')
+            return 0
+        except KeyboardInterrupt:
+            return 0
+        finally:
+            watchdog.close()
+            proc.stdout.close()
+            stop_child(proc)
+
+
+class _Sender:
+    def __init__(self, sock, target):
+        self.sock, self.target = sock, target
+        self.ready = False
+
+    def send(self, data):
+        try:
+            self.sock.sendto(data, self.target)
+        except ConnectionResetError:
+            # Winsock can report a previous ICMP "port unreachable" here while
+            # OBS is closed. Keep sending so opening the receiver can recover.
+            if sys.platform != 'win32':
+                raise
+            return
+        if not self.ready:
+            self.ready = True
+            print('Frame Control OBS stream is ready', file=sys.stderr, flush=True)
+
+
+if __name__ == '__main__':
+    try:
+        sys.exit(main())
+    except (OSError, RuntimeError) as error:
+        print(error, file=sys.stderr)
+        sys.exit(1)
@@ -70,6 +70,38 @@ print(next((a.get("digest") or "" for a in d["assets"] if a["name"]==n), "absent
 done
 [ -z "$missing" ] || { echo "not publishing: fix the assets above" >&2; exit 1; }

+# The workflow uploads this only after all eight platform builds complete.
+# Regenerate it from GitHub's installer digests and compare its own GitHub
+# digest, so a stale or partial checksum file cannot pass the release gate.
+python3 "$(dirname "$0")/release-checksums.py" < "$tmp/release.json" > "$tmp/SHA256SUMS"
+expected_sum=$(sha256sum "$tmp/SHA256SUMS" | cut -d ' ' -f 1)
+checksum_digest=$(python3 -c 'import json,sys
+d=json.load(open(sys.argv[1])); matches=[a.get("digest") for a in d["assets"] if a["name"]=="SHA256SUMS"]
+print(matches[0] if len(matches)==1 else "absent")' "$tmp/release.json")
+[ "$checksum_digest" = "sha256:$expected_sum" ] || {
+  echo "not publishing: SHA256SUMS is absent or does not match the eight installer digests" >&2; exit 1;
+}
+echo "ok       SHA256SUMS"
+
+# Every published release carries the same concrete verification instructions.
+# Keep the release's own notes, and append this section only once. The tag URL
+# is stable even while a draft temporarily has an untagged-* API name.
+python3 - "$tmp/release.json" "$(dirname "$0")/release-safety-note.md" "$tag" > "$tmp/release-with-note.json" <<'EOF'
+import json, pathlib, sys
+d = json.load(open(sys.argv[1]))
+body = (d.get("body") or "").rstrip()
+if "## Is it safe?" not in body:
+    note = pathlib.Path(sys.argv[2]).read_text(encoding="utf-8").replace("{tag}", sys.argv[3]).strip()
+    body = (body + "\n\n" if body else "") + note
+d["body"] = body
+json.dump(d, sys.stdout)
+EOF
+mv "$tmp/release-with-note.json" "$tmp/release.json"
+python3 - "$tmp/release.json" > "$tmp/release-body.txt" <<'EOF'
+import json, sys
+sys.stdout.buffer.write(json.load(open(sys.argv[1]))["body"].encode("utf-8"))
+EOF
+
 # update.json: what running copies read (app/updater.js), from github.com's
 # latest/download link rather than the rate-limited REST API.
 python3 - "$tmp/release.json" "$tag" "$page" "$expected" > "$tmp/update.json" <<'EOF'
@@ -87,6 +119,7 @@ print(" ".join(str(a["id"]) for a in d["assets"] if a["name"]=="update.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 include the Is it safe? section in the release body"
  echo "dry run: would PATCH release $id: tag_name=$tag draft=false prerelease=false make_latest=true"
  exit 0
 fi
@@ -98,6 +131,6 @@ gh api -X POST "https://uploads.github.com/repos/$repo/releases/$id/assets?name=
  -H "Content-Type: application/json" --input "$tmp/update.json" >/dev/null
 echo "ok       update.json"

-gh api -X PATCH "repos/$repo/releases/$id" -f tag_name="$tag" -F draft=false -F prerelease=false \
+gh api -X PATCH "repos/$repo/releases/$id" -f tag_name="$tag" -f body="$(cat "$tmp/release-body.txt")" -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"
@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Print SHA256SUMS for the eight release installers from GitHub asset metadata.
+
+GitHub computes each asset digest from its uploaded bytes. The workflow runs
+this only after all platform builds finish; publish-release.sh checks that the
+uploaded SHA256SUMS bytes still match these digests before publishing.
+"""
+import argparse
+import json
+import re
+import sys
+
+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 find_release(lines, tag):
+    releases = [json.loads(line) for line in lines if line.strip()]
+    hits = [r for r in releases if r.get("tag_name") == tag]
+    if not hits:
+        title = re.compile(r"Frame Control " + re.escape(tag.removeprefix("v")) + r"(: .*)?")
+        hits = [r for r in releases if r.get("draft")
+                and str(r.get("tag_name") or "").startswith("untagged-")
+                and title.fullmatch(r.get("name") or "")]
+    if len(hits) != 1:
+        raise ValueError(f"expected one release for {tag}; found {len(hits)}")
+    return hits[0]
+
+
+def checksums(release):
+    assets = release.get("assets") or []
+    lines = []
+    for name in INSTALLERS:
+        matches = [a for a in assets if a.get("name") == name]
+        if len(matches) != 1:
+            raise ValueError(f"expected one asset named {name}; found {len(matches)}")
+        digest = matches[0].get("digest") or ""
+        if not re.fullmatch(r"sha256:[0-9a-fA-F]{64}", digest):
+            raise ValueError(f"missing SHA-256 digest for {name}")
+        lines.append(f"{digest[7:].lower()}  {name}")
+    return "\n".join(lines) + "\n"
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--tag", help="find exact release in JSON-lines input")
+    parser.add_argument("--id", action="store_true", help="print the selected release id")
+    args = parser.parse_args()
+    data = sys.stdin.read()
+    release = find_release(data.splitlines(), args.tag) if args.tag else json.loads(data)
+    if args.id:
+        print(int(release["id"]))
+    else:
+        # Windows text stdout changes LF to CRLF. SHA256SUMS must have the same
+        # bytes on every runner, including publish-release.sh's verification.
+        sys.stdout.buffer.write(checksums(release).encode("ascii"))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except ValueError as exc:
+        sys.exit(str(exc))
@@ -0,0 +1,11 @@
+## Is it safe?
+
+Download only from this GitHub release. Check your installer against [SHA256SUMS](https://github.com/saphid/frame-control/releases/download/{tag}/SHA256SUMS). A matching hash proves that your file matches the file in this release. It does not prove that any program is free of malware.
+
+- Windows PowerShell: `Get-FileHash .\Frame-Control-Setup-x64.exe -Algorithm SHA256`
+- macOS Terminal: `shasum -a 256 Frame-Control-mac-arm64.dmg`
+- Linux terminal: `sha256sum Frame-Control-linux-x86_64.AppImage`
+
+Find the same filename in `SHA256SUMS` and compare all 64 hex characters. [Read the source](https://github.com/saphid/frame-control) and [see the build workflow](https://github.com/saphid/frame-control/blob/main/.github/workflows/release.yml). The Windows installer is **not code-signed**; SmartScreen may warn. The macOS app has only an **ad hoc signature**, not an Apple Developer ID signature; the DMG is **unsigned and not notarized**. Gatekeeper may warn or block it. Follow the opening steps in the README only if you trust this download.
+
+日本語: 公式リリースの SHA256SUMS とファイルの SHA-256 値を照合してください。Windows は未署名、macOS は開発者 ID による署名・公証がありません。
@@ -212,7 +212,7 @@
    <div class="head">
      <span class="kicker">Download</span>
      <h2>Get Frame Control</h2>
-      <p>Choose your computer’s OS and processor, not the headset’s. Python is bundled; Linux needs <code>ssh</code>, and arm64 Linux also needs your distribution’s <code>adb</code> for Android apps. <span hidden>Version <span data-version></span>.</span> <a href="https://github.com/saphid/frame-control/releases">Release notes</a></p>
+      <p>Choose your computer’s OS and processor, not the headset’s. Python is bundled; Linux needs <code>ssh</code>, and arm64 Linux also needs your distribution’s <code>adb</code> for Android apps. <span hidden>Version <span data-version></span>.</span> <a href="https://github.com/saphid/frame-control/releases">Release notes</a> · <a href="https://github.com/saphid/frame-control/blob/main/docs/current-support-matrix.md">What we tested</a></p>
    </div>
    <div class="downloads">
      <div class="dl" id="download-mac" data-os="mac">
@@ -257,6 +257,13 @@
      <h2>Good questions</h2>
    </div>
    <div class="faq">
+      <details id="verify-download">
+        <summary>Is it safe? How do I check my download?</summary>
+        <div><p>Starting with <b>v0.4.26</b>, download Frame Control and <a href="https://github.com/saphid/frame-control/releases/latest/download/SHA256SUMS">SHA256SUMS</a> from the same GitHub release. Earlier releases do not have this file. A matching SHA-256 means your file matches that release asset. It does not prove the app is free of malware. Compare all 64 characters with the line for your filename.</p>
+        <p>Windows PowerShell: <code>Get-FileHash .\Frame-Control-Setup-x64.exe -Algorithm SHA256</code><br>macOS Terminal: <code>shasum -a 256 Frame-Control-mac-arm64.dmg</code><br>Linux terminal: <code>sha256sum Frame-Control-linux-x86_64.AppImage</code></p>
+        <p>The <a href="https://github.com/saphid/frame-control">source</a> and <a href="https://github.com/saphid/frame-control/blob/main/.github/workflows/release.yml">build workflow</a> are public. The Windows installer is not code-signed, so SmartScreen may warn. The macOS app has only an ad hoc signature, not an Apple Developer ID signature; the DMG is unsigned and not notarized, so Gatekeeper may warn or block it. Only follow the opening steps below if you trust the download.</p>
+        <p lang="ja">日本語: v0.4.26 以降は公式リリースの SHA256SUMS とファイルの SHA-256 値を照合してください。Windows は未署名、macOS は開発者 ID による署名・公証がありません。</p></div>
+      </details>
      <details id="mac-opening">
        <summary>macOS says the app is damaged or can't be checked</summary>
        <div><p>The app isn't notarized, because there's no paid Apple developer account behind it. Only for a download you trust from the releases linked above: drag it to Applications, then clear the download quarantine once in Terminal:</p>