Bump Frame Control to 0.4.26 (#191)

Co-authored-by: SAPHID <saphid@users.noreply.github.com>

.github/workflows/release.yml

@@ -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

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+- 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.

README.md

@@ -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>
 
 ---
@@ -130,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.
+
+日本語: 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
@@ -186,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

app/login-item.js

@@ -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 };

app/main.js

@@ -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;
 
@@ -573,7 +576,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,
@@ -582,7 +638,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 }) => {
@@ -636,6 +695,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 ? [{
@@ -684,7 +745,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);
   });
@@ -692,11 +753,12 @@ 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());
   let obsQuitWaiting = false;
   let obsQuitReady = false;

app/package-lock.json

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

app/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frame-control",
   "productName": "Frame Control",
-  "version": "0.4.24",
+  "version": "0.4.26",
   "description": "Desktop app for managing a Valve Steam Frame over SSH",
   "private": true,
   "main": "main.js",
@@ -40,6 +40,7 @@
       "install-link.js",
       "updater.js",
       "preferences.js",
+      "login-item.js",
       "meta-signin.js",
       "package.json",
       "build/icon.png"

app/test/login-item.test.js

@@ -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, []);
+  });
+}

docs/current-support-matrix.md

@@ -0,0 +1,22 @@
+# What we have tested
+
+Current for Frame Control **v0.4.26**, 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 |
+|---|---|---|---|---|
+| 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 on a Linux host; H.264 video and a synthetic 440 Hz output tone reached a saved recording | No | Real game audio, audible monitoring, perceptual A/V sync and awake headset view | 25 Oct, PR #174 head, shipped in v0.4.22: [OBS log](evidence/obs-media-source-real-2026-10-25.md) |
+| OBS headset source on Windows | No physical Windows PC test | No OBS/Frame VM end-to-end test | App Start/Stop path has automated Windows checks only | 25 Oct, v0.4.23: [Windows PR #179](https://github.com/saphid/frame-control/pull/179), [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) |
+| 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) |
+| Passthrough in recordings | No active-passthrough mirror check | No | Standby frame was uniform; whether visible room pixels enter `/dev/video99` is **unknown**. Raw cameras are never captured by Frame Control | 25 Oct, v0.4.21: [headset log](evidence/round3-headset-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) |
+
+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.

docs/evidence/obs-followup-2026-10-25.md

@@ -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.

docs/obs-headset-source.md

@@ -27,6 +27,9 @@ 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. On
 Windows, install Python 3 and OpenSSH Client if Frame Control cannot find them.
 The Windows app Start/Stop path still needs a physical Windows/Frame test.
+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).
@@ -49,3 +52,23 @@ default output was present in the saved audio. The headset was in standby, so
 the video showed the standby mirror. Nobody listened to OBS's monitoring output,
 and audio/video sync and active passthrough remain 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 headset was still in standby.
+
+## 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.

docs/releasing.md

@@ -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

docs/support-matrix.html

@@ -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

docs/windows-wireless-doctor.md

@@ -48,6 +48,46 @@ 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)

scripts/obs-headset-source.py

@@ -11,10 +11,13 @@ import socket
 import subprocess
 import sys
 import threading
+import time
 
 
 PACKET = 188
 DATAGRAM = PACKET * 7
+STARTUP_TIMEOUT = 20
+STREAM_STALL = 10
 
 
 def remote_command(height=720, fps=30, audio=True):
@@ -37,7 +40,7 @@ def remote_command(height=720, fps=30, audio=True):
             f'{maps} {encode} -f mpegts -flush_packets 1 -')
 
 
-def relay(source, destination):
+def relay(source, destination, on_packet=None):
     """Preserve 188-byte MPEG-TS packet boundaries in loopback datagrams."""
     pending = bytearray()
     total = 0
@@ -46,6 +49,8 @@ def relay(source, destination):
         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:
@@ -53,7 +58,7 @@ def relay(source, destination):
     return total
 
 
-def watch_control(stream, proc):
+def watch_control(stream, 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
@@ -63,10 +68,53 @@ def watch_control(stream, proc):
         stream.read(1)
     except OSError:
         pass
+    stopped.set()
     if proc.poll() is None:
         proc.terminate()
 
 
+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
+        if self.proc.poll() is None:
+            self.proc.terminate()
+
+
 def main(argv=None):
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument('--frame', default='frame', help='SSH host or alias (default: frame)')
@@ -87,11 +135,17 @@ def main(argv=None):
     signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
     with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as udp:
         proc = subprocess.Popen(ssh, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE)
+        stopped = threading.Event()
+        watchdog = StreamWatchdog(proc)
         if args.control_stdin:
-            threading.Thread(target=watch_control, args=(sys.stdin.buffer, proc), daemon=True).start()
+            threading.Thread(target=watch_control, args=(sys.stdin.buffer, proc, stopped), daemon=True).start()
         try:
-            amount = relay(proc.stdout, _Sender(udp, target))
+            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.')
@@ -99,6 +153,7 @@ def main(argv=None):
         except KeyboardInterrupt:
             return 0
         finally:
+            watchdog.close()
             proc.stdout.close()
             if proc.poll() is None:
                 proc.terminate()

scripts/publish-release.sh

@@ -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"

scripts/release-checksums.py

@@ -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))

scripts/release-safety-note.md

@@ -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 による署名・公証がありません。

site/public/index.html

@@ -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>

tests/test_obs_headset_source.py

@@ -9,8 +9,10 @@ import socket
 import subprocess
 import sys
 import tempfile
+import threading
 import time
 import unittest
+from unittest import mock
 
 
 SCRIPT = Path(__file__).resolve().parents[1] / 'scripts' / 'obs-headset-source.py'
@@ -55,6 +57,29 @@ class ObsSourceTests(unittest.TestCase):
         self.assertIn('-f mpegts', with_audio)
         self.assertNotIn('@DEFAULT_MONITOR@', obs.remote_command(audio=False))
 
+    def test_watchdog_ends_a_stalled_child_on_every_host_platform(self):
+        class Child:
+            def __init__(self):
+                self.stopped = threading.Event()
+
+            def poll(self):
+                return 255 if self.stopped.is_set() else None
+
+            def terminate(self):
+                self.stopped.set()
+
+        for ready in (False, True):
+            with self.subTest(ready=ready):
+                child = Child()
+                watchdog = obs.StreamWatchdog(child, startup=0.1, stall=0.1)
+                if ready:
+                    watchdog.packet()
+                try:
+                    self.assertTrue(child.stopped.wait(1), 'a stalled SSH child was not terminated')
+                    self.assertIn('stopped' if ready else 'no OBS video', watchdog.reason)
+                finally:
+                    watchdog.close()
+
     @unittest.skipIf(sys.platform == 'win32', 'the packaged Start/Stop control is Linux/macOS only')
     def test_relay_stops_its_ssh_child_on_app_signal_or_control_pipe(self):
         for mode in ('signal', 'control-pipe'):
@@ -70,7 +95,7 @@ class ObsSourceTests(unittest.TestCase):
                             "import os, signal, sys, time\n"
                             "def stop(*_):\n"
                             "    open(os.environ['FAKE_SSH_STOPPED'], 'w').close()\n"
-                            "    sys.exit(0)\n"
+                            "    sys.exit(255)\n"
                             "signal.signal(signal.SIGTERM, stop)\n"
                             "sys.stdout.buffer.write(b'G' * 1316)\n"
                             "sys.stdout.buffer.flush()\n"
@@ -112,6 +137,33 @@ class ObsSourceTests(unittest.TestCase):
                 process.stdout.close()
                 process.stderr.close()
 
+    @unittest.skipIf(sys.platform == 'win32', 'the stand-in SSH script uses a POSIX shebang')
+    def test_startup_and_stream_stalls_end_ssh_with_a_clear_error(self):
+        for mode in ('startup', 'stream'):
+            with self.subTest(mode=mode), tempfile.TemporaryDirectory() as folder:
+                directory = Path(folder)
+                fake = directory / 'ssh'
+                fake.write_text("#!/usr/bin/env python3\n"
+                                "import os, signal, sys, time\n"
+                                "def stop(*_):\n"
+                                "    open(os.environ['FAKE_SSH_STOPPED'], 'w').close()\n"
+                                "    sys.exit(255)\n"
+                                "signal.signal(signal.SIGTERM, stop)\n"
+                                "if os.environ['FAKE_SSH_MODE'] == 'stream':\n"
+                                "    sys.stdout.buffer.write(b'G' * 1316)\n"
+                                "    sys.stdout.buffer.flush()\n"
+                                "while True: time.sleep(1)\n")
+                fake.chmod(0o755)
+                stopped = directory / 'stopped'
+                env = {'PATH': str(directory) + os.pathsep + os.environ.get('PATH', ''),
+                       'FAKE_SSH_STOPPED': str(stopped), 'FAKE_SSH_MODE': mode}
+                with mock.patch.dict(os.environ, env), \
+                     mock.patch.object(obs, 'STARTUP_TIMEOUT', 0.3), \
+                     mock.patch.object(obs, 'STREAM_STALL', 0.3):
+                    with self.assertRaisesRegex(RuntimeError, 'no OBS video' if mode == 'startup' else 'video stopped'):
+                        obs.main(['--frame', 'fake-frame'])
+                self.assertTrue(stopped.exists(), 'SSH survived the relay timeout')
+
 
 if __name__ == '__main__':
     unittest.main()

tests/test_publish_release.py

@@ -7,6 +7,7 @@ Run: python3 -m unittest discover -s tests
 """
 import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import json
+import hashlib
 import os
 import subprocess
 import tempfile
@@ -26,6 +27,9 @@ def draft(tag_name="untagged-c6ddfed7f75d67db2e99", name="Frame Control 9.8.7",
     if assets is None:
         assets = [{"id": 100 + i, "name": n, "size": 1000 + i, "digest": "sha256:" + "%064x" % i}
                   for i, n in enumerate(INSTALLERS)]
+        body = "".join(f"{i:064x}  {n}\n" for i, n in enumerate(INSTALLERS)).encode()
+        assets.append({"id": 200, "name": "SHA256SUMS", "size": len(body),
+                       "digest": "sha256:" + hashlib.sha256(body).hexdigest()})
     return {"id": rid, "tag_name": tag_name, "name": name, "draft": True, "prerelease": False,
             "body": "notes", "html_url": "https://github.com/saphid/frame-control/releases/tag/" + tag_name,
             "assets": assets}
@@ -79,6 +83,16 @@ class PublishRelease(unittest.TestCase):
         self.assertIsNone(upload)
         self.assertFalse(any(c[1:3] == ["-X", "PATCH"] for c in log))
 
+    def test_refuses_missing_or_stale_checksums(self):
+        for assets in (draft()["assets"][:-1],
+                       draft()["assets"][:-1] + [{"id": 200, "name": "SHA256SUMS",
+                                                  "digest": "sha256:" + "0" * 64}]):
+            p, log, upload = self.run_script([draft(assets=assets)], "v9.8.7")
+            self.assertNotEqual(p.returncode, 0)
+            self.assertIn("SHA256SUMS is absent or does not match", p.stderr)
+            self.assertIsNone(upload)
+            self.assertFalse(any("PATCH" in c for c in log))
+
     def test_refuses_ambiguous_or_absent_drafts_and_missing_tags(self):
         p, _, _ = self.run_script([draft(rid=1), draft(rid=2)], "v9.8.7")
         self.assertNotEqual(p.returncode, 0)

tests/test_release_checksums.py

@@ -0,0 +1,38 @@
+"""Checksum generator uses only complete, unambiguous GitHub asset metadata."""
+import sandbox  # noqa: F401
+import hashlib
+import importlib.util
+import unittest
+from pathlib import Path
+
+SCRIPT = Path(__file__).resolve().parent.parent / "scripts" / "release-checksums.py"
+spec = importlib.util.spec_from_file_location("release_checksums", SCRIPT)
+module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(module)
+
+
+class Checksums(unittest.TestCase):
+    def test_complete_list_matches_bytes(self):
+        assets = []
+        for i, name in enumerate(module.INSTALLERS):
+            assets.append({"name": name, "digest": "sha256:" + hashlib.sha256(str(i).encode()).hexdigest()})
+        actual = module.checksums({"assets": assets})
+        self.assertEqual(len(actual.splitlines()), 8)
+        self.assertEqual(actual.splitlines()[0], hashlib.sha256(b"0").hexdigest() + "  " + module.INSTALLERS[0])
+
+    def test_missing_duplicate_and_bad_digest_fail(self):
+        assets = [{"name": name, "digest": "sha256:" + "0" * 64} for name in module.INSTALLERS]
+        for changed in (assets[:-1], assets + [assets[0]],
+                        [dict(assets[0], digest="sha256:bad"), *assets[1:]]):
+            with self.assertRaises(ValueError):
+                module.checksums({"assets": changed})
+
+    def test_tag_or_exact_untagged_draft(self):
+        lines = ['{"id": 1, "tag_name": "untagged-a", "draft": true, "name": "Frame Control 9.8.7"}',
+                 '{"id": 2, "tag_name": "v9.8.8", "draft": false, "name": "Frame Control 9.8.8"}']
+        self.assertEqual(module.find_release(lines, "v9.8.7")["id"], 1)
+        self.assertEqual(module.find_release(lines, "v9.8.8")["id"], 2)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/wireless.cjs

@@ -37,6 +37,33 @@ test('click reads once, disables repeated clicks and renders partial inventory',
   assert.match(f.el('wirelessResult').innerHTML,/distinct Wi-Fi Direct/);
   assert.match(f.el('wirelessStatus').textContent,/Partial PC snapshot/);
 });
+test('two explicit reads compare exact identities and known state changes without claiming a repair',async()=>{
+  const f=fixture();
+  const first={...sample,sources:{pnp:'ok'},devices:[{...sample.devices[0],id:'SWD\\WIFIDIRECT\\one',
+    name:'Adapter <one>',present:true,problemCode:0}]};
+  const second={...first,observedAt:'2026-10-24T12:01:00Z',devices:[
+    {...first.devices[0],present:false,problemCode:22},
+    {...first.devices[0],id:'SWD\\WIFIDIRECT\\two',name:'Adapter <two>'}]};
+  let calls=0; f.context.api=async()=> ++calls===1 ? first : second;
+  await f.el('wirelessRead').onclick();
+  assert.match(f.el('wirelessComparison').innerHTML,/Read PC adapters again/);
+  assert.equal(f.el('wirelessForget').disabled,false);
+  await f.el('wirelessRead').onclick();
+  const change=f.el('wirelessComparison').innerHTML;
+  for(const phrase of ['Changes since previous read','Newly listed','presence Yes → No',
+    'problem code 0 → 22','not a safe disable target','&lt;one&gt;','&lt;two&gt;']) assert.ok(change.includes(phrase),phrase);
+  assert.doesNotMatch(change,/<one>|<two>/);
+  f.el('wirelessForget').onclick();
+  assert.equal(f.el('wirelessComparison').textContent,'');
+  assert.equal(f.el('wirelessForget').disabled,true);
+});
+test('incomplete PnP reads cannot imply a device appeared or vanished',()=>{
+  const f=fixture(); f.context.before={...sample,sources:{pnp:'unavailable'}};
+  f.context.after={...sample,sources:{pnp:'ok'},devices:[]};
+  const out=f.run('compareWireless(before,after)');
+  assert.match(out,/comparison unavailable/);
+  assert.doesNotMatch(out,/No longer listed|Newly listed/);
+});
 test('unsupported, busy and failed probes leave no stale inventory and allow retry',async()=>{
   for(const result of [{state:'unsupported',message:'Windows only'},{state:'busy',message:'Try again'},new Error('Denied')]) {
     const f=fixture();f.el('wirelessResult').textContent='stale inventory';

ui/index.html

@@ -1441,8 +1441,9 @@
 <section class="panel" id="wireless" hidden>
   <h2>Wireless Adapter doctor</h2>
   <p class="sub">Read-only snapshot of this Windows PC. Works without a headset connection. Nothing on the Frame is read or changed.</p>
-  <button class="action" id="wirelessRead">Read PC adapters</button>
+  <div class="row"><button class="action" id="wirelessRead">Read PC adapters</button><button id="wirelessForget" disabled>Forget previous read</button></div>
   <p id="wirelessStatus" role="status" aria-live="polite">Choose Read PC adapters to start. No automatic polling.</p>
+  <div id="wirelessComparison" aria-live="polite"></div>
   <div id="wirelessResult"></div>
   <div class="card" style="margin-top:16px"><h3>Before changing an adapter</h3>
     <p>Multiple Microsoft Wi-Fi Direct Virtual Adapter instances can be normal. A number such as #2, a disconnected link or a non-present device does not establish which instance is extra or safe to disable. This tool cannot reliably identify the Steam dongle's primary or active instance, so it offers no disable action.</p>
@@ -1452,6 +1453,14 @@
     <p>A Razer or other 2.4 GHz audio dongle can share spectrum with Wi-Fi. This inventory cannot measure interference, detect the audio dongle's channel or prove what caused a dropout or PC shutdown.</p>
     <p>Try wired headphones briefly and compare. Space USB radio dongles apart with an extension lead; if your PC uses 2.4 GHz Wi-Fi, compare Ethernet or an existing 5/6 GHz network. Change one thing at a time and keep notes. No network or security settings are changed here.</p>
   </div>
+  <div class="card" style="margin-top:16px"><h3>If streaming drops as it starts</h3>
+    <p>Read PC adapters before starting, then refresh immediately after a drop. Compare exact PnP instance IDs, presence and problem codes; a new numbered name alone does not identify a fault. Note whether the PC's own Wi-Fi also drops.</p>
+    <p>Retry once with wired PC networking or wired audio if available, then with the radio dongles spaced apart. Change one condition at a time. The PC Wi-Fi channel shown above is not the Steam dongle channel, and this check cannot prove RF interference.</p>
+  </div>
+  <div class="card" style="margin-top:16px"><h3>If the adapter will not reconnect</h3>
+    <p>Stop the failed stream, close Steam's streaming session, and check that the adapter still appears in the refreshed PC snapshot. If it is absent, reconnect the USB dongle once at the PC and read again; this will interrupt any connection using it.</p>
+    <p>If the same exact PnP instance shows problem code 22 (disabled), use Windows Device Manager to review that instance and its enable action. Do not enable or disable a different numbered instance by guesswork. If it stays missing or reports another problem code, keep the before/after IDs and error for Steam Support. Frame Control does not change the driver, radio or network settings.</p>
+  </div>
 </section>
 
 <section class="panel" id="powerReport">
@@ -5662,7 +5671,34 @@ document.querySelectorAll('[data-power-format]').forEach(b => b.onclick = async
 
 // ---- Read-only PC wireless doctor ----
 let wirelessSeq = 0;
+let wirelessPrevious = null;  // memory only; never sent or saved
 const wirelessKnown = value => value === true ? 'Yes' : value === false ? 'No' : 'Unknown';
+function compareWireless(previous, current) {
+  if (previous.sources?.pnp !== 'ok' || current.sources?.pnp !== 'ok')
+    return '<p class="hint">Exact device comparison unavailable: the PnP inventory was incomplete in one read. The current snapshot is shown below.</p>';
+  const keyed = snapshot => new Map((snapshot.devices || [])
+    .filter(d => typeof d.id === 'string' && d.id)
+    .map(d => [d.id.toLowerCase(), d]));
+  const before = keyed(previous), after = keyed(current), changes = [];
+  const describe = d => `${esc(d.name || 'Unnamed device')} (<code>${esc(d.id)}</code>)`;
+  for (const [id, device] of after) {
+    const old = before.get(id);
+    if (!old) { changes.push(`Newly listed: ${describe(device)}`); continue; }
+    for (const [field, label] of [['present','presence'], ['pnpStatus','PnP status'],
+      ['problemCode','problem code'], ['operational','operation'], ['media','media'],
+      ['defaultRoute','default route'], ['channel','reported channel'], ['band','reported band']]) {
+      if (old[field] == null || device[field] == null || old[field] === device[field]) continue;
+      const value = v => typeof v === 'boolean' ? wirelessKnown(v) : esc(v);
+      changes.push(`${describe(device)}: ${label} ${value(old[field])} → ${value(device[field])}`);
+    }
+  }
+  for (const [id, device] of before) if (!after.has(id)) changes.push(`No longer listed: ${describe(device)}`);
+  const shown = changes.slice(0, 25);
+  return `<div class="card"><h3>Changes since previous read</h3>
+    <p class="sub">${esc(previous.observedAt || 'Earlier read')} → ${esc(current.observedAt || 'Current read')}. These are reported changes, not proof of a new fault or an unused adapter. A newly listed numbered Wi-Fi Direct instance is not a safe disable target.</p>
+    ${shown.length ? `<ul>${shown.map(line => `<li>${line}</li>`).join('')}</ul>` : '<p>No reported device changes in the available fields.</p>'}
+    ${changes.length > shown.length ? `<p>${changes.length - shown.length} more changes omitted; inspect the current snapshot below.</p>` : ''}</div>`;
+}
 function renderWireless(r) {
   const unknown = value => value == null ? 'Unknown' : esc(value);
   const states = (value, known) => known[value] || (value == null ? 'Unknown' : `Other (${esc(value)})`);
@@ -5681,6 +5717,8 @@ function renderWireless(r) {
 $('wirelessRead').onclick = async () => {
   const seq = ++wirelessSeq;
   $('wirelessRead').disabled = true;
+  $('wirelessForget').disabled = true;
+  $('wirelessComparison').textContent = '';
   $('wirelessResult').textContent = '';
   $('wirelessStatus').textContent = 'Reading this PC’s adapters…';
   try {
@@ -5690,14 +5728,26 @@ $('wirelessRead').onclick = async () => {
       $('wirelessStatus').textContent = r.message || 'PC wireless inventory unavailable.';
       return;
     }
+    $('wirelessComparison').innerHTML = wirelessPrevious ? compareWireless(wirelessPrevious, r) :
+      '<p class="hint">Read PC adapters again after a dropout to compare exact device reports. The previous read stays only in this open app.</p>';
+    wirelessPrevious = r;
     $('wirelessResult').innerHTML = renderWireless(r);
     $('wirelessStatus').textContent = r.state === 'partial' ? 'Partial PC snapshot. Some sources are unavailable. No settings changed.' : 'PC snapshot received. Unknown channel/band fields may remain. No settings changed.';
   } catch (e) {
     if (seq === wirelessSeq) $('wirelessStatus').textContent = `PC wireless inventory unavailable: ${e.message}`;
   } finally {
-    if (seq === wirelessSeq) $('wirelessRead').disabled = false;
+    if (seq === wirelessSeq) {
+      $('wirelessRead').disabled = false;
+      $('wirelessForget').disabled = !wirelessPrevious;
+    }
   }
 };
+$('wirelessForget').onclick = () => {
+  wirelessPrevious = null;
+  $('wirelessForget').disabled = true;
+  $('wirelessComparison').textContent = '';
+  $('wirelessStatus').textContent = 'Previous adapter read forgotten. Read again to start a new comparison.';
+};
 
 // ---- Read-only game storage ----
 let storageSeq = 0;