From ca2a991f03bc8bba2f0d44b0eee6786e9ed0a6ad Mon Sep 17 00:00:00 2001
From: saphid <4596216+saphid@users.noreply.github.com>
Date: Sun, 27 Sep 2026 17:06:40 +1000
Subject: [PATCH 1/7] Sideloaded titles: use ids Steam's create-shortcut
 accepts

On the Frame, Steam refused to register titles whose id had a hyphen
(fc-smoke-exe) with "missing/invalid arguments", and registered the same
program as FCSmokeProbe (headset smoke test, 2026-09-27, BUILD_ID
20260922.6101926). Valve's client only allows ^[A-Za-z_][A-Za-z0-9_.]+$.

title_id now makes ids of letters, digits and _, not starting with a
digit, 2 to 64 long; new installs are checked against that, while titles
already on the Frame are still listed, launched and removed. Steam's error
text is trimmed before it's quoted, and the "install it again with Steam
running" hint only follows a Steam-not-running error.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docs/sideloading.md        | 14 ++++++++++----
 tests/test_frame_titles.py | 18 +++++++++++++++---
 ui/frame_titles.py         | 27 ++++++++++++++++++---------
 ui/index.html              |  8 +++++---
 4 files changed, 48 insertions(+), 19 deletions(-)

diff --git a/docs/sideloading.md b/docs/sideloading.md
index 6ff60e4..53a0ad8 100644
--- a/docs/sideloading.md
+++ b/docs/sideloading.md
@@ -21,7 +21,8 @@ desktop app, which knows where a dropped folder lives; in a plain browser, zip
 it.) A dialog shows:
 
 - **Name**: what Steam shows. Steam uses the title id as the name, so it's
-  limited to letters, digits, `_` and `-`; the dialog shows the result.
+  limited to letters, digits and `_`, and can't start with a digit; the
+  dialog shows the result.
 - **Launches**: the program picked to start the game, with the other
   candidates in the list.
 - **Runtime**: picked from the program, see below. Windows programs can switch
@@ -133,10 +134,15 @@ splits that string is **not checked**.
   with the same rule, because `scp -r` would follow a link out of the folder
   and upload whatever it points at.
 - Installs run one at a time, and Remove is refused while one runs.
-- The title id is limited to `[A-Za-z0-9_-]`, at most 64 characters. Valve's
-  scripts pass it to a shell (`steamos-delete` runs `rm -r` on it). Valve's
+- The title id is limited to letters, digits and `_`, doesn't start with a
+  digit (one that would gets `_` in front), and is 2 to 64 characters. That's
+  what Steam's `create-shortcut` accepts: on the Frame it refused
+  `fc-smoke-exe` with `missing/invalid arguments` and registered the same
+  program as `FCSmokeProbe` (2026-09-27, BUILD_ID 20260922.6101926), and
+  Valve's client only allows `^[A-Za-z_][A-Za-z0-9_.]+$`. Valve's scripts
+  also pass the id to a shell (`steamos-delete` runs `rm -r` on it). Valve's
   reserved sideload names (`steam`, `steamvr`, and their `deckard` forms,
-  which would replace the Steam client itself) get `-game` added.
+  which would replace the Steam client itself) get `_game` added.
 - Nothing needs `sudo`; everything goes to your home folder on the Frame.
 - In the app, a dropped folder is read from its local path by the app's own
   server, which only accepts requests from its own page (see
diff --git a/tests/test_frame_titles.py b/tests/test_frame_titles.py
index a46b508..55d080d 100644
--- a/tests/test_frame_titles.py
+++ b/tests/test_frame_titles.py
@@ -347,14 +347,26 @@ class Zips(unittest.TestCase):
 class Names(unittest.TestCase):
     def test_title_id(self):
         self.assertEqual(frame_titles.title_id('Hollow Knight: Silksong!'), 'Hollow_Knight_Silksong')
-        self.assertEqual(frame_titles.title_id('steam'), 'steam-game')     # Valve's reserved sideload names
+        self.assertEqual(frame_titles.title_id('steam'), 'steam_game')     # Valve's reserved sideload names
         self.assertEqual(frame_titles.title_id('Devkit Steam'), 'Devkit_Steam')
-        self.assertEqual(frame_titles.title_id('devkit-steam'), 'devkit-steam-game')  # the trampoline file
-        self.assertEqual(frame_titles.title_id('--rm -rf /'), 'rm_-rf')
+        self.assertEqual(frame_titles.title_id('--rm -rf /'), 'rm_rf')
         self.assertEqual(len(frame_titles.title_id('x' * 200)), 64)
         with self.assertRaises(FrameError):
             frame_titles.title_id('!!!')
 
+    def test_title_id_is_one_steam_accepts(self):
+        # The Frame's Steam refused "fc-smoke-exe" ("missing/invalid arguments") and took
+        # "FCSmokeProbe" (2026-09-27): Valve's client allows ^[A-Za-z_][A-Za-z0-9_.]+$ only.
+        self.assertEqual(frame_titles.title_id('Half-Life 2'), 'Half_Life_2')
+        self.assertEqual(frame_titles.title_id('fc-smoke-exe'), 'fc_smoke_exe')
+        self.assertEqual(frame_titles.title_id('2048'), '_2048')
+        self.assertEqual(frame_titles.title_id('X'), 'X_game')
+        self.assertEqual(frame_titles.title_id('devkit-steam'), 'devkit_steam')
+        for name in ('Half-Life 2', '2048', 'X', 'steam', 'a' * 90, 'Ünïcödé game', '9' * 70):
+            gid = frame_titles.title_id(name)
+            self.assertRegex(gid, r'^[A-Za-z_][A-Za-z0-9_.]+$', name)
+            self.assertTrue(frame_titles.NEW_ID_RE.match(gid) and frame_titles.ID_RE.match(gid), gid)
+
     def test_display_name(self):
         self.assertEqual(frame_titles.display_name('MyGame-linux-arm64.zip'), 'MyGame')
         self.assertEqual(frame_titles.display_name('Portal 2.zip'), 'Portal 2')
diff --git a/ui/frame_titles.py b/ui/frame_titles.py
index bff6b56..bc208a0 100644
--- a/ui/frame_titles.py
+++ b/ui/frame_titles.py
@@ -35,7 +35,13 @@ PY = 'python3 ~/' + UTILS + '/'
 # devkit-steam is the trampoline file that switches SteamOS to a sideloaded client
 # (select_steam.sh); a folder there breaks Valve's devkit tools.
 RESERVED_IDS = ('steam', 'steamdeckard', 'steamvr', 'steamvrdeckard', 'devkit-steam')
-ID_RE = re.compile(r'^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$')
+# Any title folder on the Frame we'll list, launch or remove: safe in a shell and a path.
+ID_RE = re.compile(r'^[A-Za-z0-9_][A-Za-z0-9_-]{0,63}$')
+# What a new install may use. Steam's create-shortcut refused "fc-smoke-exe" with
+# "missing/invalid arguments" and took the same program as "FCSmokeProbe" (headset
+# smoke test, 2026-09-27, build 20260922.6101926); Valve's client only allows
+# GAMEID_ALLOWED_PATTERN, ^[A-Za-z_][A-Za-z0-9_.]+$ (devkit_client/gui2). No dots here.
+NEW_ID_RE = re.compile(r'^[A-Za-z_][A-Za-z0-9_]{1,63}$')
 DIR_RE = re.compile(r'^/[A-Za-z0-9_./-]+$')
 
 # Zip limits: well above any real game, well below a zip bomb.
@@ -124,13 +130,15 @@ def _pe(f, head):
 
 
 def title_id(name):
-    """The Devkit Game id Steam shows as the title's name: [A-Za-z0-9_-], at most 64."""
-    s = re.sub(r'[^A-Za-z0-9_-]+', '_', str(name or '').strip())
-    s = re.sub(r'_+', '_', s).strip('_-')[:64].strip('_-')
+    """The Devkit Game id Steam shows as the title's name, in the form Steam accepts
+    (NEW_ID_RE): letters, digits and _, not starting with a digit, 2 to 64 long."""
+    s = re.sub(r'[^A-Za-z0-9]+', '_', str(name or '').strip()).strip('_')[:64].strip('_')
     if not s:
         raise FrameError('the title needs a name with some letters or digits')
-    if s.lower() in RESERVED_IDS:
-        s += '-game'
+    if s[0].isdigit():
+        s = '_' + s[:63]
+    if len(s) < 2 or s.lower() in RESERVED_IDS:
+        s += '_game'
     return s
 
 
@@ -653,7 +661,7 @@ def install_plan(plan, name=None, exe=None, runtime=None, progress=None):
 
 def _install(plan, step):
     gid = plan['id']
-    if not ID_RE.match(gid) or gid.lower() in RESERVED_IDS:
+    if not NEW_ID_RE.match(gid) or gid.lower() in RESERVED_IDS:
         raise FrameError(f'bad title id {gid!r}')
     step("Syncing Valve's devkit tools to the Frame", 0.02)
     ensure_utils()
@@ -683,8 +691,9 @@ def _install(plan, step):
         ssh(f'cat > {GAMES}/{gid}-framecontrol.json', input=json.dumps(meta, indent=1), timeout=30)
         registered = True                    # the files stay: Steam registers them once it's running
         if 'error' in reply:
-            raise FrameError(f"Uploaded, but Steam didn't register it: {reply['error']}. "
-                             "With Steam running on the Frame, install it again.")
+            err = str(reply['error']).strip().rstrip('.')
+            hint = ' With Steam running on the Frame, install it again.' if 'not running' in err else ''
+            raise FrameError(f"Uploaded, but Steam didn't register it: {err}.{hint}")
         step('Done', 1.0)
         meta.update(runtime_label=RUNTIMES[plan['runtime']]['label'], steam=str(reply.get('success', '')).strip())
         return meta
diff --git a/ui/index.html b/ui/index.html
index e980e69..66e4d0b 100644
--- a/ui/index.html
+++ b/ui/index.html
@@ -1433,9 +1433,11 @@ async function sendFiles(files, dirs = new Set()) {
 // ---- sideloaded titles (a Linux or Windows build as a Steam Devkit Game) ----
 const RESERVED_IDS = ["steam", "steamdeckard", "steamvr", "steamvrdeckard", "devkit-steam"];
 function titleId(name) {  // mirrors frame_titles.title_id: the name Steam shows
-  const trim = x => x.replace(/^[_-]+|[_-]+$/g, "");
-  let s = trim(trim(String(name).trim().replace(/[^A-Za-z0-9_-]+/g, "_").replace(/_+/g, "_")).slice(0, 64));
-  if (RESERVED_IDS.includes(s.toLowerCase())) s += "-game";
+  const trim = x => x.replace(/^_+|_+$/g, "");
+  let s = trim(trim(String(name).trim().replace(/[^A-Za-z0-9]+/g, "_")).slice(0, 64));
+  if (!s) return s;
+  if (/^[0-9]/.test(s)) s = "_" + s.slice(0, 63);
+  if (s.length < 2 || RESERVED_IDS.includes(s.toLowerCase())) s += "_game";
   return s;
 }
 const ARCH = { arm64: "ARM64", x86_64: "x86-64", x86: "32-bit x86" };

From 0181071b8313b6826841930d1dad30a702ce763f Mon Sep 17 00:00:00 2001
From: saphid <4596216+saphid@users.noreply.github.com>
Date: Sun, 27 Sep 2026 17:06:40 +1000
Subject: [PATCH 2/7] Tests against a fake Frame, and a headset smoke test

tests/fakeframe: a container that stands in for the Frame (Arch Linux, or
Arch Linux ARM on arm64) with sshd, rsync, Valve's steamos-devkit-service
and hooks (vendored unmodified), a fake Steam client for the devkit pipe and
the DevTools port (the app's JavaScript runs in Node against stand-in
SteamClient/appStore objects), stubs for steam, wpctl, flatpak, podman,
Lepton and friends, battery and thermal files under /sys, and fault
switches (fakeframe-ctl): pairing mode, approve/deny/timeout, Steam not
running, headset asleep, sshd off, disk full, runtimes missing. A second
container is the computer running Frame Control.

tests/e2e: 29 tests driving the real ui/server.py, frame_connect.py and
frame_titles.py against it; skipped unless FRAME_E2E=1. scripts/e2e.sh
builds, runs and tears down; CI runs it on ubuntu-24.04-arm.

tests/smoke + scripts/frame-smoke.sh: the core cases against a real Frame,
recorded with its BUILD_ID, cleaning up after itself; --pair to pair a
throwaway key. docs/testing.md describes the layers.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .github/workflows/checks.yml                  |  12 +
 .gitignore                                    |   1 +
 README.md                                     |   2 +
 docs/testing.md                               | 142 +++++
 scripts/e2e.sh                                |  64 +++
 scripts/frame-smoke.sh                        |   8 +
 tests/e2e/harness.py                          | 198 +++++++
 tests/e2e/test_android.py                     |  76 +++
 tests/e2e/test_device.py                      |  86 +++
 tests/e2e/test_faults.py                      |  94 ++++
 tests/e2e/test_pairing.py                     | 111 ++++
 tests/e2e/test_titles.py                      | 191 +++++++
 tests/fakeframe/Containerfile                 |  40 ++
 tests/fakeframe/compose.yaml                  |  54 ++
 tests/fakeframe/host.Containerfile            |  14 +
 tests/fakeframe/host/entrypoint.sh            |  25 +
 tests/fakeframe/rootfs/etc/ssh/sshd_config    |  21 +
 .../steamos-enable-sshd                       |  14 +
 tests/fakeframe/rootfs/usr/lib/os-release     |   9 +
 .../rootfs/usr/local/bin/fakeframe-ctl        |  31 ++
 tests/fakeframe/rootfs/usr/local/bin/flatpak  |  38 ++
 .../rootfs/usr/local/bin/gamescopectl         |  26 +
 tests/fakeframe/rootfs/usr/local/bin/nmcli    |  11 +
 tests/fakeframe/rootfs/usr/local/bin/podman   |  47 ++
 tests/fakeframe/rootfs/usr/local/bin/qdbus6   |  19 +
 tests/fakeframe/rootfs/usr/local/bin/steam    |  26 +
 tests/fakeframe/rootfs/usr/local/bin/wpctl    |  21 +
 .../usr/local/lib/fakeframe/cef_shim.js       | 157 ++++++
 .../local/lib/fakeframe/fakeframe_state.py    | 183 ++++++
 .../usr/local/lib/fakeframe/fakesteam.py      | 490 ++++++++++++++++
 .../rootfs/usr/local/lib/fakeframe/init.py    | 468 ++++++++++++++++
 .../rootfs/usr/local/lib/fakeframe/lepton.py  |  83 +++
 .../lib/fakeframe/pystubs/dbus/__init__.py    |  50 ++
 .../lib/fakeframe/pystubs/dbus/exceptions.py  |   3 +
 .../fakeframe/steamos-devkit-service/LICENSE  | 504 +++++++++++++++++
 .../steamos-devkit-service/README.md          |  21 +
 .../hooks/approve-ssh-key                     |  71 +++
 .../hooks/devkit-1-identify                   | 151 +++++
 .../hooks/devkit_utils/__init__.py            | 265 +++++++++
 .../hooks/install-ssh-key                     |  74 +++
 .../src/steamos-devkit-service.py             | 522 ++++++++++++++++++
 tests/smoke/frame_smoke.py                    | 235 ++++++++
 tests/smoke/tiny_programs.py                  |  89 +++
 43 files changed, 4747 insertions(+)
 create mode 100644 docs/testing.md
 create mode 100755 scripts/e2e.sh
 create mode 100755 scripts/frame-smoke.sh
 create mode 100644 tests/e2e/harness.py
 create mode 100644 tests/e2e/test_android.py
 create mode 100644 tests/e2e/test_device.py
 create mode 100644 tests/e2e/test_faults.py
 create mode 100644 tests/e2e/test_pairing.py
 create mode 100644 tests/e2e/test_titles.py
 create mode 100644 tests/fakeframe/Containerfile
 create mode 100644 tests/fakeframe/compose.yaml
 create mode 100644 tests/fakeframe/host.Containerfile
 create mode 100755 tests/fakeframe/host/entrypoint.sh
 create mode 100644 tests/fakeframe/rootfs/etc/ssh/sshd_config
 create mode 100755 tests/fakeframe/rootfs/usr/bin/steamos-polkit-helpers/steamos-enable-sshd
 create mode 100644 tests/fakeframe/rootfs/usr/lib/os-release
 create mode 100755 tests/fakeframe/rootfs/usr/local/bin/fakeframe-ctl
 create mode 100755 tests/fakeframe/rootfs/usr/local/bin/flatpak
 create mode 100755 tests/fakeframe/rootfs/usr/local/bin/gamescopectl
 create mode 100755 tests/fakeframe/rootfs/usr/local/bin/nmcli
 create mode 100755 tests/fakeframe/rootfs/usr/local/bin/podman
 create mode 100755 tests/fakeframe/rootfs/usr/local/bin/qdbus6
 create mode 100755 tests/fakeframe/rootfs/usr/local/bin/steam
 create mode 100755 tests/fakeframe/rootfs/usr/local/bin/wpctl
 create mode 100644 tests/fakeframe/rootfs/usr/local/lib/fakeframe/cef_shim.js
 create mode 100755 tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakeframe_state.py
 create mode 100755 tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakesteam.py
 create mode 100755 tests/fakeframe/rootfs/usr/local/lib/fakeframe/init.py
 create mode 100755 tests/fakeframe/rootfs/usr/local/lib/fakeframe/lepton.py
 create mode 100644 tests/fakeframe/rootfs/usr/local/lib/fakeframe/pystubs/dbus/__init__.py
 create mode 100644 tests/fakeframe/rootfs/usr/local/lib/fakeframe/pystubs/dbus/exceptions.py
 create mode 100644 tests/fakeframe/steamos-devkit-service/LICENSE
 create mode 100644 tests/fakeframe/steamos-devkit-service/README.md
 create mode 100755 tests/fakeframe/steamos-devkit-service/hooks/approve-ssh-key
 create mode 100755 tests/fakeframe/steamos-devkit-service/hooks/devkit-1-identify
 create mode 100644 tests/fakeframe/steamos-devkit-service/hooks/devkit_utils/__init__.py
 create mode 100755 tests/fakeframe/steamos-devkit-service/hooks/install-ssh-key
 create mode 100755 tests/fakeframe/steamos-devkit-service/src/steamos-devkit-service.py
 create mode 100644 tests/smoke/frame_smoke.py
 create mode 100644 tests/smoke/tiny_programs.py

diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
index 51eea2d..314bf4f 100644
--- a/.github/workflows/checks.yml
+++ b/.github/workflows/checks.yml
@@ -71,3 +71,15 @@ jobs:
           cd ios
           udid=$(xcrun simctl list devices available -j | python3 -c 'import json,sys; d=json.load(sys.stdin)["devices"]; print(next(x["udid"] for r in d for x in d[r] if x["name"].startswith("iPhone")))')
           xcodebuild -project FrameControl.xcodeproj -scheme FrameControl -destination "platform=iOS Simulator,id=$udid" CODE_SIGNING_ALLOWED=NO test
+
+  # End-to-end tests against the fake Frame (tests/fakeframe): Arch Linux ARM
+  # in Docker, on a native arm64 runner like the headset. See docs/testing.md.
+  e2e:
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install zsh
+        run: sudo apt-get update -qq && sudo apt-get install -y -qq zsh
+      - name: End-to-end tests
+        run: scripts/e2e.sh
diff --git a/.gitignore b/.gitignore
index ad5b005..d89ecc2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,4 @@ apk-catalog/data/cache/
 apk-catalog/data/index-v2.json*
 compat-db/.env.lakebed.server
 compat-db/.lakebed/
+tests/smoke/results/
diff --git a/README.md b/README.md
index 93cabeb..5f25235 100644
--- a/README.md
+++ b/README.md
@@ -195,6 +195,7 @@ Frame's software fits together, all checked against a real headset and labelled
 | [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 |
+| [Testing](docs/testing.md) | Unit tests, end-to-end tests against a fake Frame in Docker, and the headset smoke test |
 | [Open questions](docs/open-questions.md) | What's still unchecked |
 
 <details>
@@ -221,6 +222,7 @@ Frame's software fits together, all checked against a real headset and labelled
 
 ```sh
 python3 -m unittest discover -s tests   # server tests; no headset needed
+scripts/e2e.sh                          # end-to-end against a fake Frame (Linux with Docker)
 cd app && npm install && npm start      # run the app from the checkout
 ```
 
diff --git a/docs/testing.md b/docs/testing.md
new file mode 100644
index 0000000..e70a4a7
--- /dev/null
+++ b/docs/testing.md
@@ -0,0 +1,142 @@
+# Testing
+
+Frame Control is tested in three layers, from fast and fake to slow and real.
+A fourth, a SteamOS VM, may come later ([issue #6](https://github.com/saphid/steam-frame/issues/6)).
+
+| Layer | Runs | Needs | Covers |
+|---|---|---|---|
+| Unit tests (`tests/*.py`) | `python3 -m unittest discover -s tests` | Nothing | Parsing, validation, request guards; SSH and HTTP are mocked |
+| Fake Frame (`tests/e2e`) | `scripts/e2e.sh` | Linux with Docker | The real server and scripts against a container that behaves like a Frame |
+| Headset smoke test | `scripts/frame-smoke.sh` | A Frame on the `frame` alias | Install, launch and remove on the real device, recorded with its BUILD_ID |
+
+## Unit tests
+
+```sh
+python3 -m unittest discover -s tests
+```
+
+About 120 tests, a few seconds, on Python 3.9 and newer. GitHub Actions runs
+them on macOS, Windows and Linux. They don't pick up `tests/e2e`.
+
+## The fake Frame
+
+`tests/fakeframe/` builds a container that stands in for the headset, and a
+second one for the computer Frame Control runs on. `scripts/e2e.sh` builds
+both, starts them with `docker compose`, runs `tests/e2e` in the host
+container and takes everything down, exiting with the tests' status:
+
+```sh
+scripts/e2e.sh                                   # everything, about 2 minutes plus the first build
+scripts/e2e.sh test_titles                       # one module
+scripts/e2e.sh test_faults.Faults.test_disk_full # one test
+FAKEFRAME_KEEP=1 scripts/e2e.sh                  # leave it running afterwards
+```
+
+It needs a Linux host with Docker and `docker compose`, and zsh. The images
+are `fakeframe-frame` and `fakeframe-host`; the compose project, network and
+volumes are `fakeframe-e2e*`. CI runs it on a native arm64 runner
+(`ubuntu-24.04-arm`, the `e2e` job in `.github/workflows/checks.yml`).
+
+The host container exists because OpenSSH reads `~/.ssh/config` from the
+passwd home directory, not `$HOME`. There, `ssh frame` reaches the fake Frame
+through the same `Host frame` block `ui/frame_connect.py` writes, the
+repository is mounted read-only at `/repo`, and each test module starts the
+real `ui/server.py` (Python 3.9) and talks to it over HTTP with the headers
+its guards want.
+
+### What's real and what's fake
+
+| On the fake Frame | |
+|---|---|
+| Arch Linux (`archlinux:base`, or `menci/archlinuxarm:base` on arm64), user `steamos`, `/etc/os-release` with BUILD_ID 20260922.6101926 | Real OS, Frame's identity |
+| `sshd` with key and password logins, `rsync`, `python3` | Real |
+| Valve's steamos-devkit-service on port 32000 and its hooks, vendored unmodified in `tests/fakeframe/steamos-devkit-service` | Real; only its `dbus` import (for mDNS through systemd-resolved) is a stand-in that logs the registration |
+| Valve's devkit-utils, copied over by Frame Control itself | Real |
+| **fakesteam**: `~/.steam/steam.pid`, `steam.token` and the `steam.pipe` FIFO; answers `approve-ssh-key`, `create-shortcut`, `run-game`, `list-shortcuts` and `delete-shortcut` with the response files devkit-utils waits for; takes `steam://rungameid`, `install` and `store` URLs | Fake |
+| DevTools on `127.0.0.1:8080` with a `SharedJSContext` target. The JavaScript Frame Control sends runs for real in Node against stand-in `SteamClient`, `appStore` and `downloadsStore` objects (`cef_shim.js`), so async functions, optional chaining and `Map`s behave as in Steam's CEF | The JS engine is real; the objects are fake |
+| `steam`, `wpctl`, `flatpak`, `podman`, `nmcli`, `qdbus6`, `gamescopectl`, SteamOS's `steamos-enable-sshd` helper, and Lepton's launcher | Stubs that record their calls |
+| Battery, charger and thermal zones under `/sys/class` | Files the supervisor writes. `/sys` is read-only in a container and Docker's AppArmor profile refuses writes under it, so each folder is a volume mounted twice: over `/sys/class/...` for `frame_status.py` to read, and under `/var/lib/fakeframe/sys` for the supervisor to write |
+| `vrserver` and `plasmashell` | Renamed `sleep` processes, so the status page and the clipboard find them |
+
+Every fake behaviour copied from the device has a comment citing the doc or
+observation and the BUILD_ID it came from; anything not seen on a headset is
+marked as a guess. The fake keeps its state in `/var/lib/fakeframe/state.json`
+(shortcuts, devkit titles, compat tool mapping, launches, pairing requests,
+Lepton instances, volume, Flatpaks, clipboard) and logs stub calls to
+`calls.jsonl` beside it.
+
+Native programs really run: a launched aarch64 title executes on an arm64
+host, and an x86-64 one on x86-64 (the container shares the host's kernel).
+Proton titles are recorded with the command Steam would run, not run.
+
+### Fault switches
+
+`fakeframe-ctl` works over SSH (`ssh frame fakeframe-ctl help`) and from the
+host container (`FAKEFRAME_CTL=http://fakeframe:9999`), so a test can flip a
+switch while SSH is down:
+
+| Command | Effect |
+|---|---|
+| `pairing on\|off` | Steam's **Pair new host** screen open or not; off gives the device's 403 text |
+| `answer approve\|deny\|timeout` | How the pairing prompt is answered |
+| `steam on\|off` | Steam client running (pid file, pipe, DevTools) |
+| `sleep on\|off` | Headset asleep: ports 22 and 32000 accept and never answer, so SSH times out |
+| `sshd on\|off` | sshd stopped: new connections are refused, open ones stay |
+| `devkit-service on\|off` | Port 32000 closed |
+| `disk-full on\|off` | Fills the small (64 MB) filesystem on `~/devkit-game` |
+| `runtime NAME installed\|missing` | Proton, the Steam Linux Runtimes, Lepton |
+| `battery KEY=VALUE...` | e.g. `capacity=15 status=Discharging current_now=-900000` |
+| `keys harness\|none`, `authorized-keys` | Set or read `~/.ssh/authorized_keys` |
+| `reset`, `state`, `calls [TOOL]` | Start over; read the state and call log |
+
+### What the fake can't show
+
+- Rendering: the headset view, desktop capture content, live video, SteamVR,
+  gamescope and panels. The capture stub returns a placeholder PNG.
+- Proton and FEX: whether a Windows or x86-64 program actually runs.
+- Android: there's no Android in the Lepton stand-in, so no ADB, display
+  settings, probes or app crashes.
+- The real Steam client's UI and anything it does that isn't modelled, and
+  mDNS discovery.
+- `sudo` and the power buttons, Tailscale, and the Windows and macOS sides of
+  the app (the host container is Linux, so the `rsync` paths are tested and the
+  `scp` fallback isn't).
+
+## Headset smoke test
+
+```sh
+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
+```
+
+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 five seconds, and
+an x86-64 `.exe` that exits at once), keeping what Steam logged about each.
+Everything it installs is removed again, also after a failure. Results go to
+`tests/smoke/results/<time>-<BUILD_ID>.json` (not committed) with a summary on
+screen; it exits 0 when every step passed, 1 if one failed, 2 if the headset
+isn't reachable.
+
+`--pair` asks the devkit service to pair a new RSA key, which needs someone
+in the headset to open **Settings → Developer → Pair new host** and approve
+it; the key is checked and then taken out of `authorized_keys` again.
+
+## When the device disagrees with the fake
+
+The fake is only as good as what's been seen on a headset. When the smoke
+test (or anyone) finds the Frame doing something else:
+
+1. Record what the device did, with the date and BUILD_ID, in the doc that
+   covers it (`docs/sideloading.md`, `docs/ssh.md` and so on).
+2. Change the fake to match, with a comment citing that observation. The
+   behaviours are in `tests/fakeframe/rootfs/usr/local/lib/fakeframe/`
+   (`fakesteam.py` for Steam, `cef_shim.js` for DevTools, `init.py` for the
+   switches, the stubs in `rootfs/usr/local/bin`).
+3. Run `scripts/e2e.sh`. If the app is wrong, the tests now fail the way the
+   device did; fix the app and add a unit test.
+
+For example, on 2026-09-27 the smoke test found that Steam's `create-shortcut`
+refuses ids with a hyphen (`missing/invalid arguments`), which the fake had
+accepted. The fake now refuses them the same way, and Frame Control makes ids
+Steam accepts.
diff --git a/scripts/e2e.sh b/scripts/e2e.sh
new file mode 100755
index 0000000..2c0b1ed
--- /dev/null
+++ b/scripts/e2e.sh
@@ -0,0 +1,64 @@
+#!/usr/bin/env zsh
+# Linux host with Docker: run the end-to-end tests against the fake Frame.
+# Builds the fake Frame and host images (tests/fakeframe), starts them with
+# docker compose, runs tests/e2e in the host container, prints the results
+# and takes everything down again. Exits with the tests' status (2 if the
+# harness itself didn't come up). See docs/testing.md.
+#
+# Usage: scripts/e2e.sh [TEST...]     e.g. scripts/e2e.sh test_titles test_faults.Faults.test_disk_full
+# Env:   FAKEFRAME_BASE   base image (default: archlinux:base, or menci/archlinuxarm:base on arm64)
+#        FAKEFRAME_KEEP=1 leave the containers running afterwards
+set -uo pipefail
+
+root=${0:A:h:h}
+cd "$root" || exit 2
+case $(uname -m) in
+  x86_64|amd64) base=archlinux:base ;;
+  aarch64|arm64) base=menci/archlinuxarm:base ;;
+  *) print -u2 "No Arch Linux base image known for $(uname -m); set FAKEFRAME_BASE"; exit 2 ;;
+esac
+base=${FAKEFRAME_BASE:-$base}
+compose=(docker compose -p fakeframe-e2e -f tests/fakeframe/compose.yaml)
+started=$SECONDS
+
+print "==> Building fakeframe-frame (from $base) and fakeframe-host"
+docker build -q --build-arg BASE="$base" -t fakeframe-frame -f tests/fakeframe/Containerfile tests/fakeframe || exit 2
+docker build -q -t fakeframe-host -f tests/fakeframe/host.Containerfile tests/fakeframe || exit 2
+
+logs() {
+  print "\n==> Fake Frame logs"
+  $compose logs --no-color --tail 80 fakeframe
+  $compose exec -T fakeframe sh -c 'for f in /var/log/fakeframe/*.log; do echo "--- $f"; tail -n 40 "$f"; done' 2>/dev/null
+  print "\n==> ui/server.py log"
+  $compose exec -T host sh -c 'tail -n 80 /tmp/fakeframe-e2e-server.log' 2>/dev/null
+}
+
+finish() {
+  if [[ ${FAKEFRAME_KEEP:-0} == 1 ]]; then
+    print "==> Left running: ${(j: :)compose} exec host bash"
+  else
+    $compose down -v --remove-orphans >/dev/null 2>&1
+  fi
+}
+trap finish EXIT
+
+$compose down -v --remove-orphans >/dev/null 2>&1
+print "==> Starting the fake Frame and the host"
+if ! $compose up -d --wait; then
+  logs
+  exit 2
+fi
+print "==> Up after $(( SECONDS - started )) s; running tests/e2e"
+
+if (( $# )); then
+  args=(-v "$@")
+else
+  args=(discover -v -s .)
+fi
+tests_started=$SECONDS
+$compose exec -T -w /repo/tests/e2e host python3 -m unittest "${args[@]}"
+rc=$?
+(( rc == 0 )) || logs
+print "\n==> tests/e2e: $([[ $rc == 0 ]] && echo passed || echo "FAILED (exit $rc)") in $(( SECONDS - tests_started )) s" \
+      "($(( SECONDS - started )) s with builds)"
+exit $rc
diff --git a/scripts/frame-smoke.sh b/scripts/frame-smoke.sh
new file mode 100755
index 0000000..8d8872a
--- /dev/null
+++ b/scripts/frame-smoke.sh
@@ -0,0 +1,8 @@
+#!/usr/bin/env zsh
+# 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" "$@"
diff --git a/tests/e2e/harness.py b/tests/e2e/harness.py
new file mode 100644
index 0000000..9a0818d
--- /dev/null
+++ b/tests/e2e/harness.py
@@ -0,0 +1,198 @@
+"""Plumbing for the end-to-end tests against the fake Frame (tests/fakeframe).
+
+scripts/e2e.sh runs these inside the compose `host` container, where
+`ssh frame` reaches the fake Frame and FAKEFRAME_CTL is its control port.
+Each test starts from `fakeframe-ctl reset` and drives the real ui/server.py
+(started once, on a free port) over HTTP, then checks the fake's state.
+Without FRAME_E2E=1 every test here is skipped.
+"""
+import atexit
+import http.client
+import json
+import os
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+import urllib.request
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path[:0] = [str(ROOT / 'ui'), str(ROOT / 'tests'), str(ROOT / 'tests' / 'smoke')]
+
+ENABLED = os.environ.get('FRAME_E2E') == '1'
+CTL = os.environ.get('FAKEFRAME_CTL', 'http://fakeframe:9999').rstrip('/')
+FAKE_HOST = os.environ.get('FAKEFRAME_HOST', 'fakeframe')
+HOME = '/home/steamos'
+SERVER_LOG = os.path.join(tempfile.gettempdir(), 'fakeframe-e2e-server.log')
+
+
+def require():
+    """Call at module level: skips the module unless the fake Frame is up."""
+    if not ENABLED:
+        raise unittest.SkipTest('needs the fake Frame: run scripts/e2e.sh (sets FRAME_E2E=1)')
+
+
+# ---- the fake Frame's control port --------------------------------------------
+
+def _ctl_request(path, body=None, timeout=60):
+    data = json.dumps(body).encode() if body is not None else None
+    req = urllib.request.Request(CTL + path, data=data, headers={'Content-Type': 'application/json'})
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return json.load(r)
+
+
+def ctl(*args):
+    out = _ctl_request('/ctl', {'args': list(args)})
+    if 'error' in out:
+        raise AssertionError(f'fakeframe-ctl {" ".join(args)}: {out["error"]}')
+    return out
+
+
+def state():
+    return _ctl_request('/state')
+
+
+def calls(tool=None):
+    return _ctl_request('/calls' + (f'?{tool}' if tool else ''))
+
+
+def wait_for(check, timeout=30, what='a condition', every=0.3):
+    """Poll check() until it returns something truthy; returns that."""
+    deadline = time.monotonic() + timeout
+    last = None
+    while time.monotonic() < deadline:
+        last = check()
+        if last:
+            return last
+        time.sleep(every)
+    raise AssertionError(f'timed out after {timeout}s waiting for {what} (last: {last!r})')
+
+
+def reset():
+    ctl('reset')
+    wait_for(lambda: _ctl_request('/ping')['ok'], 30, 'the fake Frame to come back after reset')
+
+
+def ssh(cmd, check=True, timeout=30):
+    """Run cmd on the fake Frame through the `frame` alias, as Frame Control does."""
+    r = subprocess.run(['ssh', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=5', 'frame', cmd],
+                       capture_output=True, text=True, stdin=subprocess.DEVNULL, timeout=timeout)
+    if check and r.returncode != 0:
+        raise AssertionError(f'ssh frame {cmd!r} exited {r.returncode}: {r.stderr.strip()}')
+    return r.stdout
+
+
+def exists(path):
+    return ssh(f'test -e {path} && echo yes || echo no').strip() == 'yes'
+
+
+# ---- the real server ----------------------------------------------------------
+
+class Server:
+    proc = None
+    port = None
+
+    @classmethod
+    def start(cls):
+        if cls.proc and cls.proc.poll() is None:
+            return
+        with socket.socket() as s:
+            s.bind(('127.0.0.1', 0))
+            cls.port = s.getsockname()[1]
+        env = dict(os.environ, FRAME_CONTROL_LOCAL_LINKS='1')
+        log = open(SERVER_LOG, 'ab')
+        cls.proc = subprocess.Popen([sys.executable, str(ROOT / 'ui' / 'server.py'), '--port', str(cls.port)],
+                                    cwd=str(ROOT), env=env, stdin=subprocess.DEVNULL, stdout=log, stderr=log)
+        log.close()
+        atexit.register(cls.stop)
+        wait_for(lambda: cls._up(), 20, 'ui/server.py to listen')
+
+    @classmethod
+    def _up(cls):
+        try:
+            return api('GET', '/api/host')[0] == 200
+        except OSError:
+            return False
+
+    @classmethod
+    def stop(cls):
+        if cls.proc and cls.proc.poll() is None:
+            cls.proc.terminate()
+            try:
+                cls.proc.wait(10)
+            except subprocess.TimeoutExpired:
+                cls.proc.kill()
+
+
+def api(method, path, body=None, raw=None, headers=None, timeout=120):
+    """One request to the server with the headers its guards want. -> (status, JSON or bytes, headers)."""
+    conn = http.client.HTTPConnection('127.0.0.1', Server.port, timeout=timeout)
+    try:
+        hdrs = {'X-Frame-UI': '1', **(headers or {})}   # Host is 127.0.0.1:<port>, which it accepts
+        data = raw if raw is not None else (json.dumps(body).encode() if body is not None else None)
+        if data is not None and 'Content-Type' not in hdrs:
+            hdrs['Content-Type'] = 'application/json'
+        conn.request(method, path, body=data, headers=hdrs)
+        r = conn.getresponse()
+        payload = r.read()
+        if r.getheader('Content-Type', '').startswith('application/json'):
+            payload = json.loads(payload)
+        return r.status, payload, dict(r.getheaders())
+    finally:
+        conn.close()
+
+
+def ok(method, path, body=None, **kw):
+    status, out, _ = api(method, path, body, **kw)
+    if status != 200:
+        raise AssertionError(f'{method} {path} -> {status}: {out}')
+    return out
+
+
+def upload(path, mode, name=None):
+    with open(path, 'rb') as f:
+        data = f.read()
+    return api('POST', '/api/upload', raw=data, headers={
+        'X-Filename': name or os.path.basename(path), 'X-Mode': mode, 'Content-Type': 'application/octet-stream'})
+
+
+def wait_title_job(token, timeout=180):
+    def done():
+        job = ok('GET', f'/api/titles/job?token={token}')
+        return job if job['done'] else None
+    return wait_for(done, timeout, f'title install job {token}', every=0.5)
+
+
+def install_title(path, **options):
+    """Upload (or, for a folder, inspect by path) and install; returns (plan, finished job)."""
+    if os.path.isdir(path):
+        staged = ok('POST', '/api/titles', {'action': 'inspect', 'path': path})
+    else:
+        status, staged, _ = upload(path, 'title')
+        if status != 200:
+            raise AssertionError(f'upload -> {status}: {staged}')
+    started = ok('POST', '/api/titles', {'action': 'install', 'token': staged['token'], **options})
+    return staged['plan'], wait_title_job(started['job'])
+
+
+def launches(kind=None):
+    return [r for r in state()['launches'] if kind is None or r['kind'] == kind]
+
+
+class FrameTestCase(unittest.TestCase):
+    """Starts the server once and the fake Frame afresh for every test."""
+
+    @classmethod
+    def setUpClass(cls):
+        Server.start()
+
+    def setUp(self):
+        reset()
+        self.tmp = tempfile.mkdtemp(prefix='fakeframe-e2e-')
+        self.addCleanup(subprocess.run, ['rm', '-rf', self.tmp])
+
+    def path(self, *parts):
+        return os.path.join(self.tmp, *parts)
diff --git a/tests/e2e/test_android.py b/tests/e2e/test_android.py
new file mode 100644
index 0000000..b2b5373
--- /dev/null
+++ b/tests/e2e/test_android.py
@@ -0,0 +1,76 @@
+"""An APK as its own Lepton instance (ui/frame_android.py): the shortcut goes in
+through the fake Steam client's DevTools port, the launch through `steam`,
+Lepton's launcher and podman."""
+import unittest
+
+import harness
+from harness import HOME, exists, ok, state, upload, wait_for
+from test_frame_apk import apk, manifest, resources
+
+harness.require()
+
+PKG = 'com.example.fakeframe'
+APP_DIR = f'{HOME}/Applications/Android/{PKG}'
+
+
+class AndroidApps(harness.FrameTestCase):
+    def build_apk(self, min_sdk=26):
+        arsc = resources({(1, '', 0): {0: 1, 1: 2}, (2, '', 640): {0: 4}})
+        data = apk({'AndroidManifest.xml': manifest(PKG, 0x7f010000, 0x7f010001, min_sdk),
+                    'resources.arsc': arsc, 'res/icon_hi.png': b'\x89PNG fake icon',
+                    'lib/arm64-v8a/libgame.so': b''})
+        path = self.path('fake-app.apk')
+        with open(path, 'wb') as f:
+            f.write(data)
+        return path
+
+    def test_install_launch_stop_remove(self):
+        status, out, _ = upload(self.build_apk(), 'apk')
+        self.assertEqual(status, 200, out)
+        meta = out['app']
+        self.assertEqual((meta['package'], meta['label'], meta['version']), (PKG, 'App label', '2.1'))
+        shortcut = next(s for s in state()['steam']['shortcuts'] if s['appid'] == meta['shortcut'])
+        self.assertEqual(shortcut['name'], 'App label')
+        self.assertEqual(shortcut['exe'], f'{APP_DIR}/launch.sh')
+        self.assertEqual(shortcut['start_dir'], APP_DIR)
+        self.assertEqual(shortcut['icon'], f'{APP_DIR}/icon.png')
+        for f in ('app.apk', 'launch.sh', 'instance.id', 'meta.json', 'icon.png', 'lepton-show-flatscreen'):
+            self.assertTrue(exists(f'{APP_DIR}/{f}'), f)
+        self.assertEqual(meta['game_id'], (meta['shortcut'] << 32) | 0x02000000)
+
+        ok('POST', '/api/android', {'action': 'launch', 'package': PKG})
+        ctr = f"lepton-steamlaunch-{meta['instance']}"
+        running = wait_for(lambda: state()['lepton'].get(ctr), 20, 'the Lepton instance')
+        self.assertTrue(running['flatscreen'])
+        self.assertGreaterEqual(running['port'], 5556)
+        call = next(c for c in harness.calls('lepton') if 'env' in c)
+        self.assertEqual(call['env']['SteamAppId'], str(meta['instance']))
+        self.assertTrue(call['env']['STEAM_COMPAT_DATA_PATH'].startswith(f'{HOME}/.local/share/Steam/'))
+        apps = ok('GET', '/api/android')['apps']
+        self.assertEqual([(a['package'], a['running']) for a in apps], [(PKG, True)])
+
+        ok('POST', '/api/android', {'action': 'stop', 'package': PKG})
+        wait_for(lambda: ctr not in state()['lepton'], 15, 'the instance to stop')
+        ok('POST', '/api/android', {'action': 'remove', 'package': PKG})
+        self.assertEqual(state()['steam']['shortcuts'], [])
+        self.assertFalse(exists(APP_DIR))
+        self.assertFalse(exists(f"{HOME}/.local/share/Steam/steamapps/compatdata/{meta['instance']}"))
+
+    def test_reinstall_reuses_the_shortcut(self):
+        first = upload(self.build_apk(), 'apk')[1]['app']
+        second = upload(self.build_apk(), 'apk')[1]['app']
+        self.assertEqual(first['shortcut'], second['shortcut'])
+        self.assertEqual(len(state()['steam']['shortcuts']), 1)
+
+    def test_launch_without_lepton_installed_fails_on_the_frame(self):
+        meta = upload(self.build_apk(), 'apk')[1]['app']
+        harness.ctl('runtime', 'lepton', 'missing')
+        ok('POST', '/api/android', {'action': 'launch', 'package': PKG})
+        run = wait_for(lambda: next((r for r in state()['launches'] if r.get('appid') == meta['shortcut']
+                                     and r.get('exit') is not None), None), 20, 'launch.sh to exit')
+        self.assertEqual(run['exit'], 1)   # launch.sh: "Lepton isn't installed (Steam app 3056000)"
+        self.assertEqual(state()['lepton'], {})
+
+
+if __name__ == '__main__':
+    unittest.main()
diff --git a/tests/e2e/test_device.py b/tests/e2e/test_device.py
new file mode 100644
index 0000000..5888ce0
--- /dev/null
+++ b/tests/e2e/test_device.py
@@ -0,0 +1,86 @@
+"""Status, Steam library, volume, clipboard, Flatpaks and the desktop capture,
+through the server against the fake Frame."""
+import unittest
+
+import harness
+from harness import api, ctl, launches, ok, state, wait_for
+
+harness.require()
+
+
+class Device(harness.FrameTestCase):
+    def test_status(self):
+        s = ok('GET', '/api/status')
+        self.assertEqual(s['hostname'], 'frame')
+        self.assertEqual(s['os'], {'version': '0.3.0', 'build': '20260922.6101926', 'variant': 'vr'})
+        b = s['battery']
+        self.assertEqual((b['percent'], b['status'], b['health']), (76, 'Charging', 'Good'))
+        self.assertAlmostEqual(b['watts'], 9.62, places=1)
+        self.assertAlmostEqual(b['tempC'], 31.2, places=3)
+        self.assertEqual(s['power'], {'type': 'C PD [PD_PPS]', 'watts': 20.0})
+        self.assertEqual(s['temp'], 41.5)
+        self.assertEqual(s['wifi'], {'ssid': 'Fake:Frame Wi-Fi', 'signal': 72})
+        self.assertEqual(s['volume'], {'level': 0.4, 'muted': False})
+        self.assertEqual(s['services'], {'steamvr': True, 'desktop': True, 'lepton': False, 'rdp': False})
+        # Runtimes and Lepton are Steam "apps" too; the status hides them.
+        self.assertEqual([g['name'] for g in s['games']], ['Beat Saber'])
+        self.assertIsNotNone(s['disk']['home'])
+
+        ctl('battery', 'capacity=15', 'status=Discharging', 'current_now=-900000')
+        b = ok('GET', '/api/status')['battery']
+        self.assertEqual((b['percent'], b['status']), (15, 'Discharging'))
+        self.assertLess(b['watts'], 0)
+
+    def test_volume_and_mute(self):
+        ok('POST', '/api/volume', {'level': 0.55, 'muted': True})
+        self.assertEqual(state()['volume'], {'level': 0.55, 'muted': True})
+        self.assertEqual(ok('GET', '/api/status')['volume'], {'level': 0.55, 'muted': True})
+        status, out, _ = api('POST', '/api/volume', {'level': 2})
+        self.assertEqual(status, 400, out)
+
+    def test_clipboard_goes_to_klipper(self):
+        text = 'héllo from the e2e tests\nline two, with a trailing newline\n'
+        out = ok('POST', '/api/clipboard', {'text': text})
+        # ${#text} counts bytes or characters depending on the session's locale.
+        self.assertRegex(out['message'], r'^copied via Klipper \(\d+ chars\)$')
+        self.assertEqual(state()['clipboard'], [text])
+
+    def test_flatpak_install_and_remove(self):
+        ok('POST', '/api/flatpak', {'id': 'org.videolan.VLC', 'action': 'install'})
+        self.assertEqual([f['id'] for f in ok('GET', '/api/status')['flatpaks']], ['org.videolan.VLC'])
+        ok('POST', '/api/flatpak', {'id': 'org.videolan.VLC', 'action': 'uninstall'})
+        self.assertEqual(state()['flatpaks'], [])
+        status, out, _ = api('POST', '/api/flatpak', {'id': 'org.example.missing', 'action': 'install'})
+        self.assertEqual(status, 502)
+        self.assertIn('Nothing matches org.example.missing', out['error'])
+
+    def test_desktop_capture(self):
+        status, png, headers = api('GET', '/api/screenshot')
+        self.assertEqual(status, 200, png)
+        self.assertTrue(png.startswith(b'\x89PNG\r\n\x1a\n'))
+        self.assertEqual(headers.get('X-Capture-Source'), 'gamescope')
+
+    def test_steam_library_and_installs(self):
+        owned = ok('GET', '/api/steam/owned')
+        self.assertEqual(owned['country'], 'AU')
+        games = {g['id']: g for g in owned['games']}
+        self.assertEqual(set(games), {2379780, 274190, 620980})
+        self.assertEqual((games[2379780]['frame'], games[620980]['installed']), (3, True))
+        # Balatro queues at once; Broforce stops at the options dialog, which
+        # frame_steam.py accepts with ContinueInstall().
+        for appid, name in ((2379780, 'Balatro'), (274190, 'Broforce')):
+            out = ok('POST', '/api/steam', {'appid': appid, 'action': 'install'})
+            self.assertEqual(out, {'state': 'downloading', 'message': f'{name} is queued to download on the Frame'})
+        self.assertEqual(ok('GET', '/api/steam/owned')['download']['appid'], 274190)
+
+    def test_launch_and_store_page(self):
+        ok('POST', '/api/launch', {'appid': 620980})
+        run = wait_for(lambda: launches('rungameid'), 10, 'the launch to reach Steam')[-1]
+        self.assertEqual((run['appid'], run['started']), (620980, True))
+        ok('POST', '/api/steam', {'appid': 1145360, 'action': 'store'})
+        wait_for(lambda: state()['steam']['pages'], 10, 'the store page')
+        self.assertEqual(state()['steam']['pages'][0]['title'], 'Hades on Steam')
+
+
+if __name__ == '__main__':
+    unittest.main()
diff --git a/tests/e2e/test_faults.py b/tests/e2e/test_faults.py
new file mode 100644
index 0000000..b42d4e2
--- /dev/null
+++ b/tests/e2e/test_faults.py
@@ -0,0 +1,94 @@
+"""What Frame Control does when the headset misbehaves: Steam not running,
+the headset asleep or with sshd off, and a full disk."""
+import os
+import subprocess
+import sys
+import time
+import unittest
+import zipfile
+
+import harness
+import tiny_programs
+from harness import HOME, ROOT, api, ctl, exists, install_title, ok, state, wait_for
+
+harness.require()
+
+
+class Faults(harness.FrameTestCase):
+    def exe(self):
+        return tiny_programs.write(self.tmp, 'exe')
+
+    def test_steam_not_running_then_install_again(self):
+        ctl('steam', 'off')
+        _, job = install_title(self.exe())
+        # steam-client-create-shortcut's own words, passed on by frame_titles.
+        self.assertEqual(job['error'], "Uploaded, but Steam didn't register it: The Steam client is not running. "
+                                       "Registration did not complete. With Steam running on the Frame, "
+                                       "install it again.")
+        self.assertTrue(exists(f'{HOME}/devkit-game/fc_smoke_exe/fc-smoke-exe.exe'))   # the files stay
+        self.assertEqual(state()['devkit_games'], {})
+        status, out, _ = api('GET', '/api/steam/owned')
+        self.assertEqual(status, 502)
+        self.assertIn("Steam's UI isn't answering", out['error'])
+
+        ctl('steam', 'on')
+        wait_for(lambda: harness._ctl_request('/ping')['ok'], 20, 'Steam to start')
+        _, job = install_title(self.exe())
+        self.assertIsNone(job['error'], job)
+        self.assertIn('fc_smoke_exe', state()['devkit_games'])
+
+    def test_launch_with_steam_stopped(self):
+        _, job = install_title(self.exe())
+        self.assertIsNone(job['error'], job)
+        ctl('steam', 'off')
+        status, out, _ = api('POST', '/api/titles', {'action': 'launch', 'id': 'fc_smoke_exe'})
+        self.assertEqual(status, 502, out)
+        self.assertIn('steam.pid', out['error'])
+        self.assertEqual(harness.launches(), [])
+
+    def test_headset_asleep(self):
+        ok('GET', '/api/status')                        # a shared connection is up
+        ctl('sleep', 'on')
+        t0 = time.monotonic()
+        status, out, _ = api('GET', '/api/status', timeout=90)
+        took = time.monotonic() - t0
+        self.assertEqual(status, 502, out)
+        self.assertRegex(out['error'], r'[Tt]imed out')
+        self.assertLess(took, 40)                       # ConnectTimeout, not a hang
+        ctl('sleep', 'off')
+        # The next request after waking gets through again.
+        wait_for(lambda: api('GET', '/api/status', timeout=60)[0] == 200, 60, 'status after waking')
+
+    def test_sshd_stopped(self):
+        ok('GET', '/api/titles')                        # the server's shared connection is up
+        ctl('sshd', 'off')
+        # Stopping sshd keeps open sessions (Arch's sshd.service kills only the
+        # listener), so the server carries on over its shared connection...
+        self.assertEqual(api('GET', '/api/titles')[0], 200)
+        # ...while anything that connects afresh is refused.
+        out = subprocess.run([sys.executable, str(ROOT / 'ui' / 'frame_titles.py'), 'list'],
+                             capture_output=True, text=True, timeout=60)
+        self.assertEqual(out.returncode, 1)
+        self.assertIn('Connection refused', out.stderr)
+        ctl('sshd', 'on')
+        wait_for(lambda: subprocess.run([sys.executable, str(ROOT / 'ui' / 'frame_titles.py'), 'list'],
+                                        capture_output=True, timeout=60).returncode == 0, 30, 'sshd to be back')
+
+    def test_disk_full(self):
+        path = self.path('Big Game.zip')
+        with zipfile.ZipFile(path, 'w') as z:
+            z.writestr('Big Game/BigGame.exe', tiny_programs.pe_x86_64())
+            z.writestr('Big Game/data.pak', os.urandom(2 * 1024 * 1024))
+        ctl('disk-full', 'on')
+        _, job = install_title(path)
+        self.assertIn('No space left on device', job['error'] or '', job)
+        # A first install that failed part-way leaves nothing behind.
+        self.assertFalse(exists(f'{HOME}/devkit-game/Big_Game'))
+        self.assertEqual(state()['devkit_games'], {})
+        ctl('disk-full', 'off')
+        _, job = install_title(path)
+        self.assertIsNone(job['error'], job)
+
+
+if __name__ == '__main__':
+    unittest.main()
diff --git a/tests/e2e/test_pairing.py b/tests/e2e/test_pairing.py
new file mode 100644
index 0000000..aaf1ecf
--- /dev/null
+++ b/tests/e2e/test_pairing.py
@@ -0,0 +1,111 @@
+"""Setting up the connection: ui/frame_connect.py against Valve's real
+steamos-devkit-service on the fake Frame, and its password fallback."""
+import json
+import os
+import stat
+import subprocess
+import sys
+import unittest
+import urllib.request
+
+import harness
+from harness import FAKE_HOST, ROOT, ctl, state, wait_for
+
+harness.require()
+
+
+class Pairing(harness.FrameTestCase):
+    def setUp(self):
+        super().setUp()
+        ctl('keys', 'none')             # a computer the headset doesn't know yet
+
+    def connect(self, askpass=None):
+        """Start frame_connect.py FAKE_HOST with no terminal, as the app's setup window would."""
+        env = {k: v for k, v in os.environ.items() if not k.startswith('SSH_ASKPASS')}
+        if askpass:
+            script = self.path('askpass')
+            with open(script, 'w') as f:
+                f.write(f'#!/bin/sh\necho {askpass}\n')
+            os.chmod(script, stat.S_IRWXU)
+            env.update(SSH_ASKPASS=script, SSH_ASKPASS_REQUIRE='force')
+        return subprocess.Popen([sys.executable, str(ROOT / 'ui' / 'frame_connect.py'), FAKE_HOST],
+                                stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                                text=True, env=env, start_new_session=True)
+
+    def finish(self, proc, timeout=120):
+        out, _ = proc.communicate(timeout=timeout)
+        return proc.returncode, out
+
+    def authorized_keys(self):
+        return ctl('authorized-keys')['text']
+
+    def test_service_properties_and_announcement(self):
+        # docs/ssh.md: properties.json answers "login": "steamos" on the Frame.
+        with urllib.request.urlopen(f'http://{FAKE_HOST}:32000/properties.json', timeout=10) as r:
+            props = json.load(r)
+        self.assertEqual(props['login'], 'steamos')
+        self.assertEqual(props['devkit1'], ['devkit-1'])
+        # At start the service announces _steamos-devkit._tcp under the Frame's hostname.
+        ctl('devkit-service', 'off')
+        ctl('devkit-service', 'on')
+        reg = wait_for(lambda: [c for c in harness.calls('resolve1') if c['method'] == 'RegisterService'],
+                       15, 'the mDNS registration')
+        self.assertEqual(reg[0]['args'][:3], ['frame', 'frame', '_steamos-devkit._tcp'])
+        self.assertEqual(reg[0]['args'][3], 32000)
+
+    def test_pairing_mode_refusal_then_approval(self):
+        proc = self.connect()
+        # The first /register is refused: "Pair new host" isn't open.
+        wait_for(lambda: any(r['answer'] == 'not in pairing mode' for r in state()['pairing_requests']),
+                 30, 'a refused pairing request')
+        ctl('pairing', 'on')            # the user opens Settings > Developer > Pair new host
+        rc, out = self.finish(proc)
+        self.assertEqual(rc, 0, out)
+        self.assertIn('paired; key login OK', out)
+        answers = [r['answer'] for r in state()['pairing_requests']]
+        self.assertEqual(answers[-1], 'approve')
+        self.assertIn('not in pairing mode', answers)
+        self.assertIn('frame-control@', state()['pairing_requests'][-1]['request'])
+        # The hook turned sshd on and installed the RSA key for steamos.
+        self.assertTrue(harness.calls('steamos-enable-sshd'))
+        keys = self.authorized_keys()
+        self.assertRegex(keys, r'(?m)^ssh-rsa \S+ frame-control@\S+$')
+        self.assertNotIn('900b919520e4cf601998a71eec318fec', keys)  # the magic phrase isn't stored
+
+    def test_denied_request_falls_back_to_the_password(self):
+        ctl('pairing', 'on')
+        ctl('answer', 'deny')
+        rc, out = self.finish(self.connect())   # no password to give: the fallback can't finish
+        self.assertEqual(rc, 1, out)
+        self.assertIn('devkit pairing failed: the pairing request was denied', out)
+        self.assertIn('falling back to the password', out)
+        self.assertNotIn('ssh-rsa', self.authorized_keys())
+
+    def test_service_down_uses_the_password(self):
+        ctl('devkit-service', 'off')
+        rc, out = self.finish(self.connect(askpass='frame'))
+        self.assertEqual(rc, 0, out)
+        self.assertIn('devkit service not reachable on port 32000', out)
+        self.assertIn('key login OK', out)
+        with open(os.path.expanduser('~/.ssh/id_ed25519_frame.pub')) as f:
+            ours = f.read().split()[1]
+        self.assertIn(ours, self.authorized_keys())
+
+    def test_prompt_left_unanswered_times_out(self):
+        # approve-ssh-key waits 30 s for Steam, then says so.
+        ctl('pairing', 'on')
+        ctl('answer', 'timeout')
+        rc, out = self.finish(self.connect(), timeout=150)
+        self.assertEqual(rc, 1, out)
+        self.assertIn('timeout - Steam did not respond to the pairing request', out)
+
+    def test_steam_not_running(self):
+        ctl('pairing', 'on')
+        ctl('steam', 'off')
+        rc, out = self.finish(self.connect())
+        self.assertEqual(rc, 1, out)
+        self.assertIn('devkit pairing failed: Steam is not running', out)
+
+
+if __name__ == '__main__':
+    unittest.main()
diff --git a/tests/e2e/test_titles.py b/tests/e2e/test_titles.py
new file mode 100644
index 0000000..c07bc0b
--- /dev/null
+++ b/tests/e2e/test_titles.py
@@ -0,0 +1,191 @@
+"""Sideloaded titles (ui/frame_titles.py) through the server's HTTP API, against
+Valve's devkit-utils talking to the fake Steam client."""
+import hashlib
+import http.server
+import json
+import os
+import platform
+import subprocess
+import sys
+import threading
+import unittest
+import zipfile
+
+import harness
+import tiny_programs
+from harness import HOME, ROOT, ctl, exists, install_title, launches, ok, ssh, state, wait_for
+
+harness.require()
+
+GAMES = f'{HOME}/devkit-game'
+# The host container shares the fake Frame's kernel, so a native program of this
+# machine's architecture really runs there; the other one fails to exec.
+NATIVE = {'aarch64': 'arm64', 'arm64': 'arm64', 'x86_64': 'x86_64'}.get(platform.machine())
+
+
+class Titles(harness.FrameTestCase):
+    def game_zip(self, name='Cool Game-v1.2-win64.zip', extra=b''):
+        path = self.path(name)
+        with zipfile.ZipFile(path, 'w') as z:
+            z.writestr('Cool Game/CoolGame.exe', tiny_programs.pe_x86_64())
+            z.writestr('Cool Game/CoolGame_Data/level0', b'level data' + extra)
+        return path
+
+    def folder(self, kind, name):
+        os.makedirs(self.path(name))
+        return tiny_programs.write(self.path(name), kind), self.path(name)
+
+    def assert_installed(self, gid, runtime, target):
+        game = state()['devkit_games'][gid]
+        self.assertEqual(game['settings']['compat_tool'], runtime)
+        self.assertEqual(game['argv'], [target])
+        steam = state()['steam']
+        shortcut = next(s for s in steam['shortcuts'] if s['devkit_gameid'] == gid)
+        self.assertEqual(steam['compat_tools'][str(shortcut['appid'])], runtime)
+        self.assertEqual(ssh(f'stat -c %a {GAMES}/{gid}/{target}').strip(), '755')
+        listed = {t['id']: t for t in ok('GET', '/api/titles')['titles']}
+        self.assertEqual(listed[gid]['runtime'], runtime)
+        self.assertTrue(listed[gid]['frame_control'])
+        return shortcut
+
+    def test_zip_with_a_windows_exe(self):
+        plan, job = install_title(self.game_zip())
+        self.assertEqual((plan['name'], plan['id'], plan['target']), ('Cool Game', 'Cool_Game', 'CoolGame.exe'))
+        self.assertEqual(plan['runtime'], 'proton-experimental')
+        self.assertIsNone(job['error'], job)
+        self.assertEqual(job['title']['runtime_label'], 'Proton Experimental')
+        self.assert_installed('Cool_Game', 'proton-experimental', 'CoolGame.exe')
+        game = state()['devkit_games']['Cool_Game']
+        self.assertEqual(game['settings'], {'steam_play': '1', 'steam_play_debug': '0',
+                                            'steam_play_debug_version': '2019', 'compat_tool': 'proton-experimental'})
+        self.assertTrue(exists(f'{GAMES}/Cool_Game/CoolGame_Data/level0'))
+        self.assertTrue(exists(f'{HOME}/devkit-utils/.frame-control-stamp'))
+
+    def test_folder_with_an_arm64_build_runs_natively(self):
+        _, folder = self.folder('arm64', 'Tiny Arm Game')
+        plan, job = install_title(folder)
+        self.assertEqual(plan['runtime'], 'SteamLinuxRuntime_4-arm64')
+        self.assertIsNone(job['error'], job)
+        self.assert_installed('Tiny_Arm_Game', 'SteamLinuxRuntime_4-arm64', 'fc-smoke-arm64')
+        ok('POST', '/api/titles', {'action': 'launch', 'id': 'Tiny_Arm_Game'})
+        run = launches('devkit')[-1]
+        # No runtime prefix: Steam ran the aarch64 build directly on the Frame.
+        self.assertEqual(run['command'], f'{GAMES}/Tiny_Arm_Game/fc-smoke-arm64')
+        if NATIVE == 'arm64':
+            self.assertIsNotNone(run['pid'], run)
+            done = wait_for(lambda: launches('devkit')[-1].get('exit') is not None and launches('devkit')[-1],
+                            20, 'the arm64 test program to exit')
+            self.assertEqual(done['exit'], 0)
+        else:
+            self.assertIn('Exec format error', run.get('exec_error', ''), run)
+
+    def test_single_exe_upload_launch_and_remove(self):
+        exe = tiny_programs.write(self.tmp, 'exe')
+        plan, job = install_title(exe)
+        self.assertEqual(plan['id'], 'fc_smoke_exe')
+        self.assertIsNone(job['error'], job)
+        shortcut = self.assert_installed('fc_smoke_exe', 'proton-experimental', 'fc-smoke-exe.exe')
+
+        ok('POST', '/api/titles', {'action': 'launch', 'id': 'fc_smoke_exe'})
+        run = launches('devkit')[-1]
+        self.assertTrue(run['started'])
+        self.assertEqual(run['command'], f'proton waitforexitandrun "{GAMES}/fc_smoke_exe/fc-smoke-exe.exe"')
+        prefix = f"{HOME}/.local/share/Steam/steamapps/compatdata/{shortcut['appid']}"
+        self.assertTrue(exists(prefix))
+
+        ok('POST', '/api/titles', {'action': 'remove', 'id': 'fc_smoke_exe'})
+        after = state()
+        self.assertNotIn('fc_smoke_exe', after['devkit_games'])
+        self.assertEqual(after['steam']['shortcuts'], [])
+        for gone in (f'{GAMES}/fc_smoke_exe', prefix, *(f'{GAMES}/fc_smoke_exe-{k}.json'
+                                                        for k in ('argv', 'env', 'settings', 'framecontrol'))):
+            self.assertFalse(exists(gone), gone)
+        self.assertEqual(ok('GET', '/api/titles')['titles'], [])
+
+    def test_names_steam_would_refuse_are_made_safe(self):
+        # Steam's create-shortcut takes ^[A-Za-z_][A-Za-z0-9_.]+$ only (device, 2026-09-27).
+        exe = self.path('2048-Deluxe.exe')
+        with open(exe, 'wb') as f:
+            f.write(tiny_programs.pe_x86_64())
+        plan, job = install_title(exe)
+        self.assertEqual(plan['id'], '_2048_Deluxe')
+        self.assertIsNone(job['error'], job)
+        self.assert_installed('_2048_Deluxe', 'proton-experimental', '2048-Deluxe.exe')
+
+    def test_x86_64_linux_build_needs_a_runtime_the_frame_lacks(self):
+        _, folder = self.folder('x86_64', 'Tiny PC Game')
+        plan, job = install_title(folder)
+        self.assertEqual(plan['runtime'], 'SteamLinuxRuntime_4')
+        self.assertIsNone(job['error'], job)
+        appid = self.assert_installed('Tiny_PC_Game', 'SteamLinuxRuntime_4', 'fc-smoke-x86_64')['appid']
+        # Steam answers the launch, then doesn't start it (docs/sideloading.md).
+        ok('POST', '/api/titles', {'action': 'launch', 'id': 'Tiny_PC_Game'})
+        run = launches('devkit')[-1]
+        self.assertFalse(run['started'])
+        self.assertEqual(run['message'], f'Tool 4183110 "Steam Linux Runtime 4.0" is found for appID {appid}, '
+                                         'but is not installed')
+        # With the runtime installed, it starts.
+        ctl('runtime', 'SteamLinuxRuntime_4', 'installed')
+        ok('POST', '/api/titles', {'action': 'launch', 'id': 'Tiny_PC_Game'})
+        run = launches('devkit')[-1]
+        self.assertTrue(run['started'])
+        if NATIVE == 'x86_64':
+            done = wait_for(lambda: launches('devkit')[-1].get('exit') is not None and launches('devkit')[-1],
+                            20, 'the x86-64 test program to exit')
+            self.assertEqual(done['exit'], 0)
+
+    def test_reinstall_with_another_runtime_keeps_one_shortcut(self):
+        zip_path = self.game_zip()
+        _, first = install_title(zip_path)
+        self.assertIsNone(first['error'], first)
+        appid = state()['devkit_games']['Cool_Game']['appid']
+        _, second = install_title(zip_path, runtime='proton-stable')
+        self.assertIsNone(second['error'], second)
+        self.assert_installed('Cool_Game', 'proton-stable', 'CoolGame.exe')
+        steam = state()['steam']
+        self.assertEqual([s['appid'] for s in steam['shortcuts']], [appid])
+        meta = json.loads(ssh(f'cat {GAMES}/Cool_Game-framecontrol.json'))
+        self.assertEqual(meta['runtime'], 'proton-stable')
+
+    def test_install_link_with_a_local_manifest(self):
+        # frame-control://install?manifest=... as a website would link it, served from
+        # this computer (FRAME_CONTROL_LOCAL_LINKS=1 lets http://127.0.0.1 through).
+        site = self.path('site')
+        os.makedirs(site)
+        with open(self.game_zip('linkgame-win64.zip'), 'rb') as f:
+            data = f.read()
+        with open(os.path.join(site, 'linkgame-win64.zip'), 'wb') as f:
+            f.write(data)
+        class Files(http.server.SimpleHTTPRequestHandler):
+            def __init__(self, *args):
+                super().__init__(*args, directory=site)
+
+            def log_message(self, *args):
+                pass
+        httpd = http.server.ThreadingHTTPServer(('127.0.0.1', 0), Files)
+        threading.Thread(target=httpd.serve_forever, daemon=True).start()
+        self.addCleanup(httpd.shutdown)
+        base = f'http://127.0.0.1:{httpd.server_address[1]}'
+        with open(os.path.join(site, 'manifest.json'), 'w') as f:
+            json.dump({'schema': 'framedrop.install/v1', 'name': 'Link Game',
+                       'files': [{'url': f'{base}/linkgame-win64.zip', 'sha256': hashlib.sha256(data).hexdigest(),
+                                  'size': len(data), 'exe': 'Cool Game/CoolGame.exe'}]}, f)
+
+        check = ok('POST', '/api/webinstall/check', {'manifest': f'{base}/manifest.json'})
+        self.assertEqual((check['name'], check['kind'], check['size']), ('Link Game', 'title', len(data)))
+        job_id = ok('POST', '/api/webinstall/start', {'id': check['id']})['job']
+        job = wait_for(lambda: (lambda j: j if j['phase'] in ('done', 'error') else None)(
+            ok('GET', f'/api/webinstall/job?id={job_id}')), 120, 'the link install')
+        self.assertEqual(job['phase'], 'done', job)
+        self.assert_installed('Link_Game', 'proton-experimental', 'CoolGame.exe')
+
+    def test_command_line_lists_what_the_app_installed(self):
+        install_title(self.game_zip())
+        out = subprocess.run([sys.executable, str(ROOT / 'ui' / 'frame_titles.py'), 'list'],
+                             capture_output=True, text=True, timeout=60)
+        self.assertEqual(out.returncode, 0, out.stderr)
+        self.assertEqual([t['id'] for t in json.loads(out.stdout)], ['Cool_Game'])
+
+
+if __name__ == '__main__':
+    unittest.main()
diff --git a/tests/fakeframe/Containerfile b/tests/fakeframe/Containerfile
new file mode 100644
index 0000000..ce1f2e0
--- /dev/null
+++ b/tests/fakeframe/Containerfile
@@ -0,0 +1,40 @@
+# The fake Steam Frame: Arch Linux (SteamOS's base) with sshd, rsync, python3,
+# Valve's steamos-devkit-service and hooks, a fake Steam client and stubs for
+# the Frame-only commands Frame Control runs. See docs/testing.md.
+#
+# BASE: archlinux:base on x86_64, menci/archlinuxarm:base on arm64 (a daily
+# Arch Linux ARM build); scripts/e2e.sh picks one from `uname -m`.
+ARG BASE=archlinux:base
+FROM ${BASE}
+
+RUN (pacman-key --init && pacman-key --populate) >/dev/null 2>&1; \
+    pacman -Syu --noconfirm --needed openssh rsync python nodejs curl iproute2 procps-ng util-linux \
+    && pacman -Scc --noconfirm
+
+# The Frame's user is steamos (docs/ssh.md). Its password stands in for the
+# Developer Mode password.
+RUN useradd -m -u 1000 -s /bin/bash steamos \
+    && echo 'steamos:frame' | chpasswd \
+    && ssh-keygen -A
+
+# Valve's service and hooks where the service looks for them. It runs as
+# steamos, so it lists one user and properties.json says "login": "steamos",
+# as the Frame's does (docs/ssh.md, verified 2026-09-26, BUILD_ID 20260922.6101926).
+COPY steamos-devkit-service/src/steamos-devkit-service.py /usr/lib/steamos-devkit/
+COPY steamos-devkit-service/hooks/ /usr/share/steamos-devkit/hooks/
+COPY rootfs/ /
+
+# /etc/os-release, pointed at /usr/lib/os-release, carries the Frame's
+# VERSION_ID 0.3.0, VARIANT_ID vr and BUILD_ID 20260922.6101926 (docs/apks.md).
+RUN ln -sf ../usr/lib/os-release /etc/os-release \
+    && chmod 755 /usr/share/steamos-devkit/hooks/approve-ssh-key /usr/share/steamos-devkit/hooks/install-ssh-key \
+      /usr/share/steamos-devkit/hooks/devkit-1-identify /usr/local/bin/* /usr/local/lib/fakeframe/*.py \
+      /usr/bin/steamos-polkit-helpers/steamos-enable-sshd \
+    && mkdir -p /usr/local/lib/fakeframe/bin /var/lib/fakeframe /var/log/fakeframe /home/steamos/devkit-game \
+    && cp /usr/bin/sleep /usr/local/lib/fakeframe/bin/vrserver \
+    && cp /usr/bin/sleep /usr/local/lib/fakeframe/bin/plasmashell \
+    && chmod 1777 /var/lib/fakeframe /var/log/fakeframe \
+    && chown -R steamos:steamos /home/steamos
+
+EXPOSE 22 32000 9999
+CMD ["python3", "/usr/local/lib/fakeframe/init.py"]
diff --git a/tests/fakeframe/compose.yaml b/tests/fakeframe/compose.yaml
new file mode 100644
index 0000000..089321c
--- /dev/null
+++ b/tests/fakeframe/compose.yaml
@@ -0,0 +1,54 @@
+# The fake Frame and the computer Frame Control runs on, for tests/e2e.
+# scripts/e2e.sh builds the two images, brings this up, runs the tests in
+# `host` and takes it down again.
+name: fakeframe-e2e
+services:
+  fakeframe:
+    image: fakeframe-frame
+    pull_policy: never
+    hostname: frame               # the Frame's default hostname (docs/ssh.md)
+    init: true
+    tmpfs:
+      # Small, so `fakeframe-ctl disk-full on` can fill it.
+      - /home/steamos/devkit-game:size=64m,mode=0755,exec
+    volumes:
+      - keys:/keys
+      # frame_status.py reads the battery and thermal zones from /sys, which is
+      # read-only in a container (and docker's AppArmor profile refuses writes
+      # under /sys even to a mount there). So each folder is a volume mounted
+      # twice: over /sys/class/... for reading, and under /var/lib/fakeframe/sys
+      # where the supervisor writes it (fakeframe-ctl battery).
+      - power:/sys/class/power_supply
+      - power:/var/lib/fakeframe/sys/power_supply
+      - thermal:/sys/class/thermal
+      - thermal:/var/lib/fakeframe/sys/thermal
+    environment:
+      FAKEFRAME_PAIRING_MODE: ${FAKEFRAME_PAIRING_MODE:-0}
+    healthcheck:
+      test: ["CMD", "fakeframe-ctl", "ping"]
+      interval: 2s
+      timeout: 10s
+      retries: 60
+  host:
+    image: fakeframe-host
+    pull_policy: never
+    init: true
+    depends_on:
+      fakeframe:
+        condition: service_healthy
+    volumes:
+      - ../..:/repo:ro
+      - keys:/keys:ro
+    environment:
+      FAKEFRAME_CTL: http://fakeframe:9999
+      FAKEFRAME_HOST: fakeframe
+      FRAME_E2E: "1"
+    healthcheck:
+      test: ["CMD", "test", "-f", "/home/tester/.ready"]
+      interval: 1s
+      timeout: 5s
+      retries: 120
+volumes:
+  keys:
+  power:
+  thermal:
diff --git a/tests/fakeframe/host.Containerfile b/tests/fakeframe/host.Containerfile
new file mode 100644
index 0000000..bfdc7b5
--- /dev/null
+++ b/tests/fakeframe/host.Containerfile
@@ -0,0 +1,14 @@
+# The computer Frame Control runs on, for the e2e tests: Python 3.9 (the
+# oldest the app supports), the OpenSSH client and rsync, and nothing else.
+# The repository is mounted read-only at /repo (compose.yaml). OpenSSH reads
+# ~/.ssh/config from the passwd home, not $HOME, which is why this is a
+# container of its own rather than a HOME override on the machine running the tests.
+FROM python:3.9-slim-bookworm
+RUN apt-get update && apt-get install -y --no-install-recommends openssh-client rsync procps \
+    && rm -rf /var/lib/apt/lists/* \
+    && useradd -m -u 1000 -s /bin/bash tester
+COPY host/entrypoint.sh /usr/local/bin/fakeframe-host
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
+USER tester
+WORKDIR /repo
+CMD ["fakeframe-host"]
diff --git a/tests/fakeframe/host/entrypoint.sh b/tests/fakeframe/host/entrypoint.sh
new file mode 100755
index 0000000..b4727c0
--- /dev/null
+++ b/tests/fakeframe/host/entrypoint.sh
@@ -0,0 +1,25 @@
+#!/bin/bash
+# The computer side of the harness: tester's ~/.ssh as Frame Control's setup
+# leaves it (ui/frame_connect.py's own config block), pointing `frame` at the
+# fake Frame, with the harness key the fake trusts.
+set -euo pipefail
+host=${FAKEFRAME_HOST:-fakeframe}
+for _ in $(seq 1 240); do
+  [ -s /keys/id_ed25519_frame.pub ] && break
+  sleep 0.5
+done
+mkdir -p -m 700 ~/.ssh
+install -m 600 /keys/id_ed25519_frame ~/.ssh/id_ed25519_frame
+install -m 644 /keys/id_ed25519_frame.pub ~/.ssh/id_ed25519_frame.pub
+python3 - "$host" > ~/.ssh/config <<'PY'
+import sys
+sys.path.insert(0, '/repo/ui')
+import frame_connect
+print('\n'.join(frame_connect.config_block(sys.argv[1])))
+PY
+chmod 600 ~/.ssh/config
+until ssh-keyscan -T 2 "$host" > ~/.ssh/known_hosts 2>/dev/null && [ -s ~/.ssh/known_hosts ]; do
+  sleep 1
+done
+touch ~/.ready
+exec sleep infinity
diff --git a/tests/fakeframe/rootfs/etc/ssh/sshd_config b/tests/fakeframe/rootfs/etc/ssh/sshd_config
new file mode 100644
index 0000000..74bc0f9
--- /dev/null
+++ b/tests/fakeframe/rootfs/etc/ssh/sshd_config
@@ -0,0 +1,21 @@
+# The fake Frame's sshd. With Developer Mode on, the Frame takes key logins and
+# the Developer Mode password for `steamos` (docs/ssh.md); the fake's password
+# is "frame". MaxSessions leaves room for Frame Control's shared connection.
+Port 22
+HostKey /etc/ssh/ssh_host_ed25519_key
+HostKey /etc/ssh/ssh_host_rsa_key
+HostKey /etc/ssh/ssh_host_ecdsa_key
+PermitRootLogin no
+PubkeyAuthentication yes
+AuthorizedKeysFile .ssh/authorized_keys
+PasswordAuthentication yes
+KbdInteractiveAuthentication no
+UsePAM no
+PrintMotd no
+MaxSessions 64
+MaxStartups 64:30:128
+# OpenSSH 9.8+ penalises an address after failed logins by refusing it for a
+# while. The pairing tests fail logins on purpose, so the fake turns that off.
+# (Whether the Frame's sshd penalises is unchecked.)
+PerSourcePenalties no
+Subsystem sftp /usr/lib/ssh/sftp-server
diff --git a/tests/fakeframe/rootfs/usr/bin/steamos-polkit-helpers/steamos-enable-sshd b/tests/fakeframe/rootfs/usr/bin/steamos-polkit-helpers/steamos-enable-sshd
new file mode 100755
index 0000000..8386d15
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/bin/steamos-polkit-helpers/steamos-enable-sshd
@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+"""Stub for SteamOS's polkit helper, which approve-ssh-key runs once a pairing
+is approved: asks the fake Frame's supervisor to (re)start sshd."""
+import json
+import sys
+import urllib.request
+
+sys.path.insert(0, '/usr/local/lib/fakeframe')
+import fakeframe_state as fs  # noqa: E402
+
+fs.log('steamos-enable-sshd')
+req = urllib.request.Request('http://127.0.0.1:9999/ctl', data=json.dumps({'args': ['sshd', 'on']}).encode(),
+                             headers={'Content-Type': 'application/json'})
+urllib.request.urlopen(req, timeout=10).read()
diff --git a/tests/fakeframe/rootfs/usr/lib/os-release b/tests/fakeframe/rootfs/usr/lib/os-release
new file mode 100644
index 0000000..baac582
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/lib/os-release
@@ -0,0 +1,9 @@
+NAME="SteamOS"
+PRETTY_NAME="SteamOS"
+ID=steamos
+ID_LIKE=arch
+LOGO=steamos
+HOME_URL="https://www.steampowered.com/"
+VERSION_ID=0.3.0
+VARIANT_ID=vr
+BUILD_ID=20260922.6101926
diff --git a/tests/fakeframe/rootfs/usr/local/bin/fakeframe-ctl b/tests/fakeframe/rootfs/usr/local/bin/fakeframe-ctl
new file mode 100755
index 0000000..bdbb02b
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/local/bin/fakeframe-ctl
@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""Flip the fake Frame's fault switches and read its state; `fakeframe-ctl help`.
+
+Talks to the supervisor's control port, so it works the same over SSH
+(`ssh frame fakeframe-ctl steam off`) and from the host container with
+FAKEFRAME_CTL=http://fakeframe:9999.
+"""
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+url = os.environ.get('FAKEFRAME_CTL', 'http://127.0.0.1:9999').rstrip('/')
+req = urllib.request.Request(url + '/ctl', data=json.dumps({'args': sys.argv[1:]}).encode(),
+                             headers={'Content-Type': 'application/json'})
+try:
+    with urllib.request.urlopen(req, timeout=60) as r:
+        out = json.load(r)
+except urllib.error.HTTPError as e:
+    out = json.load(e)
+except OSError as e:
+    sys.exit(f'fakeframe-ctl: control port not answering ({e})')
+if 'usage' in out:
+    print(out['usage'])
+elif 'error' in out:
+    sys.exit(f"fakeframe-ctl: {out['error']}")
+else:
+    print(json.dumps(out, indent=1))
+    if sys.argv[1:2] == ['ping'] and not out.get('ok'):
+        sys.exit(1)
diff --git a/tests/fakeframe/rootfs/usr/local/bin/flatpak b/tests/fakeframe/rootfs/usr/local/bin/flatpak
new file mode 100755
index 0000000..1d9d510
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/local/bin/flatpak
@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Stub for flatpak: --user installs and removals, and `list`, kept in the state file.
+Nothing is downloaded; an app id containing "missing" fails like an unknown ref."""
+import sys
+
+sys.path.insert(0, '/usr/local/lib/fakeframe')
+import fakeframe_state as fs  # noqa: E402
+
+args = sys.argv[1:]
+fs.log('flatpak', args=args)
+words = [a for a in args if not a.startswith('-')]
+cmd = words[0] if words else ''
+if cmd == 'remote-add':
+    pass
+elif cmd == 'install':
+    app = words[-1]
+    if 'missing' in app:
+        sys.exit(f'error: Nothing matches {app} in remote flathub')
+    with fs.update() as s:
+        if not any(f['id'] == app for f in s['flatpaks']):
+            s['flatpaks'].append({'id': app, 'name': app.rsplit('.', 1)[-1], 'version': '1.0', 'installation': 'user'})
+    print(f'Installing {app}\nInstallation complete.')
+elif cmd == 'uninstall':
+    app = words[-1]
+    with fs.update() as s:
+        before = len(s['flatpaks'])
+        s['flatpaks'] = [f for f in s['flatpaks'] if f['id'] != app]
+        gone = len(s['flatpaks']) < before
+    if not gone:
+        sys.exit(f'error: {app}/*unspecified*/*unspecified* not installed')
+    print('Uninstall complete.')
+elif cmd == 'list':
+    for f in fs.read()['flatpaks']:
+        print('\t'.join((f['id'], f['name'], f['version'], f['installation'])))
+elif cmd == 'run':
+    pass
+else:
+    sys.exit(f'flatpak stub: unsupported {args}')
diff --git a/tests/fakeframe/rootfs/usr/local/bin/gamescopectl b/tests/fakeframe/rootfs/usr/local/bin/gamescopectl
new file mode 100755
index 0000000..6ba57c0
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/local/bin/gamescopectl
@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""Stub for gamescopectl: `screenshot FILE` writes a small PNG, as gamescope does
+(asynchronously on the Frame, which server.SCREENSHOT waits out)."""
+import struct
+import sys
+import zlib
+
+sys.path.insert(0, '/usr/local/lib/fakeframe')
+import fakeframe_state as fs  # noqa: E402
+
+args = sys.argv[1:]
+fs.log('gamescopectl', args=args)
+if len(args) != 2 or args[0] != 'screenshot':
+    sys.exit(f'gamescopectl stub: unsupported {args}')
+
+
+def chunk(kind, data):
+    return struct.pack('>I', len(data)) + kind + data + struct.pack('>I', zlib.crc32(kind + data))
+
+
+w, h = 64, 36
+rows = b''.join(b'\0' + b''.join(bytes((x * 4, y * 7, 160)) for x in range(w)) for y in range(h))
+png = (b'\x89PNG\r\n\x1a\n' + chunk(b'IHDR', struct.pack('>IIBBBBB', w, h, 8, 2, 0, 0, 0))
+       + chunk(b'IDAT', zlib.compress(rows)) + chunk(b'IEND', b''))
+with open(args[1], 'wb') as f:
+    f.write(png)
diff --git a/tests/fakeframe/rootfs/usr/local/bin/nmcli b/tests/fakeframe/rootfs/usr/local/bin/nmcli
new file mode 100755
index 0000000..d416776
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/local/bin/nmcli
@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+"""Stub for nmcli: the Wi-Fi network frame_status.py reads with
+`nmcli -t -f active,ssid,signal dev wifi` (':' inside fields escaped as '\\:')."""
+import sys
+
+sys.path.insert(0, '/usr/local/lib/fakeframe')
+import fakeframe_state as fs  # noqa: E402
+
+fs.log('nmcli', args=sys.argv[1:])
+print('yes:Fake\\:Frame Wi-Fi:72')
+print('no:Neighbours:31')
diff --git a/tests/fakeframe/rootfs/usr/local/bin/podman b/tests/fakeframe/rootfs/usr/local/bin/podman
new file mode 100755
index 0000000..a996bf3
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/local/bin/podman
@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Stub for podman, for the fake Lepton instances (lepton.py): ps, stop, exec.
+`podman ps --format "{{.Names}} {{.Labels.adb_port}}"` lists what's running,
+as frame_android.running_instances reads it (docs/apks.md)."""
+import os
+import sys
+import time
+
+sys.path.insert(0, '/usr/local/lib/fakeframe')
+import fakeframe_state as fs  # noqa: E402
+
+
+def alive(c):
+    try:
+        os.kill(c['pid'], 0)
+        return True
+    except OSError:
+        return False
+
+
+args = sys.argv[1:]
+fs.log('podman', args=args)
+cmd = args[0] if args else ''
+containers = {n: c for n, c in fs.read()['lepton'].items() if alive(c)}
+if cmd == 'ps':
+    for name, c in sorted(containers.items()):
+        print(f"{name} {c['port']}")
+elif cmd == 'stop':
+    name = args[-1]
+    c = containers.get(name)
+    if not c:
+        sys.exit(f'Error: no container with name or ID "{name}" found: no such container')
+    os.kill(c['pid'], 15)
+    for _ in range(50):
+        if not alive(c):
+            break
+        time.sleep(0.1)
+    print(name)
+elif cmd == 'exec':
+    name, rest = args[1], ' '.join(args[2:])
+    if name not in containers:
+        sys.exit(f'Error: no container with name or ID "{name}" found: no such container')
+    if 'pidof' in rest:
+        print(4242)                   # the app is "up"; there's no Android to ask
+    # logcat and anything else: nothing to report
+else:
+    sys.exit(f'podman stub: unsupported {args}')
diff --git a/tests/fakeframe/rootfs/usr/local/bin/qdbus6 b/tests/fakeframe/rootfs/usr/local/bin/qdbus6
new file mode 100755
index 0000000..c1afafb
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/local/bin/qdbus6
@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""Stub for qdbus6: records Klipper setClipboardContents calls, the way
+Frame Control sends text to the headset desktop's clipboard (server.PASTE,
+verified 2026-09-25)."""
+import os
+import sys
+
+sys.path.insert(0, '/usr/local/lib/fakeframe')
+import fakeframe_state as fs  # noqa: E402
+
+args = sys.argv[1:]
+fs.log('qdbus6', args=args[:3], bus=os.environ.get('DBUS_SESSION_BUS_ADDRESS'))
+if args[:3] == ['org.kde.klipper', '/klipper', 'org.kde.klipper.klipper.setClipboardContents'] and len(args) == 4:
+    if not os.environ.get('DBUS_SESSION_BUS_ADDRESS'):
+        sys.exit('Could not connect to D-Bus server')
+    with fs.update() as s:
+        s['clipboard'].append(args[3])
+else:
+    sys.exit(f'qdbus6 stub: unsupported {args}')
diff --git a/tests/fakeframe/rootfs/usr/local/bin/steam b/tests/fakeframe/rootfs/usr/local/bin/steam
new file mode 100755
index 0000000..0ce1613
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/local/bin/steam
@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""Stub for SteamOS's `steam` command: hands steam:// URLs to the running client.
+
+On the Frame, `steam steam://rungameid/N` over SSH starts the game in the
+running client (docs/apks.md, docs/steam-games.md, 2026-09-25). How the real
+wrapper passes the URL on isn't documented; this writes it as a line on
+~/.steam/steam.pipe, which fakesteam reads (guess).
+"""
+import os
+import sys
+
+sys.path.insert(0, '/usr/local/lib/fakeframe')
+import fakeframe_state as fs  # noqa: E402
+
+args = sys.argv[1:]
+running = fs.steam_pid() is not None
+fs.log('steam', args=args, client_running=running)
+if not running:
+    # The real command would start the Steam client; this one can't.
+    print('steam: the Steam client is not running', file=sys.stderr)
+    sys.exit(0)
+fd = os.open(os.path.expanduser('~/.steam/steam.pipe'), os.O_RDWR)
+try:
+    os.write(fd, (' '.join(args) + '\n').encode())
+finally:
+    os.close(fd)
diff --git a/tests/fakeframe/rootfs/usr/local/bin/wpctl b/tests/fakeframe/rootfs/usr/local/bin/wpctl
new file mode 100755
index 0000000..a423110
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/local/bin/wpctl
@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Stub for PipeWire's wpctl: the default sink's volume and mute, kept in the state file.
+Output format as wpctl prints it: "Volume: 0.40" plus " [MUTED]"."""
+import sys
+
+sys.path.insert(0, '/usr/local/lib/fakeframe')
+import fakeframe_state as fs  # noqa: E402
+
+args = sys.argv[1:]
+fs.log('wpctl', args=args)
+if len(args) == 2 and args[0] == 'get-volume':
+    v = fs.read()['volume']
+    print(f"Volume: {v['level']:.2f}" + (' [MUTED]' if v['muted'] else ''))
+elif len(args) == 3 and args[0] == 'set-volume':
+    with fs.update() as s:
+        s['volume']['level'] = max(0.0, min(1.5, float(args[2])))
+elif len(args) == 3 and args[0] == 'set-mute':
+    with fs.update() as s:
+        s['volume']['muted'] = args[2] == 'toggle' and not s['volume']['muted'] or args[2] == '1'
+else:
+    sys.exit(f'wpctl stub: unsupported {args}')
diff --git a/tests/fakeframe/rootfs/usr/local/lib/fakeframe/cef_shim.js b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/cef_shim.js
new file mode 100644
index 0000000..e50f3cf
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/cef_shim.js
@@ -0,0 +1,157 @@
+// The fake Steam client's JavaScript context ("SharedJSContext"), for fakesteam's
+// DevTools server. fakesteam sends one JSON request per line on stdin:
+//   {"id": N, "expression": "...", "awaitPromise": true, "steam": {...state...}}
+// and gets one line back: {"id": N, "result": <CDP Runtime.evaluate result>, "steam": {...}}.
+// The expression runs for real in a V8 context holding the objects below, so
+// whatever JavaScript Frame Control sends (async functions, optional chaining,
+// Map) behaves as it would in Steam's CEF; only the objects are stand-ins.
+//
+// Shapes copy what was seen through the Frame's DevTools port on 2026-09-25
+// (docs/steam-games.md and docs/apks.md, BUILD_ID 20260922.6101926):
+// appStore.allApps, a Map in downloadsStore.m_DownloadOverview keyed by client
+// id with "0" for this machine, SteamClient.Installs.GetInstallManagerInfo /
+// ContinueInstall, SteamClient.User.GetIPCountry, and SteamClient.Apps.AddShortcut
+// + SetShortcutName / SetShortcutStartDir for non-Steam shortcuts.
+'use strict';
+const vm = require('vm');
+const readline = require('readline');
+
+const SHORTCUT_TYPE = 1073741824;  // app_type of a non-Steam shortcut, as steam_shortcuts.py filters
+
+function newShortcutId(steam) {
+  // Real shortcut ids are 32-bit with the top bit set (T3 Code's was 3130509679).
+  steam.next_shortcut = (steam.next_shortcut || 0) + 1;
+  return (0x80000000 + ((steam.next_shortcut * 2654435761) >>> 1)) >>> 0;
+}
+
+function build(steam) {
+  const findShortcut = id => steam.shortcuts.find(s => s.appid === Number(id));
+  const gameOverview = a => ({
+    appid: a.appid, display_name: a.display_name, sort_as: a.display_name, app_type: 1,
+    steam_hw_compat_category_packed: a.packed || 0, vr_supported: !!a.vr, vr_only: !!a.vr_only,
+    size_on_disk: String(a.installed ? a.size : 0), minutes_playtime_forever: a.minutes || 0,
+    rt_last_time_played: a.last_played || 0,
+    local_per_client_data: {
+      installed: !!a.installed, display_status: a.display_status ?? (a.installed ? 1 : 0),
+      status_percentage: a.status_percentage ?? 0,
+    },
+  });
+  const shortcutOverview = s => ({
+    appid: s.appid, display_name: s.name, sort_as: s.name, app_type: SHORTCUT_TYPE,
+    local_per_client_data: { installed: true, display_status: 1, status_percentage: 0 },
+  });
+  const allApps = () => [...steam.apps.map(gameOverview), ...steam.shortcuts.map(shortcutOverview)];
+
+  const im = () => steam.install_manager;
+  const queue = appid => {
+    // State 14: Steam queued the download (Balatro on the Frame, docs/steam-games.md).
+    const app = steam.apps.find(a => a.appid === appid);
+    Object.assign(im(), { eInstallState: 14, currentAppID: appid });
+    if (app) {
+      steam.download = { update_appid: appid, update_state: 'Downloading', paused: false,
+                         update_is_install: true, overall_percent_complete: 0,
+                         overall_estimated_time_remaining_sec: 7, update_network_bytes_per_second: 9500000 };
+    }
+  };
+
+  return {
+    appStore: {
+      get allApps() { return allApps(); },
+      GetAppOverviewByAppID(id) { return allApps().find(a => a.appid === Number(id)) || null; },
+    },
+    downloadsStore: {
+      get m_DownloadOverview() { return steam.download ? new Map([['0', { ...steam.download }]]) : new Map(); },
+    },
+    SteamClient: {
+      Apps: {
+        async AddShortcut(name, exe, launchOptions, cmdLine) {
+          const appid = newShortcutId(steam);
+          const base = String(exe).split('/').pop();
+          steam.shortcuts.push({ appid, name: base, exe: String(exe), start_dir: '', icon: '',
+                                 launch_options: String(launchOptions || ''), devkit_gameid: null });
+          return appid;
+        },
+        SetShortcutName(id, name) { const s = findShortcut(id); if (s) s.name = String(name); },
+        SetShortcutStartDir(id, dir) { const s = findShortcut(id); if (s) s.start_dir = String(dir); },
+        SetShortcutIcon(id, icon) { const s = findShortcut(id); if (s) s.icon = String(icon); },
+        SetShortcutExe(id, exe) { const s = findShortcut(id); if (s) s.exe = String(exe); },
+        RemoveShortcut(id) {
+          steam.shortcuts = steam.shortcuts.filter(s => s.appid !== Number(id));
+          delete steam.compat_tools[String(id)];
+        },
+      },
+      Installs: {
+        async GetInstallManagerInfo() {
+          const i = im();
+          return { eInstallState: i.eInstallState, currentAppID: i.currentAppID,
+                   nDiskSpaceRequired: i.nDiskSpaceRequired, nDiskSpaceAvailable: i.nDiskSpaceAvailable,
+                   eAppError: i.eAppError ?? 0, errorDetail: i.errorDetail ?? '' };
+        },
+        // Broforce stopped at state 7 and ContinueInstall() queued it (docs/steam-games.md).
+        ContinueInstall() { if (im().eInstallState === 7) queue(im().currentAppID); },
+        CancelInstall() { Object.assign(im(), { eInstallState: 16 }); },
+        // Calling OpenInstallWizard directly did nothing on the Frame: the state stayed 0.
+        OpenInstallWizard() {},
+      },
+      User: {
+        async GetIPCountry() { return steam.country; },
+      },
+    },
+  };
+}
+
+// What CDP's Runtime.evaluate returns with returnByValue.
+function remote(value) {
+  if (value === undefined) return { type: 'undefined' };
+  if (value === null) return { type: 'object', subtype: 'null', value: null };
+  const type = typeof value;
+  if (type === 'object') return { type: 'object', value: JSON.parse(JSON.stringify(value)) };
+  if (type === 'function') return { type: 'function', description: String(value) };
+  return { type, value, description: String(value) };
+}
+
+function exception(err, inPromise) {
+  // Chrome puts the stack in description; its first line is enough here.
+  const description = err && err.name ? `${err.name}: ${err.message}` : String(err);
+  return {
+    result: { type: 'object', subtype: 'error', className: (err && err.name) || 'Error', description },
+    exceptionDetails: {
+      exceptionId: 1, text: inPromise ? 'Uncaught (in promise)' : 'Uncaught', lineNumber: 0, columnNumber: 0,
+      exception: { type: 'object', subtype: 'error', className: (err && err.name) || 'Error', description },
+    },
+  };
+}
+
+async function evaluate(req) {
+  const steam = req.steam;
+  const ctx = vm.createContext(build(steam));
+  let value;
+  try {
+    value = vm.runInContext(req.expression, ctx, { timeout: 5000 });
+  } catch (err) {
+    return exception(err, false);
+  }
+  if (req.awaitPromise && value && typeof value.then === 'function') {
+    try {
+      value = await value;
+    } catch (err) {
+      return exception(err, true);
+    }
+  }
+  try {
+    return { result: remote(value) };
+  } catch (err) {
+    return exception(err, false);
+  }
+}
+
+// One request at a time: fakesteam holds the state lock around each.
+const rl = readline.createInterface({ input: process.stdin });
+let chain = Promise.resolve();
+rl.on('line', line => {
+  chain = chain.then(async () => {
+    const req = JSON.parse(line);
+    const result = await evaluate(req);
+    process.stdout.write(JSON.stringify({ id: req.id, result, steam: req.steam }) + '\n');
+  });
+});
diff --git a/tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakeframe_state.py b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakeframe_state.py
new file mode 100755
index 0000000..707f5dc
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakeframe_state.py
@@ -0,0 +1,183 @@
+"""Shared state of the fake Frame: one JSON file plus a log of stub calls.
+
+Every fake part (the supervisor, fakesteam, the command stubs) reads and
+writes /var/lib/fakeframe/state.json through update(), which holds an
+exclusive flock, so separate processes never lose each other's changes.
+Tests read the file over SSH (`fakeframe-ctl state`) or the control port.
+"""
+import contextlib
+import fcntl
+import json
+import os
+import time
+
+DIR = '/var/lib/fakeframe'
+STATE = os.path.join(DIR, 'state.json')
+CALLS = os.path.join(DIR, 'calls.jsonl')
+LOCK = os.path.join(DIR, 'state.lock')
+
+HOME = '/home/steamos'
+STEAM_ROOT = HOME + '/.local/share/Steam'
+DEVKIT_GAMES = HOME + '/devkit-game'
+LEPTON = STEAM_ROOT + '/steamapps/common/Lepton/lepton'
+
+# Compat tools and the Steam app ids of their depots. 4183110 is the id Steam
+# printed on the Frame for "Steam Linux Runtime 4.0" (docs/sideloading.md,
+# BUILD_ID 20260922.6101926); Lepton Development is 3056000 (docs/apks.md).
+# The others are placeholders: nothing in Frame Control reads them.
+RUNTIME_APPIDS = {'proton-experimental': 1493710, 'proton-stable': 3658110,
+                  'SteamLinuxRuntime_4-arm64': 4183120, 'SteamLinuxRuntime_4': 4183110,
+                  'lepton': 3056000}
+RUNTIME_NAMES = {'proton-experimental': 'Proton Experimental', 'proton-stable': 'Proton 11.0',
+                 'SteamLinuxRuntime_4-arm64': 'Steam Linux Runtime 4.0 (arm64)',
+                 'SteamLinuxRuntime_4': 'Steam Linux Runtime 4.0', 'lepton': 'Lepton Development'}
+
+
+def default_state():
+    return {
+        'switches': {
+            'pairing_mode': False,      # Steam Settings > Developer > Pair new host open or not
+            'pairing_answer': 'approve',  # approve | deny | timeout
+            'steam': True,              # Steam client running
+            'asleep': False,            # headset asleep: ports 22 and 32000 accept but never answer
+            'sshd': True,
+            'devkit_service': True,
+            'disk_full': False,
+        },
+        # Which compat tools are installed. On the Frame the x86-64 Steam Linux
+        # Runtime 4.0 wasn't, and a devkit title didn't install it (docs/sideloading.md,
+        # 2026-09-26, BUILD_ID 20260922.6101926).
+        'runtimes': {'proton-experimental': True, 'proton-stable': True,
+                     'SteamLinuxRuntime_4-arm64': True, 'SteamLinuxRuntime_4': False, 'lepton': True},
+        # /sys/class/power_supply values, in the units the kernel uses (µV, µA, tenths
+        # of °C), as frame_status.py reads them (paths verified on build 20260922; its
+        # docstring gives the charger type 'C PD [PD_PPS]' at 20 W as seen on the Frame).
+        'battery': {'capacity': 76, 'status': 'Charging', 'voltage_now': 7700000, 'current_now': 1250000,
+                    'time_to_full_now': 2520, 'temp': 312, 'health': 'Good',
+                    'charger': {'online': 1, 'usb_type': 'C PD [PD_PPS]', 'voltage_now': 9000000,
+                                'current_now': 2220000}},
+        'thermal_mc': [41500, 38250],   # thermal_zone*/temp, millidegrees C
+        'volume': {'level': 0.4, 'muted': False},
+        'flatpaks': [],
+        'clipboard': [],
+        'steam': {
+            'country': 'AU',            # GetIPCountry() answered "AU" (docs/steam-games.md)
+            'next_shortcut': 0,
+            # A few owned games. Balatro went straight to install state 14 and
+            # Broforce stopped at 7 on the Frame (docs/steam-games.md, 2026-09-25,
+            # BUILD_ID 20260922.6101926); `wizard` makes the fake do the same.
+            'apps': [
+                {'appid': 2379780, 'display_name': 'Balatro', 'installed': False, 'size': 67000000,
+                 'packed': 3 << 8 | 3, 'vr': False, 'wizard': 14},
+                {'appid': 274190, 'display_name': 'Broforce', 'installed': False, 'size': 600000000,
+                 'packed': 0 << 8 | 2, 'vr': False, 'wizard': 7},
+                {'appid': 620980, 'display_name': 'Beat Saber', 'installed': True, 'size': 4200000000,
+                 'packed': 3 << 8 | 1, 'vr': True, 'vr_only': True, 'wizard': 14},
+            ],
+            'shortcuts': [],            # {appid, name, exe, start_dir, icon, devkit_gameid}
+            'compat_tools': {},         # shortcut appid (str) -> compat tool alias (CompatToolMapping)
+            'install_manager': {'eInstallState': 0, 'currentAppID': 0, 'nDiskSpaceRequired': 0,
+                                'nDiskSpaceAvailable': 0},
+            'download': None,
+            'pages': [],                # extra DevTools targets, e.g. a store page
+        },
+        'devkit_games': {},             # gameid -> what create-shortcut registered
+        'launches': [],                 # every launch Steam was asked for, and what it did
+        'pairing_requests': [],
+        'lepton': {},                   # container name -> {port, pid, package dir}
+    }
+
+
+def _share(fd):
+    # Files are made by root or steamos, whichever comes first; both write them (umask aside).
+    try:
+        os.fchmod(fd, 0o666)
+    except OSError:
+        pass                            # not ours: whoever made it already did this
+
+
+def _ensure_dir():
+    os.makedirs(DIR, exist_ok=True)
+
+
+@contextlib.contextmanager
+def _locked(kind):
+    _ensure_dir()
+    fd = os.open(LOCK, os.O_RDWR | os.O_CREAT, 0o666)
+    _share(fd)
+    try:
+        fcntl.flock(fd, kind)
+        yield
+    finally:
+        os.close(fd)
+
+
+def _load():
+    try:
+        with open(STATE) as f:
+            return json.load(f)
+    except (OSError, ValueError):
+        return default_state()
+
+
+def _save(state):
+    tmp = f'{STATE}.{os.getpid()}.tmp'
+    with open(tmp, 'w') as f:
+        json.dump(state, f, indent=1, sort_keys=True)
+    os.chmod(tmp, 0o666)                # the supervisor (root) and steamos both write it
+    os.replace(tmp, STATE)
+
+
+def read():
+    with _locked(fcntl.LOCK_SH):
+        return _load()
+
+
+@contextlib.contextmanager
+def update():
+    """with update() as s: change s; it's written back when the block ends without an error."""
+    with _locked(fcntl.LOCK_EX):
+        state = _load()
+        yield state
+        _save(state)
+
+
+def reset():
+    with _locked(fcntl.LOCK_EX):
+        _save(default_state())
+        with open(CALLS, 'w'):
+            pass
+        os.chmod(CALLS, 0o666)
+
+
+def log(tool, **fields):
+    """Append one call record to calls.jsonl."""
+    _ensure_dir()
+    line = json.dumps({'time': round(time.time(), 3), 'tool': tool, **fields}) + '\n'
+    fd = os.open(CALLS, os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o666)
+    _share(fd)
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX)
+        os.write(fd, line.encode())
+    finally:
+        os.close(fd)
+
+
+def calls(tool=None):
+    try:
+        with open(CALLS) as f:
+            out = [json.loads(line) for line in f if line.strip()]
+    except OSError:
+        return []
+    return [c for c in out if tool is None or c['tool'] == tool]
+
+
+def steam_pid():
+    """The fake Steam client's pid if it's running, as devkit_utils.validate_steam_client checks."""
+    try:
+        with open(HOME + '/.steam/steam.pid') as f:
+            pid = int(f.read())
+        os.kill(pid, 0)
+        return pid
+    except (OSError, ValueError):
+        return None
diff --git a/tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakesteam.py b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakesteam.py
new file mode 100755
index 0000000..c76b586
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakesteam.py
@@ -0,0 +1,490 @@
+#!/usr/bin/env python3
+"""A stand-in for the Frame's Steam client, run as steamos by the supervisor.
+
+What it copies, and from where (BUILD_ID 20260922.6101926 unless noted):
+- The devkit IPC Valve's devkit-utils and the devkit service's hooks use:
+  ~/.steam/steam.pid (validate_steam_client), ~/.steam/steam.token, and
+  "devkit-1 steam://devkit-1/<token>/<command>?<query>" lines on the
+  ~/.steam/steam.pipe FIFO, answered by writing <response> or
+  <response>.error (with <response>.lock while writing), as
+  devkit_utils.wait_on_file_response describes. Commands: approve-ssh-key,
+  create-shortcut, run-game, list-shortcuts and delete-shortcut (all that
+  devkit-utils and the hooks send).
+- steam:// URLs that the `steam` wrapper forwards (rungameid, install, store).
+- The DevTools endpoint on 127.0.0.1:8080 with a SharedJSContext target
+  (docs/steam-games.md, docs/apks.md). Expressions run in node against
+  cef_shim.js.
+
+State lives in fakeframe_state (the "steam", "devkit_games", "launches" and
+"pairing_requests" keys). Anything not seen on a headset is marked "guess".
+"""
+import base64
+import hashlib
+import json
+import os
+import re
+import secrets
+import signal
+import struct
+import subprocess
+import sys
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import fakeframe_state as fs  # noqa: E402
+
+HOME = fs.HOME
+STEAM_DIR = HOME + '/.steam'
+PID_FILE, TOKEN_FILE, PIPE = (f'{STEAM_DIR}/steam.{n}' for n in ('pid', 'token', 'pipe'))
+CONSOLE_LOG = fs.STEAM_ROOT + '/logs/console_log.txt'  # guess: which file Steam logs devkit launches to
+DEVTOOLS_PORT = 8080
+TARGET_ID = 'F0CA11ED5EA4ED0000000000000000AB'
+GAME_LOGS = '/var/log/fakeframe'
+
+# The 403 text /register returned while Steam wasn't on "Pair new host"
+# (docs/ssh.md, verified 2026-09-26). approve-ssh-key passes the Steam
+# client's error file through as {"error": ...}, so this is what Steam writes.
+PAIRING_MODE_ERROR = 'please put the Steam client in pairing mode: Settings -> Developer -> Pair new host'
+# Guess: what Steam writes when the prompt is declined hasn't been seen.
+PAIRING_DENIED = 'the pairing request was denied on the device'
+# Steam refused create-shortcut for ids like "fc-smoke-exe" with this text, and
+# took the same program as "FCSmokeProbe" (headset smoke test, 2026-09-27,
+# BUILD_ID 20260922.6101926). Valve's client only allows ids matching
+# GAMEID_ALLOWED_PATTERN (devkit_client/gui2/gui2.py), so the fake checks that.
+INVALID_ARGUMENTS = 'missing/invalid arguments\n'
+GAMEID_ALLOWED = re.compile(r'[A-Za-z_][A-Za-z0-9_.]+')
+
+_lock = threading.RLock()   # one state change at a time within this process (the file lock covers others)
+TOKEN = secrets.token_hex(16)
+
+
+def console(line):
+    os.makedirs(os.path.dirname(CONSOLE_LOG), exist_ok=True)
+    with open(CONSOLE_LOG, 'a') as f:
+        f.write(time.strftime('[%Y-%m-%d %H:%M:%S] ') + line + '\n')
+
+
+def respond(path, text=None, error=None):
+    """Answer a devkit request the way devkit_utils.wait_on_file_response expects."""
+    lock = path + '.lock'
+    open(lock, 'w').close()
+    with open(path + '.error' if error is not None else path, 'w') as f:
+        f.write(error if error is not None else text)
+    os.unlink(lock)
+
+
+# ---- the Node side of the DevTools endpoint ----------------------------------
+
+class JS:
+    def __init__(self):
+        self.proc = None
+        self.next = 0
+
+    def _start(self):
+        shim = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'cef_shim.js')
+        self.proc = subprocess.Popen(['node', shim], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True)
+
+    def evaluate(self, expression, await_promise):
+        with _lock:
+            if not self.proc or self.proc.poll() is not None:
+                self._start()
+            self.next += 1
+            with fs.update() as state:
+                self.proc.stdin.write(json.dumps({'id': self.next, 'expression': expression,
+                                                  'awaitPromise': await_promise, 'steam': state['steam']}) + '\n')
+                self.proc.stdin.flush()
+                reply = json.loads(self.proc.stdout.readline())
+                state['steam'] = reply['steam']
+            return reply['result']
+
+
+JS_WORKER = JS()
+
+
+# ---- devkit commands ----------------------------------------------------------
+
+def shortcut_for(state, gameid):
+    return next((s for s in state['steam']['shortcuts'] if s.get('devkit_gameid') == gameid), None)
+
+
+def new_shortcut_id(steam):
+    steam['next_shortcut'] = steam.get('next_shortcut', 0) + 1
+    return (0x80000000 + ((steam['next_shortcut'] * 2654435761 & 0xFFFFFFFF) >> 1)) & 0xFFFFFFFF
+
+
+def read_json(path, default=None):
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (OSError, ValueError):
+        return default
+
+
+def cmd_approve_ssh_key(q):
+    with fs.update() as state:
+        sw = state['switches']
+        answer = sw['pairing_answer'] if sw['pairing_mode'] else 'not in pairing mode'
+        state['pairing_requests'].append({'time': time.time(), 'request': q.get('request', ''), 'answer': answer})
+    if answer == 'not in pairing mode':
+        respond(q['response'], error=PAIRING_MODE_ERROR)
+    elif answer == 'approve':
+        respond(q['response'], text='approved')   # guess: the hook only checks that the file appears
+    elif answer == 'deny':
+        respond(q['response'], error=PAIRING_DENIED)
+    # 'timeout': never answer; the hook gives up after 30 s.
+
+
+def cmd_create_shortcut(q):
+    gameid = q.get('gameid', '')
+    folder = q.get('directory') or fs.DEVKIT_GAMES
+    path = os.path.join(folder, gameid)
+    if not GAMEID_ALLOWED.fullmatch(gameid):
+        respond(q['response'], error=INVALID_ARGUMENTS)
+        return
+    if not os.path.isdir(path):
+        respond(q['response'], error=f'no devkit game folder {path}')   # guess: wording
+        return
+    argv = read_json(f'{folder}/{gameid}-argv.json', [])
+    settings = read_json(f'{folder}/{gameid}-settings.json', {})
+    env = read_json(f'{folder}/{gameid}-env.json', {})
+    with fs.update() as state:
+        steam = state['steam']
+        sc = shortcut_for(state, gameid)
+        if not sc:
+            sc = {'appid': new_shortcut_id(steam), 'name': gameid, 'exe': '', 'start_dir': path, 'icon': '',
+                  'launch_options': '', 'devkit_gameid': gameid}
+            steam['shortcuts'].append(sc)
+        sc['exe'] = argv[0] if argv else ''
+        tool = settings.get('compat_tool')
+        # Steam maps the title to the chosen compat tool (CompatToolMapping and
+        # compat_log.txt on the Frame, docs/sideloading.md, 2026-09-26).
+        if tool:
+            steam['compat_tools'][str(sc['appid'])] = tool
+        else:
+            steam['compat_tools'].pop(str(sc['appid']), None)
+        state['devkit_games'][gameid] = {'appid': sc['appid'], 'directory': path, 'argv': argv,
+                                         'settings': settings, 'env': env, 'registered': time.time()}
+    console(f'devkit create-shortcut: registered devkit game "{gameid}"')
+    respond(q['response'], text='')     # Steam's answer was empty on the Frame (2026-09-27)
+
+
+def cmd_list_shortcuts(q):
+    # The reply format devkit_utils.resolve.resolve_shortcuts asserts.
+    with fs.update() as state:
+        ids = sorted(state['devkit_games'])
+    respond(q['response'], text=json.dumps({'version': 2, 'gameids': ids}))
+
+
+def cmd_delete_shortcut(q):
+    gameid = q.get('gameid', '')
+    with fs.update() as state:
+        sc = shortcut_for(state, gameid)
+        state['devkit_games'].pop(gameid, None)
+        if sc:
+            state['steam']['shortcuts'].remove(sc)
+            state['steam']['compat_tools'].pop(str(sc['appid']), None)
+            # Remove also deleted the title's Proton prefix on the Frame (docs/sideloading.md).
+            subprocess.run(['rm', '-rf', f"{fs.STEAM_ROOT}/steamapps/compatdata/{sc['appid']}"])
+    console(f'devkit delete-shortcut: removed devkit game "{gameid}"')
+    respond(q['response'], text=f'deleted {gameid}\n')
+
+
+def cmd_run_game(q):
+    gameid = q.get('gameid', '')
+    with fs.update() as state:
+        game = state['devkit_games'].get(gameid)
+        tool = game and state['steam']['compat_tools'].get(str(game['appid']))
+        runtimes = state['runtimes']
+    if not game:
+        respond(q['response'], error=f'unknown devkit game "{gameid}"')   # guess: wording
+        return
+    target = game['argv'][0] if game['argv'] else ''
+    full = os.path.join(game['directory'], target.strip('"'))
+    record = {'kind': 'devkit', 'gameid': gameid, 'appid': game['appid'], 'tool': tool, 'time': time.time()}
+    if tool and not runtimes.get(tool, False):
+        # Seen for the x86-64 runtime (docs/sideloading.md, 2026-09-26): Steam
+        # logs this and the game doesn't start.
+        name = fs.RUNTIME_NAMES.get(tool, tool)
+        record.update(started=False, message=f'Tool {fs.RUNTIME_APPIDS.get(tool, 0)} "{name}" is found for '
+                                              f'appID {game["appid"]}, but is not installed')
+    elif tool and tool.startswith('proton'):
+        # How Steam ran a sideloaded .exe on the Frame (docs/sideloading.md).
+        prefix = f"{fs.STEAM_ROOT}/steamapps/compatdata/{game['appid']}/pfx"
+        os.makedirs(prefix, exist_ok=True)
+        record.update(started=True, command=f'proton waitforexitandrun "{full}"', prefix=prefix)
+    else:
+        # An aarch64 title ran natively, without SteamLinuxRuntime_4-arm64's
+        # _v2-entry-point prefix, even though Steam recorded the mapping
+        # (docs/sideloading.md, 2026-09-26). So does the fake, for real.
+        record.update(started=True, command=full)
+        record.update(execute(full, game['directory'], {**game.get('env', {})}, f"devkit-{gameid}"))
+    with fs.update() as state:
+        state['launches'].append(record)
+    console(record['message'] if not record['started'] else f'devkit run-game: started devkit game "{gameid}"')
+    respond(q['response'], text='OK\n')   # guess: steam-devkit-rpc only checks that it arrives
+
+
+DEVKIT = {'approve-ssh-key': cmd_approve_ssh_key, 'create-shortcut': cmd_create_shortcut,
+          'list-shortcuts': cmd_list_shortcuts, 'delete-shortcut': cmd_delete_shortcut,
+          'run-game': cmd_run_game}
+
+
+def execute(path, cwd, env, label):
+    """Start a program the way Steam would, and note its pid and exit status."""
+    os.makedirs(GAME_LOGS, exist_ok=True)
+    log = open(f'{GAME_LOGS}/{label}.log', 'ab')
+    try:
+        proc = subprocess.Popen([path], cwd=cwd if os.path.isdir(cwd) else HOME, env={**os.environ, **env},
+                                stdin=subprocess.DEVNULL, stdout=log, stderr=log, start_new_session=True)
+    except OSError as e:
+        return {'pid': None, 'exec_error': str(e)}
+    finally:
+        log.close()
+
+    def reap():
+        code = proc.wait()
+        with fs.update() as state:
+            for r in state['launches']:
+                if r.get('pid') == proc.pid and 'exit' not in r:
+                    r['exit'] = code
+    threading.Thread(target=reap, daemon=True).start()
+    return {'pid': proc.pid}
+
+
+# ---- steam:// URLs from the `steam` wrapper ----------------------------------
+
+def url_rungameid(gid):
+    gid = int(gid)
+    record = {'kind': 'rungameid', 'gameid': gid, 'time': time.time()}
+    if gid >= 1 << 32:
+        # A non-Steam shortcut: (appid << 32) | 0x02000000 (docs/apks.md).
+        appid = gid >> 32
+        with fs.update() as state:
+            sc = next((s for s in state['steam']['shortcuts'] if s['appid'] == appid), None)
+        if not sc:
+            record.update(started=False, message=f'no shortcut {appid}')
+        else:
+            # Steam sets STEAM_FOSSILIZE_DUMP_PATH for shortcut launches but not
+            # STEAM_COMPAT_SHADER_PATH (docs/apks.md, 2026-09-25).
+            env = {'SteamAppId': str(appid), 'SteamGameId': str(gid),
+                   'STEAM_FOSSILIZE_DUMP_PATH': f'{fs.STEAM_ROOT}/steamapps/shadercache/{appid}/fozpipelinesv6'}
+            record.update(appid=appid, started=True, command=sc['exe'])
+            record.update(execute(sc['exe'], sc.get('start_dir') or HOME, env, f'shortcut-{appid}'))
+    else:
+        with fs.update() as state:
+            app = next((a for a in state['steam']['apps'] if a['appid'] == gid), None)
+        record.update(appid=gid, started=bool(app and app['installed']),
+                      message=None if app and app['installed'] else 'not installed')
+    with fs.update() as state:
+        state['launches'].append(record)
+
+
+def url_install(appid):
+    appid = int(appid)
+    free = os.statvfs(HOME)
+    with fs.update() as state:
+        steam = state['steam']
+        app = next((a for a in steam['apps'] if a['appid'] == appid), None)
+        im = steam['install_manager']
+        if not app:
+            return                      # not owned: Steam shows a store or license dialog, state stays 0
+        im.update(currentAppID=appid, nDiskSpaceRequired=app['size'],
+                  nDiskSpaceAvailable=free.f_bavail * free.f_frsize, eInstallState=app.get('wizard', 14))
+        if im['eInstallState'] == 14:
+            steam['download'] = {'update_appid': appid, 'update_state': 'Downloading', 'paused': False,
+                                 'update_is_install': True, 'overall_percent_complete': 0,
+                                 'overall_estimated_time_remaining_sec': 7,
+                                 'update_network_bytes_per_second': 9500000}
+
+
+def url_store(appid):
+    # A store page showed up in the DevTools page list (docs/steam-games.md).
+    names = {1145360: 'Hades'}
+    with fs.update() as state:
+        state['steam']['pages'].append({'title': f"{names.get(int(appid), 'App ' + appid)} on Steam",
+                                        'url': f'https://store.steampowered.com/app/{appid}/'})
+
+
+URLS = [(re.compile(r'steam://rungameid/(\d+)$'), url_rungameid),
+        (re.compile(r'steam://install/(\d+)$'), url_install),
+        (re.compile(r'steam://store/(\d+)$'), url_store)]
+
+
+def handle_line(line):
+    line = line.strip()
+    if not line:
+        return
+    fs.log('steam.pipe', line=line)
+    try:
+        if line.startswith('devkit-1 '):
+            m = re.fullmatch(r'steam://devkit-1/([^/]*)/([^?]*)\??(.*)', line.split(' ', 1)[1])
+            if not m or m[1] != TOKEN:
+                console('devkit-1: rejected a command with a bad token')
+                return
+            cmd = m[2].rstrip('/')               # steam-devkit-rpc sends "run-game/?..."
+            q = {k: v[0] for k, v in parse_qs(m[3], keep_blank_values=True).items()}
+            handler = DEVKIT.get(cmd)
+            if not handler:
+                console(f'devkit-1: unknown command {cmd}')
+                if 'response' in q:
+                    respond(q['response'], error=f'unknown command {cmd}')
+                return
+            handler(q)
+            return
+        for pat, fn in URLS:
+            m = pat.match(line.split()[-1])
+            if m:
+                fn(*m.groups())
+                return
+        console(f'ignored: {line}')
+    except Exception as e:  # keep reading the pipe whatever one command did
+        console(f'error handling {line!r}: {type(e).__name__}: {e}')
+
+
+def read_pipe():
+    # O_RDWR: there is always a writer, so reads never hit EOF between clients.
+    fd = os.open(PIPE, os.O_RDWR)
+    with os.fdopen(fd, 'rb', buffering=0) as f:
+        buf = b''
+        while True:
+            chunk = f.read(4096)
+            buf += chunk
+            while b'\n' in buf:
+                line, buf = buf.split(b'\n', 1)
+                threading.Thread(target=handle_line, args=(line.decode('utf-8', 'replace'),), daemon=True).start()
+
+
+# ---- DevTools HTTP + WebSocket -------------------------------------------------
+
+def targets():
+    base = {'type': 'page', 'description': '', 'faviconUrl': ''}
+    out = [{**base, 'id': TARGET_ID, 'title': 'SharedJSContext',
+            'url': 'https://steamloopback.host/index.html',
+            'devtoolsFrontendUrl': f'/devtools/inspector.html?ws=127.0.0.1:{DEVTOOLS_PORT}/devtools/page/{TARGET_ID}',
+            'webSocketDebuggerUrl': f'ws://127.0.0.1:{DEVTOOLS_PORT}/devtools/page/{TARGET_ID}'}]
+    for i, p in enumerate(fs.read()['steam'].get('pages', [])):
+        tid = f'{i + 1:032X}'
+        out.append({**base, 'id': tid, 'title': p['title'], 'url': p['url'],
+                    'webSocketDebuggerUrl': f'ws://127.0.0.1:{DEVTOOLS_PORT}/devtools/page/{tid}'})
+    return out
+
+
+class DevTools(BaseHTTPRequestHandler):
+    protocol_version = 'HTTP/1.1'
+
+    def log_message(self, fmt, *args):
+        pass
+
+    def do_GET(self):
+        path = self.path.split('?')[0].rstrip('/')
+        if self.headers.get('Upgrade', '').lower() == 'websocket':
+            if path != f'/devtools/page/{TARGET_ID}':
+                self.send_error(404)
+                return
+            self.websocket()
+            return
+        if path in ('/json', '/json/list'):
+            body = json.dumps(targets(), indent=2).encode()
+        elif path == '/json/version':
+            body = json.dumps({'Browser': 'Chrome/126.0.6478.183', 'Protocol-Version': '1.3',
+                               'User-Agent': 'Valve Steam Client (fakeframe)'}).encode()
+        else:
+            self.send_error(404)
+            return
+        self.send_response(200)
+        self.send_header('Content-Type', 'application/json; charset=UTF-8')
+        self.send_header('Content-Length', str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def websocket(self):
+        key = self.headers.get('Sec-WebSocket-Key', '')
+        accept = base64.b64encode(hashlib.sha1((key + '258EAFA5-E914-47DA-95CA-C5AB0DC85B11').encode()).digest())
+        self.wfile.write(b'HTTP/1.1 101 WebSocket Protocol Handshake\r\nUpgrade: WebSocket\r\n'
+                         b'Connection: Upgrade\r\nSec-WebSocket-Accept: ' + accept + b'\r\n\r\n')
+        self.wfile.flush()
+        self.close_connection = True
+        try:
+            while True:
+                op, data = self.read_frame()
+                if op == 8:
+                    return
+                if op == 9:
+                    self.send_frame(data, 10)
+                    continue
+                if op != 1:
+                    continue
+                msg = json.loads(data)
+                reply = {'id': msg.get('id')}
+                if msg.get('method') == 'Runtime.evaluate':
+                    params = msg.get('params') or {}
+                    reply['result'] = JS_WORKER.evaluate(str(params.get('expression', '')),
+                                                         bool(params.get('awaitPromise')))
+                else:
+                    reply['error'] = {'code': -32601, 'message': f"'{msg.get('method')}' wasn't found"}
+                self.send_frame(json.dumps(reply).encode(), 1)
+        except (EOFError, OSError, ValueError):
+            return
+
+    def read_exact(self, n):
+        data = self.rfile.read(n)
+        if len(data) < n:
+            raise EOFError
+        return data
+
+    def read_frame(self):
+        b0, b1 = self.read_exact(2)
+        n = b1 & 0x7F
+        if n == 126:
+            n = struct.unpack('>H', self.read_exact(2))[0]
+        elif n == 127:
+            n = struct.unpack('>Q', self.read_exact(8))[0]
+        mask = self.read_exact(4) if b1 & 0x80 else None
+        data = self.read_exact(n)
+        if mask:
+            data = bytes(b ^ mask[i % 4] for i, b in enumerate(data))
+        return b0 & 0x0F, data
+
+    def send_frame(self, data, op):
+        n = len(data)
+        head = bytes([0x80 | op]) + (bytes([n]) if n < 126 else
+                                     bytes([126]) + struct.pack('>H', n) if n < 1 << 16 else
+                                     bytes([127]) + struct.pack('>Q', n))
+        self.wfile.write(head + data)
+        self.wfile.flush()
+
+
+def main():
+    os.makedirs(STEAM_DIR, exist_ok=True)
+    if not os.path.exists(PIPE):
+        os.mkfifo(PIPE, 0o600)
+    with open(TOKEN_FILE, 'w') as f:
+        f.write(TOKEN)
+    with open(PID_FILE, 'w') as f:
+        f.write(str(os.getpid()))
+
+    def stop(*_):
+        # Guess: whether Steam removes steam.pid on exit. Either way
+        # validate_steam_client then says Steam isn't running.
+        try:
+            os.unlink(PID_FILE)
+        except OSError:
+            pass
+        if JS_WORKER.proc:
+            JS_WORKER.proc.kill()
+        os._exit(0)
+    signal.signal(signal.SIGTERM, stop)
+    signal.signal(signal.SIGINT, stop)
+
+    httpd = ThreadingHTTPServer(('127.0.0.1', DEVTOOLS_PORT), DevTools)
+    httpd.daemon_threads = True
+    threading.Thread(target=httpd.serve_forever, daemon=True).start()
+    console('fakesteam: started (-cef-enable-debugging on 127.0.0.1:8080)')
+    read_pipe()
+
+
+if __name__ == '__main__':
+    main()
diff --git a/tests/fakeframe/rootfs/usr/local/lib/fakeframe/init.py b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/init.py
new file mode 100755
index 0000000..14593c0
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/init.py
@@ -0,0 +1,468 @@
+#!/usr/bin/env python3
+"""The fake Frame's supervisor, run as root under docker's init.
+
+It starts and stops sshd, Valve's steamos-devkit-service (as steamos),
+fakesteam (as steamos) and a few named placeholder processes the status page
+looks for, following the switches in the state file. It also serves the
+control port (9999) that fakeframe-ctl and the e2e tests use, so a test can
+flip a fault switch even while SSH is down.
+
+Control: GET /state, GET /calls, GET /ping, POST /ctl {"args": ["pairing", "on"]}.
+See `fakeframe-ctl help` for the commands.
+"""
+import glob
+import json
+import os
+import pwd
+import shutil
+import socket
+import subprocess
+import sys
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import fakeframe_state as fs  # noqa: E402
+
+LIB = os.path.dirname(os.path.abspath(__file__))
+USER = 'steamos'
+PW = pwd.getpwnam(USER)
+HOME = fs.HOME
+KEYS = '/keys'                                  # shared with the host container
+HARNESS_KEY = KEYS + '/id_ed25519_frame'
+AUTH_KEYS = HOME + '/.ssh/authorized_keys'
+BALLAST = fs.DEVKIT_GAMES + '/.fakeframe-ballast'
+# Written here; compose mounts the same volumes over /sys/class/power_supply and /sys/class/thermal.
+POWER = '/var/lib/fakeframe/sys/power_supply'
+THERMAL = '/var/lib/fakeframe/sys/thermal'
+CONTROL_PORT = 9999
+LOGS = '/var/log/fakeframe'
+USAGE = """fakeframe-ctl COMMAND
+  pairing on|off              Steam's "Pair new host" screen open or not
+  answer approve|deny|timeout how the pairing prompt is answered
+  steam on|off                Steam client running (steam.pid, pipe, DevTools on 8080)
+  sleep on|off                headset asleep: 22 and 32000 accept but never answer
+  sshd on|off                 sshd running (off: connection refused)
+  devkit-service on|off       steamos-devkit-service on 32000
+  disk-full on|off            fill the small ~/devkit-game filesystem
+  runtime NAME installed|missing   NAME: proton-experimental, proton-stable,
+                              SteamLinuxRuntime_4-arm64, SteamLinuxRuntime_4, lepton
+  battery KEY=VALUE...        e.g. capacity=15 status=Discharging current_now=-900000
+  keys harness|none           authorized_keys: only the harness key, or empty
+  authorized-keys             what ~/.ssh/authorized_keys holds now
+  reset                       default state, nothing installed, harness key only
+  state | calls [TOOL] | ping"""
+
+_lock = threading.RLock()
+_procs = {}
+_blackhole = {'socks': [], 'conns': []}
+
+
+def log(msg):
+    print(time.strftime('%H:%M:%S ') + msg, flush=True)
+
+
+def as_user():
+    env = {'HOME': HOME, 'USER': USER, 'LOGNAME': USER, 'SHELL': '/bin/bash',
+           'PATH': '/usr/local/bin:/usr/bin:/bin', 'XDG_RUNTIME_DIR': f'/run/user/{PW.pw_uid}',
+           'LANG': 'C.UTF-8'}
+    return {'user': PW.pw_uid, 'group': PW.pw_gid, 'extra_groups': [], 'env': env, 'cwd': HOME}
+
+
+def chown(path):
+    os.chown(path, PW.pw_uid, PW.pw_gid)
+
+
+# ---- processes ------------------------------------------------------------------
+
+def spawn(name, argv, user=True, env=None):
+    os.makedirs(LOGS, exist_ok=True)
+    out = open(f'{LOGS}/{name}.log', 'ab')
+    kw = as_user() if user else {'env': dict(os.environ)}
+    kw['env'].update(env or {})
+    _procs[name] = subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=out, stderr=out,
+                                    start_new_session=True, **kw)
+    out.close()
+    log(f'started {name} (pid {_procs[name].pid})')
+
+
+def stop(name, sig=15):
+    p = _procs.pop(name, None)
+    if p and p.poll() is None:
+        p.send_signal(sig)
+        try:
+            p.wait(5)
+        except subprocess.TimeoutExpired:
+            p.kill()
+            p.wait()
+        log(f'stopped {name}')
+
+
+def running(name):
+    p = _procs.get(name)
+    return bool(p and p.poll() is None)
+
+
+def kill_ssh_sessions():
+    """Drop every SSH connection, as losing Wi-Fi does."""
+    for comm_file in glob.glob('/proc/[0-9]*/comm'):
+        try:
+            with open(comm_file) as f:
+                comm = f.read().strip()
+            if comm.startswith('sshd'):
+                os.kill(int(comm_file.split('/')[2]), 9)
+        except (OSError, ValueError):
+            pass
+
+
+class Blackhole:
+    """Accept on a port and never answer, so ssh waits and times out. An unreachable
+    Frame times out rather than refusing (seen over Tailscale on 2026-09-27);
+    a closed port would fail at once, which hides timeout bugs."""
+
+    @staticmethod
+    def start(port):
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        s.bind(('0.0.0.0', port))
+        s.listen(64)
+        _blackhole['socks'].append(s)
+
+        def accept():
+            while True:
+                try:
+                    c, _ = s.accept()
+                except OSError:
+                    return
+                _blackhole['conns'].append(c)
+        threading.Thread(target=accept, daemon=True).start()
+
+    @staticmethod
+    def stop():
+        for s in _blackhole['socks'] + _blackhole['conns']:
+            try:
+                s.shutdown(socket.SHUT_RDWR)
+            except OSError:
+                pass
+            s.close()
+        _blackhole['socks'].clear()
+        _blackhole['conns'].clear()
+
+
+def reconcile():
+    """Make the running processes match the switches."""
+    with _lock:
+        sw = fs.read()['switches']
+        asleep = sw['asleep']
+        if asleep and not _blackhole['socks']:
+            stop('sshd')
+            stop('devkit-service')
+            kill_ssh_sessions()
+            Blackhole.start(22)
+            Blackhole.start(32000)
+        if not asleep and _blackhole['socks']:
+            Blackhole.stop()
+        want = {'sshd': sw['sshd'] and not asleep, 'devkit-service': sw['devkit_service'] and not asleep,
+                'steam': sw['steam'], 'vrserver': True, 'plasmashell': True}
+        for name, on in want.items():
+            if on and not running(name):
+                start(name)
+            elif not on and running(name):
+                stop(name)
+
+
+def start(name):
+    if name == 'sshd':
+        spawn('sshd', ['/usr/bin/sshd', '-D', '-e'], user=False)
+    elif name == 'devkit-service':
+        # Valve's service, unmodified, with a stand-in dbus module (no systemd-resolved here).
+        spawn('devkit-service', ['python3', '/usr/lib/steamos-devkit/steamos-devkit-service.py'],
+              env={'PYTHONPATH': f'{LIB}/pystubs'})
+    elif name == 'steam':
+        spawn('steam', ['python3', f'{LIB}/fakesteam.py'])
+    else:
+        # frame_status.py looks for these by process name (vrserver: SteamVR,
+        # plasmashell: the headset desktop, which /api/clipboard also needs).
+        spawn(name, [f'{LIB}/bin/{name}', 'infinity'],
+              env={'DBUS_SESSION_BUS_ADDRESS': f'unix:path=/run/user/{PW.pw_uid}/bus'})
+
+
+# ---- the device's files -----------------------------------------------------------
+
+def write(path, text, owner=True):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, 'w') as f:
+        f.write(text)
+    if owner:
+        chown(path)
+
+
+def sysfs(state):
+    """Battery, charger and thermal zones, in the files frame_status.py reads.
+
+    /sys is read-only in a container, so compose mounts a volume over each of
+    the two folders and again here, where it can be written
+    (tests/fakeframe/compose.yaml); without those this does nothing.
+    """
+    b = state['battery']
+    if not os.path.isdir(POWER) or not os.path.isdir(THERMAL):
+        log('no fake /sys: see the volumes in tests/fakeframe/compose.yaml')
+        return
+    try:
+        for d in glob.glob(POWER + '/*') + glob.glob(THERMAL + '/thermal_zone*'):
+            shutil.rmtree(d, ignore_errors=True)
+        bat = POWER + '/max1720x_battery'   # the fuel gauge frame_status.py was written against
+        for k in ('capacity', 'status', 'voltage_now', 'current_now', 'time_to_full_now', 'temp', 'health'):
+            write(f'{bat}/{k}', f'{b[k]}\n', owner=False)
+        write(f'{bat}/type', 'Battery\n', owner=False)
+        c = b.get('charger') or {}
+        usb = POWER + '/usb'
+        write(f'{usb}/type', 'USB\n', owner=False)
+        write(f'{usb}/online', f"{c.get('online', 0)}\n", owner=False)
+        for k in ('usb_type', 'voltage_now', 'current_now'):
+            if k in c:
+                write(f'{usb}/{k}', f'{c[k]}\n', owner=False)
+        for i, t in enumerate(state['thermal_mc']):
+            write(f'{THERMAL}/thermal_zone{i}/temp', f'{t}\n', owner=False)
+    except OSError as e:
+        log(f'no fake /sys ({e}); see the volumes in tests/fakeframe/compose.yaml')
+
+
+def runtimes(state):
+    """Installed compat tools as Steam app manifests, and the Lepton launcher itself."""
+    apps = fs.STEAM_ROOT + '/steamapps'
+    for alias, installed in state['runtimes'].items():
+        acf = f'{apps}/appmanifest_{fs.RUNTIME_APPIDS[alias]}.acf'
+        if installed:
+            write(acf, '"AppState"\n{\n\t"appid"\t\t"%d"\n\t"name"\t\t"%s"\n\t"SizeOnDisk"\t\t"%d"\n}\n'
+                  % (fs.RUNTIME_APPIDS[alias], fs.RUNTIME_NAMES[alias], 900000000))
+        elif os.path.exists(acf):
+            os.unlink(acf)
+    if state['runtimes'].get('lepton'):
+        os.makedirs(os.path.dirname(fs.LEPTON), exist_ok=True)
+        shutil.copy(f'{LIB}/lepton.py', fs.LEPTON)
+        os.chmod(fs.LEPTON, 0o755)
+    elif os.path.exists(fs.LEPTON):
+        os.unlink(fs.LEPTON)
+    for app in state['steam']['apps']:
+        acf = f"{apps}/appmanifest_{app['appid']}.acf"
+        if app['installed']:
+            write(acf, '"AppState"\n{\n\t"appid"\t\t"%d"\n\t"name"\t\t"%s"\n\t"SizeOnDisk"\t\t"%d"\n}\n'
+                  % (app['appid'], app['display_name'], app['size']))
+    subprocess.run(['chown', '-R', f'{USER}:{USER}', fs.STEAM_ROOT])
+
+
+def disk_full(on):
+    if on:
+        if os.path.ismount(fs.DEVKIT_GAMES) is False:
+            raise ValueError(f'disk-full needs {fs.DEVKIT_GAMES} to be its own small filesystem (compose tmpfs)')
+        st = os.statvfs(fs.DEVKIT_GAMES)
+        size = max(0, st.f_bavail * st.f_frsize - 64 * 1024)
+        fd = os.open(BALLAST, os.O_WRONLY | os.O_CREAT, 0o600)
+        try:
+            os.posix_fallocate(fd, 0, size)
+        finally:
+            os.close(fd)
+    elif os.path.exists(BALLAST):
+        os.unlink(BALLAST)
+
+
+def set_keys(which):
+    os.makedirs(os.path.dirname(AUTH_KEYS), mode=0o700, exist_ok=True)
+    chown(os.path.dirname(AUTH_KEYS))
+    text = ''
+    if which == 'harness':
+        with open(HARNESS_KEY + '.pub') as f:
+            text = f.read()
+    write(AUTH_KEYS, text)
+    os.chmod(AUTH_KEYS, 0o600)
+
+
+def harness_key():
+    """The key the host container logs in with, shared through the /keys volume."""
+    os.makedirs(KEYS, exist_ok=True)
+    if not os.path.exists(HARNESS_KEY):
+        subprocess.run(['ssh-keygen', '-q', '-t', 'ed25519', '-N', '', '-C', 'fakeframe-harness',
+                        '-f', HARNESS_KEY], check=True)
+    os.chmod(HARNESS_KEY, 0o644)        # the host container copies it into its own ~/.ssh with 0600
+
+
+def clean_home():
+    """Everything Frame Control or a test put on the "headset"."""
+    for c in list(fs.read()['lepton'].values()):
+        try:
+            os.kill(c['pid'], 15)
+        except (OSError, KeyError, TypeError):
+            pass
+    for pattern in (fs.DEVKIT_GAMES + '/*', fs.DEVKIT_GAMES + '/.[!.]*', HOME + '/devkit-utils',
+                    HOME + '/.devkit-utils.frame-control', HOME + '/Applications', HOME + '/Downloads/*',
+                    fs.STEAM_ROOT + '/steamapps/compatdata', fs.STEAM_ROOT + '/steamapps/shadercache',
+                    fs.STEAM_ROOT + '/logs', '/var/log/fakeframe/devkit-*', '/var/log/fakeframe/shortcut-*'):
+        for p in glob.glob(pattern):
+            subprocess.run(['rm', '-rf', p])
+    os.makedirs(HOME + '/Downloads', exist_ok=True)
+    chown(HOME + '/Downloads')
+    chown(fs.DEVKIT_GAMES)
+
+
+def apply_files():
+    state = fs.read()
+    sysfs(state)
+    runtimes(state)
+
+
+def reset():
+    with _lock:
+        stop('steam')
+        clean_home()
+        fs.reset()
+        env_switches()
+        set_keys('harness')
+        disk_full(False)
+        apply_files()
+        reconcile()
+
+
+def env_switches():
+    """FAKEFRAME_PAIRING_MODE=1 and the like set a switch's value at start."""
+    with fs.update() as s:
+        for k in s['switches']:
+            v = os.environ.get('FAKEFRAME_' + k.upper())
+            if v is not None:
+                s['switches'][k] = v if k == 'pairing_answer' else v in ('1', 'on', 'true', 'yes')
+
+
+# ---- commands ----------------------------------------------------------------------
+
+ON_OFF = {'on': True, 'off': False}
+SWITCH = {'pairing': 'pairing_mode', 'steam': 'steam', 'sleep': 'asleep', 'sshd': 'sshd',
+          'devkit-service': 'devkit_service'}
+
+
+def command(args):
+    if not args or args[0] == 'help':
+        return {'usage': USAGE}
+    cmd, rest = args[0], args[1:]
+    if cmd == 'state':
+        return fs.read()
+    if cmd == 'calls':
+        return fs.calls(rest[0] if rest else None)
+    if cmd == 'ping':
+        return ping()
+    if cmd == 'reset':
+        reset()
+        return {'ok': True}
+    if cmd in SWITCH and len(rest) == 1 and rest[0] in ON_OFF:
+        with fs.update() as s:
+            s['switches'][SWITCH[cmd]] = ON_OFF[rest[0]]
+        reconcile()
+        return {'ok': True, SWITCH[cmd]: ON_OFF[rest[0]]}
+    if cmd == 'answer' and rest and rest[0] in ('approve', 'deny', 'timeout'):
+        with fs.update() as s:
+            s['switches']['pairing_answer'] = rest[0]
+        return {'ok': True}
+    if cmd == 'disk-full' and len(rest) == 1 and rest[0] in ON_OFF:
+        with _lock:
+            disk_full(ON_OFF[rest[0]])
+            with fs.update() as s:
+                s['switches']['disk_full'] = ON_OFF[rest[0]]
+        return {'ok': True}
+    if cmd == 'runtime' and len(rest) == 2 and rest[1] in ('installed', 'missing'):
+        with fs.update() as s:
+            if rest[0] not in s['runtimes']:
+                raise ValueError(f'unknown runtime {rest[0]}')
+            s['runtimes'][rest[0]] = rest[1] == 'installed'
+        apply_files()
+        return {'ok': True}
+    if cmd == 'battery' and rest:
+        with fs.update() as s:
+            for kv in rest:
+                k, _, v = kv.partition('=')
+                if k not in s['battery'] or k == 'charger':
+                    raise ValueError(f'unknown battery field {k}')
+                s['battery'][k] = int(v) if v.lstrip('-').isdigit() else v
+        apply_files()
+        return {'ok': True}
+    if cmd == 'keys' and rest and rest[0] in ('harness', 'none'):
+        set_keys(rest[0])
+        return {'ok': True}
+    if cmd == 'authorized-keys':
+        with open(AUTH_KEYS) as f:
+            return {'text': f.read()}
+    raise ValueError(f'unknown command {" ".join(args)!r}; try help')
+
+
+def port_open(port):
+    try:
+        with socket.create_connection(('127.0.0.1', port), timeout=1):
+            return True
+    except OSError:
+        return False
+
+
+def ping():
+    sw = fs.read()['switches']
+    checks = {}
+    if sw['sshd'] and not sw['asleep']:
+        checks['sshd'] = port_open(22)
+    if sw['devkit_service'] and not sw['asleep']:
+        checks['devkit_service'] = port_open(32000)
+    if sw['steam']:
+        checks['devtools'] = port_open(8080) and fs.steam_pid() is not None
+    return {'ok': all(checks.values()), 'checks': checks}
+
+
+class Control(BaseHTTPRequestHandler):
+    def log_message(self, fmt, *args):
+        pass
+
+    def reply(self, obj, status=200):
+        body = json.dumps(obj).encode()
+        self.send_response(status)
+        self.send_header('Content-Type', 'application/json')
+        self.send_header('Content-Length', str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        path, _, query = self.path.partition('?')
+        args = {'/state': ['state'], '/calls': ['calls'] + ([query] if query else []), '/ping': ['ping']}.get(path)
+        if not args:
+            self.reply({'error': 'not found'}, 404)
+            return
+        self.reply(command(args))
+
+    def do_POST(self):
+        if self.path != '/ctl':
+            self.reply({'error': 'not found'}, 404)
+            return
+        try:
+            body = json.loads(self.rfile.read(int(self.headers.get('Content-Length') or 0)) or b'{}')
+            self.reply(command([str(a) for a in body.get('args', [])]))
+        except (ValueError, OSError) as e:
+            self.reply({'error': str(e)}, 400)
+
+
+def main():
+    os.umask(0o022)
+    harness_key()
+    os.makedirs(fs.DIR, mode=0o777, exist_ok=True)
+    os.chmod(fs.DIR, 0o777)
+    os.makedirs(f'/run/user/{PW.pw_uid}', exist_ok=True)
+    chown(f'/run/user/{PW.pw_uid}')
+    reset()
+    httpd = ThreadingHTTPServer(('0.0.0.0', CONTROL_PORT), Control)
+    httpd.daemon_threads = True
+    threading.Thread(target=httpd.serve_forever, daemon=True).start()
+    log(f'fake Frame up; control on :{CONTROL_PORT}')
+    while True:                         # restart anything that died unasked, as systemd would
+        time.sleep(1)
+        try:
+            reconcile()
+        except Exception as e:  # keep supervising
+            log(f'reconcile: {type(e).__name__}: {e}')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/tests/fakeframe/rootfs/usr/local/lib/fakeframe/lepton.py b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/lepton.py
new file mode 100755
index 0000000..ccaa3d5
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/lepton.py
@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Stand-in for Lepton's launcher (~/.local/share/Steam/steamapps/common/Lepton/lepton).
+
+frame/android/lepton-app.sh runs it as `lepton waitforexitandrun -- APK` with
+the Steam compat variables set. Like the real one (docs/apks.md, verified
+2026-09-25, BUILD_ID 20260922.6101926) it:
+- dies with "unbound variable" when STEAM_COMPAT_SHADER_PATH isn't set;
+- needs STEAM_COMPAT_DATA_PATH under ~/.local/share/Steam (only that tree is
+  mounted in the container; elsewhere the app crashes with ENOENT);
+- runs a "steamlaunch" container named lepton-steamlaunch-<SteamAppId> when
+  SteamAppId is set, else Lepton Development (lepton-dev);
+- opens ADB on 0.0.0.0: 5555 for Lepton Development, the next free port for
+  each own instance (README security notes, 2026-09-25);
+- shows a flat window only when lepton-show-flatscreen sits next to the APK.
+There's no Android inside: it records the launch and holds the port until
+`podman stop` (the podman stub) ends it.
+"""
+import json
+import os
+import signal
+import socket
+import sys
+import time
+
+sys.path.insert(0, '/usr/local/lib/fakeframe')
+import fakeframe_state as fs  # noqa: E402
+
+ENV = ('SteamAppId', 'STEAM_COMPAT_INSTALL_PATH', 'STEAM_COMPAT_DATA_PATH', 'STEAM_COMPAT_SHADER_PATH',
+       'STEAM_FOSSILIZE_DUMP_PATH', 'IS_PARENT')
+
+
+def main():
+    args = sys.argv[1:]
+    env = {k: os.environ.get(k) for k in ENV}
+    fs.log('lepton', args=args, env=env)
+    for k in ('STEAM_COMPAT_SHADER_PATH', 'STEAM_COMPAT_DATA_PATH', 'STEAM_COMPAT_INSTALL_PATH'):
+        if not env[k]:
+            sys.exit(f'{sys.argv[0]}: line 1: {k}: unbound variable')
+    if not os.path.realpath(env['STEAM_COMPAT_DATA_PATH']).startswith(fs.STEAM_ROOT + '/'):
+        sys.exit('ENOENT: STEAM_COMPAT_DATA_PATH is outside ~/.local/share/Steam, which is all the container sees')
+    apk = args[-1] if args else ''
+    if not apk.endswith('.apk') or not os.path.isfile(apk):
+        sys.exit(f'lepton: no APK at {apk!r}')
+    steamlaunch = bool(env['SteamAppId'])
+    name = f"lepton-steamlaunch-{env['SteamAppId']}" if steamlaunch else 'lepton-dev'
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    with fs.update() as state:
+        if name in state['lepton']:
+            sys.exit(f'lepton: {name} is already running')
+        used = {c['port'] for c in state['lepton'].values()}
+        for port in ([5555] if not steamlaunch else range(5556, 5600)):
+            if port in used:
+                continue
+            try:
+                sock.bind(('0.0.0.0', port))
+                break
+            except OSError:
+                continue
+        else:
+            sys.exit('lepton: no free ADB port')
+        sock.listen(8)
+        os.makedirs(os.path.join(env['STEAM_COMPAT_DATA_PATH'], 'internal'), exist_ok=True)
+        state['lepton'][name] = {'port': port, 'pid': os.getpid(), 'apk': apk, 'started': time.time(),
+                                 'flatscreen': os.path.exists(os.path.join(os.path.dirname(apk),
+                                                                           'lepton-show-flatscreen'))}
+
+    def stop(*_):
+        with fs.update() as state:
+            state['lepton'].pop(name, None)
+        fs.log('lepton', stopped=name)
+        os._exit(0)
+    signal.signal(signal.SIGTERM, stop)
+    signal.signal(signal.SIGINT, stop)
+    print(json.dumps({'container': name, 'adb_port': port}), flush=True)
+    while True:
+        conn, _ = sock.accept()     # nothing speaks ADB here; just close
+        conn.close()
+
+
+if __name__ == '__main__':
+    main()
diff --git a/tests/fakeframe/rootfs/usr/local/lib/fakeframe/pystubs/dbus/__init__.py b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/pystubs/dbus/__init__.py
new file mode 100644
index 0000000..050d3b1
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/pystubs/dbus/__init__.py
@@ -0,0 +1,50 @@
+"""Stand-in for dbus-python, just enough for Valve's steamos-devkit-service.
+
+The service advertises _steamos-devkit._tcp through systemd-resolved's
+RegisterService over the system bus (on the Frame, `frame` answered mDNS,
+docs/ssh.md, 2026-09-26). A container has no system bus or resolved, so
+this records the call in the fake Frame's log instead.
+"""
+import sys
+
+from . import exceptions  # noqa: F401
+
+sys.path.insert(0, '/usr/local/lib/fakeframe')
+import fakeframe_state as fs  # noqa: E402
+
+
+class Array(list):
+    def __init__(self, items=(), signature=None):
+        super().__init__(items)
+
+
+class Dictionary(dict):
+    def __init__(self, items=(), signature=None):
+        super().__init__(items)
+
+
+def UInt16(v):
+    return int(v)
+
+
+def _plain(v):
+    if isinstance(v, dict):
+        return {k: _plain(x) for k, x in v.items()}
+    if isinstance(v, list):
+        if all(isinstance(x, int) for x in v):
+            return bytes(v).decode('utf-8', 'replace')
+        return [_plain(x) for x in v]
+    return v
+
+
+class _Object:
+    def get_dbus_method(self, name, interface=None):
+        def call(*args):
+            fs.log('resolve1', method=name, args=_plain(list(args)))
+            return f'/org/freedesktop/resolve1/dnssd/{args[0]}' if name == 'RegisterService' else None
+        return call
+
+
+class SystemBus:
+    def get_object(self, bus_name, path):
+        return _Object()
diff --git a/tests/fakeframe/rootfs/usr/local/lib/fakeframe/pystubs/dbus/exceptions.py b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/pystubs/dbus/exceptions.py
new file mode 100644
index 0000000..8e06c27
--- /dev/null
+++ b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/pystubs/dbus/exceptions.py
@@ -0,0 +1,3 @@
+class DBusException(Exception):
+    def get_dbus_name(self):
+        return None
diff --git a/tests/fakeframe/steamos-devkit-service/LICENSE b/tests/fakeframe/steamos-devkit-service/LICENSE
new file mode 100644
index 0000000..63ab7cd
--- /dev/null
+++ b/tests/fakeframe/steamos-devkit-service/LICENSE
@@ -0,0 +1,504 @@
+                  GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 2.1, February 1999
+
+ Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+ 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+[This is the first released version of the Lesser GPL.  It also counts
+ as the successor of the GNU Library Public License, version 2, hence
+ the version number 2.1.]
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software--to make sure the software is free for all its users.
+
+  This license, the Lesser General Public License, applies to some
+specially designated software packages--typically libraries--of the
+Free Software Foundation and other authors who decide to use it.  You
+can use it too, but we suggest you first think carefully about whether
+this license or the ordinary General Public License is the better
+strategy to use in any particular case, based on the explanations below.
+
+  When we speak of free software, we are referring to freedom of use,
+not price.  Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of
+it in new free programs; and that you are informed that you can do
+these things.
+
+  To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights.  These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.
+
+  For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+
+  We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.
+
+  To protect each distributor, we want to make it very clear that
+there is no warranty for the free library.  Also, if the library is
+modified by someone else and passed on, the recipients should know
+that what they have is not the original version, so that the original
+author's reputation will not be affected by problems that might be
+introduced by others.
+
+  Finally, software patents pose a constant threat to the existence of
+any free program.  We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder.  Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.
+
+  Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License.  This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and
+is quite different from the ordinary General Public License.  We use
+this license for certain libraries in order to permit linking those
+libraries into non-free programs.
+
+  When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library.  The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom.  The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.
+
+  We call this license the "Lesser" General Public License because it
+does Less to protect the user's freedom than the ordinary General
+Public License.  It also provides other free software developers Less
+of an advantage over competing non-free programs.  These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries.  However, the Lesser license provides advantages in certain
+special circumstances.
+
+  For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it becomes
+a de-facto standard.  To achieve this, non-free programs must be
+allowed to use the library.  A more frequent case is that a free
+library does the same job as widely used non-free libraries.  In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.
+
+  In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of
+free software.  For example, permission to use the GNU C Library in
+non-free programs enables many more people to use the whole GNU
+operating system, as well as its variant, the GNU/Linux operating
+system.
+
+  Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run
+that program using a modified version of the Library.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library".  The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.
+
+                  GNU LESSER GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License Agreement applies to any software library or other
+program which contains a notice placed by the copyright holder or
+other authorized party saying it may be distributed under the terms of
+this Lesser General Public License (also called "this License").
+Each licensee is addressed as "you".
+
+  A "library" means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+  The "Library", below, refers to any such software library or work
+which has been distributed under these terms.  A "work based on the
+Library" means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language.  (Hereinafter, translation is
+included without limitation in the term "modification".)
+
+  "Source code" for a work means the preferred form of the work for
+making modifications to it.  For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control compilation
+and installation of the library.
+
+  Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it).  Whether that is true depends on what the Library does
+and what the program that uses the Library does.
+
+  1. You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.
+
+  You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.
+
+  2. You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) The modified work must itself be a software library.
+
+    b) You must cause the files modified to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    c) You must cause the whole of the work to be licensed at no
+    charge to all third parties under the terms of this License.
+
+    d) If a facility in the modified Library refers to a function or a
+    table of data to be supplied by an application program that uses
+    the facility, other than as an argument passed when the facility
+    is invoked, then you must make a good faith effort to ensure that,
+    in the event an application does not supply such function or
+    table, the facility still operates, and performs whatever part of
+    its purpose remains meaningful.
+
+    (For example, a function in a library to compute square roots has
+    a purpose that is entirely well-defined independent of the
+    application.  Therefore, Subsection 2d requires that any
+    application-supplied function or table used by this function must
+    be optional: if the application does not supply it, the square
+    root function must still compute square roots.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library.  To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License.  (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.)  Do not make any other change in
+these notices.
+
+  Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+  This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.
+
+  4. You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.
+
+  If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  5. A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a "work that uses the Library".  Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.
+
+  However, linking a "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library".  The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.
+
+  When a "work that uses the Library" uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library.  The
+threshold for this to be true is not precisely defined by law.
+
+  If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work.  (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)
+
+  Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.
+
+  6. As an exception to the Sections above, you may also combine or
+link a "work that uses the Library" with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.
+
+  You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License.  You must supply a copy of this License.  If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License.  Also, you must do one
+of these things:
+
+    a) Accompany the work with the complete corresponding
+    machine-readable source code for the Library including whatever
+    changes were used in the work (which must be distributed under
+    Sections 1 and 2 above); and, if the work is an executable linked
+    with the Library, with the complete machine-readable "work that
+    uses the Library", as object code and/or source code, so that the
+    user can modify the Library and then relink to produce a modified
+    executable containing the modified Library.  (It is understood
+    that the user who changes the contents of definitions files in the
+    Library will not necessarily be able to recompile the application
+    to use the modified definitions.)
+
+    b) Use a suitable shared library mechanism for linking with the
+    Library.  A suitable mechanism is one that (1) uses at run time a
+    copy of the library already present on the user's computer system,
+    rather than copying library functions into the executable, and (2)
+    will operate properly with a modified version of the library, if
+    the user installs one, as long as the modified version is
+    interface-compatible with the version that the work was made with.
+
+    c) Accompany the work with a written offer, valid for at
+    least three years, to give the same user the materials
+    specified in Subsection 6a, above, for a charge no more
+    than the cost of performing this distribution.
+
+    d) If distribution of the work is made by offering access to copy
+    from a designated place, offer equivalent access to copy the above
+    specified materials from the same place.
+
+    e) Verify that the user has already received a copy of these
+    materials or that you have already sent this user a copy.
+
+  For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
+reproducing the executable from it.  However, as a special exception,
+the materials to be distributed need not include anything that is
+normally distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies
+the executable.
+
+  It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system.  Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+
+  7. You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:
+
+    a) Accompany the combined library with a copy of the same work
+    based on the Library, uncombined with any other library
+    facilities.  This must be distributed under the terms of the
+    Sections above.
+
+    b) Give prominent notice with the combined library of the fact
+    that part of it is a work based on the Library, and explaining
+    where to find the accompanying uncombined form of the same work.
+
+  8. You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License.  Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License.  However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+  9. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Library or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+  10. Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties with
+this License.
+
+  11. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply,
+and the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  12. If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License may add
+an explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded.  In such case, this License incorporates the limitation as if
+written in the body of this License.
+
+  13. The Free Software Foundation may publish revised and/or new
+versions of the Lesser General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Library
+specifies a version number of this License which applies to it and
+"any later version", you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation.  If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+
+  14. If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission.  For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this.  Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+                            NO WARRANTY
+
+  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+           How to Apply These Terms to Your New Libraries
+
+  If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of the
+ordinary General Public License).
+
+  To apply these terms, attach the following notices to the library.  It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+    SteamOS Devkit Service
+    Copyright (C) 2022 Valve Software inc.
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+    USA
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the library, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the
+  library `Frob' (a library for tweaking knobs) written by James Random
+  Hacker.
+
+  <signature of Ty Coon>, 1 April 1990
+  Ty Coon, President of Vice
+
+That's all there is to it!
diff --git a/tests/fakeframe/steamos-devkit-service/README.md b/tests/fakeframe/steamos-devkit-service/README.md
new file mode 100644
index 0000000..a694d7d
--- /dev/null
+++ b/tests/fakeframe/steamos-devkit-service/README.md
@@ -0,0 +1,21 @@
+# Valve's steamos-devkit-service (vendored, for the fake Frame only)
+
+Unmodified copy of [steamos-devkit-service](https://gitlab.steamos.cloud/devkit/steamos-devkit-service):
+the HTTP service on port 32000 (`src/`) and its hooks (`hooks/`), which the
+fake Frame image installs at `/usr/lib/steamos-devkit/` and
+`/usr/share/steamos-devkit/hooks/`, where the service looks for them.
+
+- Source: commit `74cf8fe` (2025-09-16, tag `v0.20250916.0`).
+- Licence: the repository's `LICENSE` is the LGPL 2.1 (copied here).
+  `src/steamos-devkit-service.py` itself carries an MIT header, and
+  `hooks/devkit-1-identify` and `hooks/install-ssh-key` carry LGPL-2.1+
+  headers. Nothing here ships in Frame Control; it's only built into the
+  test image.
+
+The service imports `dbus` to advertise itself over mDNS through
+systemd-resolved, which a container doesn't have. The image puts a small
+stand-in `dbus` module on its `PYTHONPATH` (`rootfs/usr/local/lib/fakeframe/pystubs`)
+that records the registration instead. Everything else runs as Valve wrote it.
+
+To update: copy `src/`, `hooks/` and `LICENSE` from a newer checkout and update
+the commit line above.
diff --git a/tests/fakeframe/steamos-devkit-service/hooks/approve-ssh-key b/tests/fakeframe/steamos-devkit-service/hooks/approve-ssh-key
new file mode 100755
index 0000000..a022ed5
--- /dev/null
+++ b/tests/fakeframe/steamos-devkit-service/hooks/approve-ssh-key
@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+
+import sys
+import os
+import logging
+import tempfile
+from urllib.parse import quote_plus as urllib_quote_plus
+import subprocess
+import json
+
+ENABLE_SSHD = '/usr/bin/steamos-polkit-helpers/steamos-enable-sshd'
+
+logger = logging.getLogger(os.path.realpath(__file__))
+
+import devkit_utils
+
+if __name__ == '__main__':
+    logger.setLevel(logging.INFO)
+    ch = logging.StreamHandler()
+    ch.setLevel(logging.INFO)
+    ch.setFormatter(logging.Formatter('%(name)s:%(message)s'))
+    logger.addHandler(ch)
+
+    request = open(sys.argv[1], 'rt').read()
+    requestIP = 'Unknown'
+    try:
+        requestIP = sys.argv[2]
+    except NameError:
+        logger.warning('request IP not given as argument to hook')
+        pass
+
+    key_identifier = request.split(' ')[2]
+    request = f'Development host at IP {requestIP} key: {key_identifier!r}'
+
+    ret = {}
+
+    try:
+        devkit_utils.validate_steam_client()
+    except devkit_utils.SteamClientNotRunningException as e:
+        msg = 'Steam is not running'
+        logger.warning(msg)
+        ret['error'] = msg
+    else:
+        with tempfile.TemporaryDirectory(prefix='approve-ssh-key') as tempdir:
+            logger.info('Sending pairing request to Steam')
+            response = os.path.join(tempdir, 'response')
+            cmd = 'approve-ssh-key?response={}&request={}'.format(
+                urllib_quote_plus(response),
+                urllib_quote_plus(request),
+            )
+            devkit_utils.execute_steam_client_command(cmd)
+            try:
+                with devkit_utils.wait_on_file_response(response, timeout=30) as f:
+                    logger.debug('Got response from Steam client')
+                    # Make sure sshd is enabled to support development features
+                    if os.path.exists(ENABLE_SSHD):
+                        subprocess.check_call(ENABLE_SSHD)
+                    else:
+                        subprocess.check_call('sudo systemctl enable --now sshd', shell=True)
+            except devkit_utils.SteamResponse_Timeout:
+                ret['error'] = 'timeout - Steam did not respond to the pairing request'
+            except devkit_utils.SteamResponse_Error as e:
+                ret['error'] = e.error_response
+
+    # json dictionary response gets written to stdout
+    # NOTE: the devkit service unfortunately smashes stdout/stderr all together in a text response, but we can still work with that
+    sys.stdout.flush()
+    sys.stderr.flush()
+    print(json.dumps(ret))
+    retcode = 1 if 'error' in ret else 0
+    sys.exit(retcode)
diff --git a/tests/fakeframe/steamos-devkit-service/hooks/devkit-1-identify b/tests/fakeframe/steamos-devkit-service/hooks/devkit-1-identify
new file mode 100755
index 0000000..301583d
--- /dev/null
+++ b/tests/fakeframe/steamos-devkit-service/hooks/devkit-1-identify
@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+# encoding: utf-8
+
+# This file is part of steamos-devkit
+# SPDX-License-Identifier: LGPL-2.1+
+#
+# Copyright 2017-2018 Collabora Ltd
+#
+# This package is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This package is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this package.  If not, see
+# <http://www.gnu.org/licenses/>.
+
+# Sample script run to identify the machine we are running on. This
+# is used by the devkit daemon to choose an identity for the machine,
+# and can also be run directly.
+#
+# A script or binary (written in any language) named devkit-1-identify
+# can be placed in the same directory as this sample, and it will be
+# used preferentially.
+#
+# Execution environment:
+# - Runs as root, or as an ordinary user who can run games
+# - Part of a non-interactive secure shell session
+# Input:
+# - None
+# Output:
+# - Exit 0 on success or nonzero on error
+# - On success, must print JSON to stdout containing one object with
+#   the following keys and string values, all of which are optional:
+#   - "machine_id": The hexadecimal systemd/D-Bus machine-id(5)
+#     (in the case of a conflict between systemd's /etc/machine-id and
+#     D-Bus' traditional /var/lib/dbus/machine-id, the systemd version
+#     should be preferred)
+#   - "hostname": The machine-readable hostname as set by sethostname(2)
+#   - "pretty_hostname": A human-friendly version of the hostname as
+#     found in systemd's machine-info(5)
+#   - "product_family", "product_name", "product_serial", "product_uuid",
+#     "sys_vendor": as for /sys/devices/virtual/dmi/id
+#   - "product": The best human-friendly description of the machine
+#     hardware we can devise, for example "Alienware ASM100"
+#   - "serial": The best hardware serial number we can devise
+#   - "machine_name": The best unique name for the machine that we can
+#     devise
+# - Any diagnostic messages must be printed to stderr only
+
+import json
+import os
+import re
+import socket
+import subprocess
+import sys
+
+_MACHINE_ID_RE = re.compile(r'^[0-9A-Fa-f]{32,32}$')
+_USELESS_HOSTNAMES = frozenset((
+    'debian',
+    'host',
+    'localhost',
+    'steamos',
+    'ubuntu',
+))
+# The case combination sometimes varies, so this is lowercased and we
+# use lower() to compare.
+_USELESS_DMI_NAMES = frozenset((
+    'to be filled by o.e.m.',
+))
+
+if __name__ == '__main__':
+
+    info = {}
+    steam_serialnumber = None
+
+    for k in ('product_family', 'product_name', 'product_serial',
+              'product_uuid', 'sys_vendor'):
+        try:
+            with open('/sys/devices/virtual/dmi/id/{}'.format(k)) as reader:
+                v = reader.read().strip()
+
+                if v and v.lower() not in _USELESS_DMI_NAMES:
+                    info[k] = v
+        except (IOError, OSError, UnicodeError):
+            pass
+
+    try:
+        for f in ('/etc/machine-id', '/var/lib/dbus/machine-id'):
+            with open(f) as reader:
+                v = reader.read().strip()
+
+                if _MACHINE_ID_RE.match(v):
+                    info['machine_id'] = v
+    except (IOError, OSError, UnicodeError):
+        pass
+
+    if 'product_family' in info and 'sys_vendor' in info:
+        info['product'] = '{sys_vendor} {product_family}'.format(**info)
+    elif 'product_name' in info and 'sys_vendor' in info:
+        info['product'] = '{sys_vendor} {product_name}'.format(**info)
+    elif 'product_family' in info:
+        info['product'] = info['product_family']
+    elif 'product_name' in info:
+        info['product'] = info['product_name']
+
+    if os.access('/usr/bin/hostnamectl', os.X_OK):
+        try:
+            v = subprocess.check_output([
+                'hostnamectl', '--pretty',
+            ]).decode('utf-8').strip()
+        except (subprocess.CalledProcessError, UnicodeError):
+            pass
+        else:
+            if v:
+                info['pretty_hostname'] = v
+
+            v = subprocess.check_output([
+                'hostnamectl', '--static',
+            ]).decode('utf-8').strip()
+
+            if v:
+                info['hostname'] = v
+
+    if 'hostname' not in info:
+        try:
+            info['hostname'] = socket.gethostname()
+        except (IOError, OSError, UnicodeError):
+            pass
+
+    if steam_serialnumber:
+        info['serial'] = steam_serialnumber
+    elif 'product_serial' in info:
+        info['serial'] = info['product_serial']
+
+    if 'product' in info:
+        info['machine_name'] = info['product']
+
+    if 'hostname' in info and info['hostname'] not in _USELESS_HOSTNAMES:
+        info['machine_name'] = info['hostname']
+
+    if 'pretty_hostname' in info:
+        info['machine_name'] = info['pretty_hostname']
+
+    json.dump(info, sys.stdout, indent=4, sort_keys=True)
+    print()
diff --git a/tests/fakeframe/steamos-devkit-service/hooks/devkit_utils/__init__.py b/tests/fakeframe/steamos-devkit-service/hooks/devkit_utils/__init__.py
new file mode 100644
index 0000000..4d5feba
--- /dev/null
+++ b/tests/fakeframe/steamos-devkit-service/hooks/devkit_utils/__init__.py
@@ -0,0 +1,265 @@
+#!/usr/bin/env python
+# encoding: utf-8
+"""Utility functions for the Steam client hook scripts"""
+
+import sys
+import os
+import traceback
+import tempfile
+import json
+import logging
+import fcntl
+import errno
+import contextlib
+import time
+import fcntl
+
+
+import logging as logging_module
+logger = logging_module.getLogger(__name__)
+
+
+@contextlib.contextmanager
+def wrap_outputs(stderr_prefix):
+    # capture stderr to file to support debugging
+    stderr_fd = sys.stderr.fileno()
+    tf = tempfile.NamedTemporaryFile(
+        mode='w+',
+        prefix=stderr_prefix,
+        delete=True)
+    if sys.version_info >= (3, 4):
+        # this API in the os module is only available for python3
+        # but it does not seem to work with subprocess anyway
+        os.set_inheritable(tf.file.fileno(), True)
+        assert os.get_inheritable(tf.file.fileno())
+    sys.stderr = tf.file
+
+    # we can only write out a json response to stdout,
+    # so redirect stdout to stderr,
+    # and keep a handle on the original stdout for the response
+    stdout_fd = os.dup(sys.stdout.fileno())
+    os.dup2(sys.stderr.fileno(), sys.stdout.fileno())
+
+    ctx = {}
+    try:
+        yield ctx
+    except:
+        logger.error(traceback.format_exc())
+    finally:
+        tf.flush()
+        tf.seek(0)
+        os.write(stderr_fd, tf.read().encode('utf-8'))
+        if 'ret' in ctx:
+            os.write(stdout_fd, json.dumps(ctx['ret']).encode('utf-8'))
+
+
+class SteamClientNotRunningException(Exception):
+    def __init__(self, error_message):
+        self.error_message = error_message
+
+    def __str__(self):
+        return self.error_message
+
+
+def validate_steam_client():
+    """Verify that the steam client is running, and permissions are adequate"""
+    pid_path = os.path.normpath(
+        os.path.realpath(
+            os.path.expanduser('~/.steam/steam.pid')))
+    if not os.path.exists(pid_path):
+        raise SteamClientNotRunningException('{0} does not exist'.format(pid_path))
+    try:
+        pid = int(open(pid_path, 'rt').read())
+    except Exception:
+        raise SteamClientNotRunningException('{0} is invalid'.format(pid_path))
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        raise SteamClientNotRunningException('{0} does not refer to a valid process'.format(pid_path))
+    logger.info('Found steam client pid %s', pid)
+
+
+def execute_steam_client_command(cmd):
+    """Send a command to the steam client over the IPC pipe"""
+    pipe_path = os.path.normpath(
+        os.path.realpath(
+            os.path.expanduser('~/.steam/steam.pipe')))
+    try:
+        pipe = open(pipe_path, 'wb+', 0)
+    except IOError:
+        raise Exception('cannot open steam client pipe')
+    session_token = open(os.path.expanduser('~/.steam/steam.token')).read()
+    pipe_cmd = 'devkit-1 steam://devkit-1/{0}/{1}'.format(
+        session_token,
+        cmd
+    )
+    logger.debug('Sending command line:')
+    logger.debug(pipe_cmd)
+    pipe.write('{0}\n'.format(pipe_cmd).encode('utf-8'))
+    pipe.close()
+
+
+def save_argv(gameid, argv):
+    """Save command line and arguments if provided"""
+
+    if argv is None:
+        return
+
+    argvfile = os.path.join(os.getenv("HOME"), "devkit-game",
+                            gameid + "-argv.json")
+    try:
+        with open(argvfile, "w") as argvf:
+            fcntl.flock(argvf, fcntl.LOCK_EX)
+            json.dump(argv, argvf)
+            fcntl.flock(argvf, fcntl.LOCK_UN)
+    except IOError:
+        raise Exception(
+            "Unable to open argv file for writing: {0}".format(argvfile))
+
+
+def obtain_argv(gameid, argv):
+    """Obtain command line with arguments"""
+
+    # If present and not None or [], just return the local arguments
+    if argv:
+        return argv
+
+    # From here, expect arguments to have been saved previously
+    argvfile = os.path.join(os.getenv("HOME"), "devkit-game",
+                            gameid + "-argv.json")
+    try:
+        with open(argvfile, "r") as argvf:
+            fcntl.flock(argvf, fcntl.LOCK_EX)
+            argv = json.load(argvf)
+            fcntl.flock(argvf, fcntl.LOCK_UN)
+    except IOError:
+        raise Exception(
+            "Unable to open argv file for reading: {0}".format(argvfile))
+    return argv
+
+
+def save_settings(gameid, data):
+    """Save settings"""
+    settingsfile = os.path.join(os.getenv("HOME"), "devkit-game",
+                                gameid + "-settings.json")
+    settings = dict()
+
+    if data.get('clear_settings', False):
+        settings = {}
+    else:
+        try:
+            with open(settingsfile, "r") as f:
+                fcntl.flock(f, fcntl.LOCK_EX)
+                settings = json.load(f)
+                fcntl.flock(f, fcntl.LOCK_UN)
+        except IOError as e:
+            if (e.errno != errno.ENOENT):
+                raise
+
+    # Merge settings from new json
+    if 'settings' in data:
+        settings.update(data['settings'])
+
+    try:
+        with open(settingsfile, "w") as f:
+            fcntl.flock(f, fcntl.LOCK_EX)
+            json.dump(settings, f)
+            fcntl.flock(f, fcntl.LOCK_UN)
+    except (IOError):
+        raise Exception(
+            "Unable to open settings file for writing: {0}".format(
+                settingsfile
+            ))
+
+    return settings
+
+
+def load_settings(gameid):
+    settingsfile = os.path.join(os.getenv("HOME"), "devkit-game", gameid + '-settings.json')
+
+    if not os.path.isfile(settingsfile):
+        return None
+
+    with open(settingsfile, "r") as f:
+        fcntl.flock(f, fcntl.LOCK_EX)
+        settings = json.load(f)
+        fcntl.flock(f, fcntl.LOCK_UN)
+
+    return settings
+
+
+class SteamResponse_Timeout(Exception):
+    pass
+
+
+class SteamResponse_Error(Exception):
+    def __init__(self, error_response):
+        self.error_response = error_response
+
+    def __str__(self):
+        return self.error_response
+
+
+@contextlib.contextmanager
+def wait_on_file_response(path, timeout=5):
+    """
+The pipe to the Steam Client is one way.
+Responses from the Steam Client are written to filesystem.
+Protocol is as follows:
+- Steam Client creates a 'path.lock' file
+- Steam Client writes either 'path' or 'path.error' to indicate a problem
+- Steam Client deletes 'path.lock'
+- Caller (us) can then read the response
+
+NOTE 1: this function is used as a context manager and will block until a response comes in or timeout.
+
+NOTE 2: the files are created by Steam when responding to a command. If the files already exist the response protocol will break.
+    """
+    lock_path = '{0}.lock'.format(path)
+    error_path = '{0}.error'.format(path)
+    max_count = timeout
+    while True:
+        time.sleep(1)
+        if os.path.exists(error_path) or os.path.exists(path) and not os.path.exists(lock_path):
+            if os.path.exists(error_path):
+                with open(error_path, 'r') as f:
+                    fcntl.flock(f, fcntl.LOCK_EX)
+                    error_response = f.read()
+                    fcntl.flock(f, fcntl.LOCK_UN)
+                    raise SteamResponse_Error(error_response)
+            with open(path, 'r') as f:
+                fcntl.flock(f, fcntl.LOCK_EX)
+                success_response = f.read()
+                yield success_response
+                fcntl.flock(f, fcntl.LOCK_UN)
+                return
+        max_count -= 1
+        if max_count > 0:
+            continue
+        raise SteamResponse_Timeout()
+
+
+# Setting up as a context manager so we never miss the deletion
+# Creating a temporary .lock file to guard the create operation
+@contextlib.contextmanager
+def create_pid(pid_path):
+    os.makedirs(os.path.dirname(pid_path), exist_ok=True)
+    lock_path = '{0}.lock'.format(pid_path)
+    try:
+        lock_file = os.open(lock_path, os.O_CREAT | os.O_EXCL)
+    except IOError as e:
+        logger.error('cannot create lock file %s for pid file %s', lock_path, pid_path)
+        logger.error('remove the lock file manually and run again if you are confident no other instance is active')
+        raise
+
+    pid_file = open(pid_path,'w')
+    pid_file.write(str(os.getpid()))
+    pid_file.flush()
+    os.close(lock_file)
+    os.unlink(lock_path)
+    try:
+        yield pid_file
+    finally:
+        pid_file.close()
+        # Assume that's atomic and all is well, no need for another .lock
+        os.unlink(pid_path)
diff --git a/tests/fakeframe/steamos-devkit-service/hooks/install-ssh-key b/tests/fakeframe/steamos-devkit-service/hooks/install-ssh-key
new file mode 100755
index 0000000..e0d9cd1
--- /dev/null
+++ b/tests/fakeframe/steamos-devkit-service/hooks/install-ssh-key
@@ -0,0 +1,74 @@
+#!/bin/sh
+#
+# This file is part of steamos-devkit
+# SPDX-License-Identifier: LGPL-2.1+
+#
+# Copyright © 2017-2018 Collabora Ltd
+#
+# This package is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This package is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this package.  If not, see
+# <http://www.gnu.org/licenses/>.
+
+# Sample script to install ssh keys that were approved by the
+# approve-ssh-key script.
+#
+# A script or binary (written in any language) named install-ssh-key
+# can be placed in the same directory as this sample, and it will be
+# used preferentially.
+#
+# Execution environment:
+# - Runs as root
+# Input:
+# - The public key is in a temporary file accessible via argv[1], in
+#   OpenSSH format
+# - argv[2], ... are the users to which we should grant access
+# Output:
+# - Exit 0 to accept the key, or nonzero to reject or on error
+#
+# This sample implementation should be suitable for any machine that
+# has the specified users. A production implementation would be similar
+# or even identical.
+
+set -e
+
+public_key="$1"
+shift
+
+echo "Installing public key '$public_key' for users: $*"
+
+for user in "$@"
+do
+    if pwent="$(getent passwd "$user")"
+    then
+        home="$(echo "$pwent" | cut -d: -f6)"
+        group="$(id -gn "$user")"
+        install -d -m 0755 -o "$user" -g "$group" "$home/.ssh"
+        if ! [ -e "$home/.ssh/authorized_keys" ]
+        then
+            install -m 0600 -o "$user" -g "$group" "$public_key" "$home/.ssh/authorized_keys"
+        else
+            if ! ( grep -v '^#' "$home/.ssh/authorized_keys" | grep -qF "$(cut -d " " -f2 "$public_key")" )
+            then
+                if [ -n "$(tail -1c "$home/.ssh/authorized_keys")" ]
+                then
+                    echo >> "$home/.ssh/authorized_keys"
+                fi
+                cat "$public_key" >> "$home/.ssh/authorized_keys"
+            fi
+        fi
+    fi
+done
+
+echo "Public key installed"
+
+exit 0
diff --git a/tests/fakeframe/steamos-devkit-service/src/steamos-devkit-service.py b/tests/fakeframe/steamos-devkit-service/src/steamos-devkit-service.py
new file mode 100755
index 0000000..f22f3ac
--- /dev/null
+++ b/tests/fakeframe/steamos-devkit-service/src/steamos-devkit-service.py
@@ -0,0 +1,522 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# MIT License
+#
+# Copyright (c) 2022 Valve Software inc., Collabora Ltd
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from http.server import BaseHTTPRequestHandler
+import configparser
+import getpass
+import json
+import os
+import platform
+import socketserver
+import subprocess
+import tempfile
+import urllib.parse
+import argparse
+import threading
+import sys
+import builtins
+import signal
+
+import dbus
+
+# Print to stderr, which is unbuffered and easier to read in journalctl
+STDOUT_PRINT = builtins.print
+def stderr_print(*args, **kwargs):
+    if 'file' not in kwargs:
+        kwargs['file'] = sys.stderr
+    global STDOUT_PRINT
+    return STDOUT_PRINT(*args, **kwargs)
+builtins.print = stderr_print
+
+# Expect a SIGUSR1 signal to exit
+# Could come at any time so we keep a global flag, but also support a callback
+SHOULD_EXIT = False
+EXIT_CALLBACK = None
+def handle_sigusr1(signum, frame):
+    """ Handle SIGUSR1 signal
+    """
+    global SHOULD_EXIT
+    global EXIT_CALLBACK
+    print("Received SIGUSR1, exiting.")
+    SHOULD_EXIT = True
+    if EXIT_CALLBACK:
+        EXIT_CALLBACK()
+def set_exit_callback(callback):
+    """ Set a callback to be called when we receive a SIGUSR1 signal
+    """
+    global SHOULD_EXIT
+    global EXIT_CALLBACK
+    EXIT_CALLBACK = callback
+    #print(f'Exit callback set to {EXIT_CALLBACK}')
+    if SHOULD_EXIT and EXIT_CALLBACK:
+        EXIT_CALLBACK()
+signal.signal(signal.SIGUSR1, handle_sigusr1)
+
+SERVICE_PORT = 32000
+PACKAGE = "steamos-devkit-service"
+DEVKIT_HOOKS_DIR = "/usr/share/steamos-devkit/hooks"
+CURRENT_TXTVERS = '1'
+
+ENTRY_POINT = "devkit-1"
+# root until config is loaded and told otherwise, etc.
+ENTRY_POINT_USER = "root"
+DEVICE_USERS = []
+PROPERTIES = {"txtvers": 1,
+              "login": ENTRY_POINT_USER,
+              "settings": "",
+              "devkit1": [
+                  ENTRY_POINT
+              ]}
+
+# Forced mDNS republish currently disabled, was causing a bad interaction with org.freedesktop.resolve1
+FORCE_PUBLISH_INTERVAL = 0
+
+def write_file(data: bytes) -> str:
+    """ Write given bytes to a temporary file and return the filename
+
+    Return the empty string if unable to open temp file for some reason
+    """
+
+    with tempfile.NamedTemporaryFile(mode='w', prefix='devkit-1', encoding='utf-8',
+        delete=False) as file:
+        file.write(data.decode())
+
+        return file.name
+
+    return ''
+
+
+def write_key(post_body: bytes) -> str:
+    """ Write key to temp file and return filename if valid
+
+    Return the empty string if invalid
+    """
+    length = len(post_body)
+    found_name = False
+
+    if length >= 64 * 1024:
+        print("Key length too long")
+        return ''
+    if not post_body.decode().startswith('ssh-rsa '):
+        print("Key doesn't start with ssh-rsa ")
+        return ''
+
+    # Get to the base64 bits
+    index = 8
+    while index < length and post_body[index] == ' ':
+        index = index + 1
+
+    # Make sure key is base64
+    body_decoded = post_body.decode()
+    while index < length:
+        if ((body_decoded[index] == '+') or (body_decoded[index] == '/') or
+                (body_decoded[index].isdigit()) or
+                (body_decoded[index].isalpha())):
+            index = index + 1
+            continue
+        if body_decoded[index] == '=':
+            index = index + 1
+            if (index < length) and (body_decoded[index] == ' '):
+                break
+            if (index < length) and (body_decoded[index] == '='):
+                index = index + 1
+                if (index < length) and (body_decoded[index] == ' '):
+                    break
+            print("Found = but no space or = next, invalid key")
+            return ''
+        if body_decoded[index] == ' ':
+            break
+
+        print("Found invalid data, invalid key at "
+              f"index: {index} data: {body_decoded[index]}")
+        return ''
+
+    print(f"Key is valid base64, writing to temp file index: {index}")
+    while index < length:
+        if body_decoded[index] == ' ':
+            # it's a space, the rest is name or magic phrase, don't write to disk
+            if found_name:
+                print(f"Found name ending at index {index}")
+                length = index
+            else:
+                print(f"Found name ending index {index}")
+                found_name = True
+        if body_decoded[index] == '\0':
+            print("Found null terminator before expected")
+            return ''
+        if body_decoded[index] == '\n' and index != length - 1:
+            print("Found newline before expected")
+            return ''
+        index = index + 1
+
+    # write data to the file
+    data = body_decoded[:length]
+    filename = write_file(data.encode())
+
+    if filename:
+        print(f"Filename key written to: {filename}")
+
+    return filename
+
+
+def find_hook(name: str) -> str:
+    """ Find a hook with the given name
+
+    Return the path to the hook if found. '' if not found
+    """
+    test_path = f"{DEVKIT_HOOKS_DIR}/{name}"
+    if os.path.exists(test_path) and os.access(test_path, os.X_OK):
+        return test_path
+
+    print(f"Error:: Unable to find hook for {name}")
+    return ''
+
+
+def get_machine_name() -> str:
+    """ Get the machine name and return it in a string
+
+    Use identify hook first, and if that fails just get the hostname.
+    """
+    machine_name = ''
+    # Run devkit-1-identify hook to get hostname, otherwise use default platform.node()
+    identify_hook = find_hook("devkit-1-identify")
+    if identify_hook:
+        # Run hook and parse machine_name out
+        process = subprocess.Popen(identify_hook, shell=False, stdout=subprocess.PIPE)
+        output = ''
+        for line in process.stdout:
+            textline = line.decode(encoding='utf-8', errors="ignore")
+            output += textline
+        process.wait()
+        output_object = json.loads(output)
+        if 'machine_name' in output_object:
+            machine_name = output_object["machine_name"]
+
+    if not machine_name:
+        machine_name = platform.node()
+
+    return machine_name
+
+
+class DevkitHandler(BaseHTTPRequestHandler):
+    """ Class to handle http requests on selected port for registration, getting properties.
+    """
+    def _send_headers(self, code, content_type):
+        self.send_response(code)
+        self.send_header("Content-type", content_type)
+        self.end_headers()
+
+    def do_GET(self):
+        """ Handle GET requests
+        """
+        print(f"GET request to path {self.path} from {self.client_address[0]}")
+
+        if self.path == "/login-name":
+            self._send_headers(200, "text/plain")
+            self.wfile.write(ENTRY_POINT_USER.encode())
+            return
+
+        if self.path == "/properties.json":
+            self._send_headers(200, "application/json")
+            self.wfile.write(json.dumps(PROPERTIES, indent=2).encode())
+            return
+
+        query = urllib.parse.parse_qs(self.path[2:])
+        print(f"query is {query}")
+
+        if len(query) > 0 and query["command"]:
+            command = query["command"][0]
+
+            if command == "ping":
+                self._send_headers(200, "text/plain")
+                self.wfile.write("pong\n".encode())
+                return
+
+            self._send_headers(404, "")
+            return
+
+        self._send_headers(404, "")
+        self.wfile.write("Unknown request\n".encode())
+
+    def do_POST(self):
+        """ Handle POST requests
+        """
+        if self.path == "/register":
+            from_ip = self.client_address[0]
+            content_len = int(self.headers.get('Content-Length'))
+            post_body = self.rfile.read(content_len)
+            print(f"register request from {from_ip}")
+            filename = write_key(post_body)
+
+            if not filename:
+                self._send_headers(403, "text/plain")
+                self.wfile.write(json.dumps({'error':'Failed to write the ssh key'}).encode())
+                return
+
+            # Run approve script
+            approve_hook = find_hook("approve-ssh-key")
+            if not approve_hook:
+                self._send_headers(403, "text/plain")
+                self.wfile.write(json.dumps({'error':'Failed to find approve hook'}).encode())
+                os.unlink(filename)
+                return
+
+            # Run hook and parse output
+            approve_process = subprocess.Popen([approve_hook, filename, from_ip],
+                                               shell=False,
+                                               stdout=subprocess.PIPE)
+            approve_output = ''
+            for approve_line in approve_process.stdout:
+                approve_textline = approve_line.decode(encoding='utf-8', errors="ignore")
+                approve_output += approve_textline
+
+            approve_process.wait()
+            approve_object = json.loads(approve_output)
+            if "error" in approve_object:
+                self._send_headers(403, "text/plain")
+                self.wfile.write(approve_output.encode()) # is already a json {'error':} response
+                os.unlink(filename)
+                return
+
+            # Otherwise, assume it passed
+            install_hook = find_hook("install-ssh-key")
+            if not install_hook:
+                self._send_headers(403, "text-plain")
+                self.wfile.write(json.dumps({'error':'Failed to find install-ssh-key hook'}).encode())
+                os.unlink(filename)
+                return
+
+            command = [install_hook, filename]
+            # Append each user to command as separate arguments
+            for user in DEVICE_USERS:
+                command.append(user)
+
+            install_process = subprocess.Popen(command, shell=False, stdout=subprocess.PIPE)
+            install_output = ''
+            for install_line in install_process.stdout:
+                install_textline = install_line.decode(encoding='utf-8', errors="ignore")
+                install_output += install_textline
+            install_process.wait()
+
+            exit_code = install_process.returncode
+            if exit_code != 0:
+                self._send_headers(500, "text/plain")
+                self.wfile.write("install-ssh-key:\n".encode())
+                self.wfile.write(install_output.encode())
+                os.unlink(filename)
+                return
+
+            self._send_headers(200, "text/plain")
+            self.wfile.write("Registered\n".encode())
+            os.unlink(filename)
+
+
+class DevkitService:
+    """ Class to run as service.
+
+    Parses configuration, creates handler, registers an entry in dynamic DNS, etc.
+    """
+    def __init__(self):
+        global ENTRY_POINT_USER
+        global DEVICE_USERS
+
+        self.port = SERVICE_PORT
+        self.name = get_machine_name()
+        self.stype = "_steamos-devkit._tcp"
+
+        self.service_path = None
+
+        config = configparser.ConfigParser()
+        # Use str form to preserve case
+        config.optionxform = str
+        config.read(["/etc/steamos-devkit/steamos-devkit.conf",
+                     "/usr/share/steamos-devkit/steamos-devkit.conf",
+                     os.path.join(os.path.expanduser('~'), '.config', PACKAGE, PACKAGE + '.conf')])
+
+        self.settings = {}
+        if 'Settings' in config:
+            settings = config["Settings"]
+            self.settings = dict(settings)
+            if 'Port' in settings:
+                self.port = int(settings["Port"])
+
+        PROPERTIES["settings"] = json.dumps(self.settings)
+
+        # Parse users from configs
+        if os.geteuid() == 0:
+            # Running as root, maybe warn?
+            print("Running as root, Probably shouldn't be\n")
+            if 'Users' in config:
+                users = config["Users"]
+                if 'ShellUsers' in users:
+                    DEVICE_USERS = users["ShellUsers"]
+        else:
+            if 'Users' in config:
+                users = config["Users"]
+                if 'ShellUsers' in users:
+                    DEVICE_USERS = users["ShellUsers"]
+            else:
+                username = getpass.getuser()
+                print(f'Username: {username}')
+                DEVICE_USERS = []
+                DEVICE_USERS.append(username)
+
+        # If only one user, that's the entry point user
+        # Otherwise entry_point_user needs to be root to be able to switch between users
+        if len(DEVICE_USERS) == 1:
+            ENTRY_POINT_USER = DEVICE_USERS[0]
+            PROPERTIES["login"] = ENTRY_POINT_USER
+
+        # "an array of dictionaries mapping strings to byte arrays" .. biggest eyeroll
+        py_dict = {}
+        for key, value in [
+            ('txtvers', CURRENT_TXTVERS),
+            ('settings', json.dumps(self.settings)),
+            ('login', ENTRY_POINT_USER),
+            ('devkit1', ENTRY_POINT)
+        ]:
+            py_dict[key] = dbus.Array([ord(c) for c in value], signature='y')
+        self.txt_records = dbus.Array( [dbus.Dictionary(py_dict, signature='say' )], signature='a{say}' )
+
+        self.dbus_bus = dbus.SystemBus()
+        self.resolve1_register = self.dbus_bus.get_object(
+            'org.freedesktop.resolve1',
+            '/org/freedesktop/resolve1'
+        ).get_dbus_method(
+            'RegisterService',
+            'org.freedesktop.resolve1.Manager'
+        )
+        self.resolve1_unregister = self.dbus_bus.get_object(
+            'org.freedesktop.resolve1',
+            '/org/freedesktop/resolve1'
+        ).get_dbus_method(
+            'UnregisterService',
+            'org.freedesktop.resolve1.Manager'
+        )
+
+        self.httpd = socketserver.TCPServer(("", self.port), DevkitHandler, bind_and_activate=False)
+        print(f"serving at port: {self.port}")
+        print(f"machine name: {self.name}")
+        self.httpd.allow_reuse_address = True
+        self.httpd.server_bind()
+        self.httpd.server_activate()
+
+    def publish(self, recursed=False, silent=False):
+        """ Publish ourselves on mdns as an available devkit device.
+        """
+        # https://www.freedesktop.org/software/systemd/man/latest/org.freedesktop.resolve1.html
+
+        if not silent:
+            print(f'RegisterService {self.name} {self.stype} {self.port}')
+        self.unpublish(silent)
+
+        try:
+            self.service_path = self.resolve1_register(
+                # Passing '%H' should amount to the same thing
+                # (is expanded based on specifiers, see https://www.man7.org/linux/man-pages/man5/systemd.dnssd.5.html)
+                self.name,
+                # 'name_template' .. what is this?
+                # also referred to as 'service instance name' in the implementation
+                # can't be an empty string, gets expanded with the same specifier rules as name,
+                # gets random numbers appended to it for a new instance name in case of service collisions?
+                self.name,
+                self.stype,
+                dbus.UInt16(int(self.port)),
+                dbus.UInt16(10),    # priority (see https://en.wikipedia.org/wiki/SRV_record)
+                dbus.UInt16(0),     # weight
+                self.txt_records,
+            )
+        except dbus.exceptions.DBusException as e:
+            # services will persist, it's bad if we didn't properly unregister, but we can recover this
+            if not recursed and e.get_dbus_name() == 'org.freedesktop.resolve1.DnssdServiceExists':
+                print('Service is already registered! Trying to recover')
+                self.service_path = f'/org/freedesktop/resolve1/dnssd/{self.name}'
+                self.unpublish()
+                self.publish(True)
+            else:
+                raise e
+
+    def unpublish(self, silent=False):
+        """ Remove publishing of ourselves as devkit device since we are quitting.
+        """
+        if self.service_path:
+            if not silent:
+                print(f'UnregisterService {self.service_path}')
+            self.resolve1_unregister(self.service_path)
+            self.service_path = None
+
+    def force_publish(self, exit_event):
+        while True:
+            exit_event.wait(timeout=FORCE_PUBLISH_INTERVAL)
+            if exit_event.is_set():
+                break
+            self.publish(False, True)
+
+    def on_signal_shutdown(self):
+        print('Shutting down the httpd server')
+        # This is blocking and needs to run in a thread, otherwise we'll deadlock
+        threading.Thread(target=self.httpd.shutdown, daemon=True).start()
+
+    def run_server(self):
+        """ Run server until keyboard interrupt or we are killed
+        """
+
+        thread = None
+        exit_event = None
+        global FORCE_PUBLISH_INTERVAL
+        if 'ForcePublishInterval' in self.settings:
+            FORCE_PUBLISH_INTERVAL = int(self.settings['ForcePublishInterval'])
+        if FORCE_PUBLISH_INTERVAL != 0:
+            exit_event = threading.Event()
+            thread = threading.Thread(target=self.force_publish, args=[exit_event,], daemon=True).start()
+
+        set_exit_callback(self.on_signal_shutdown)
+        try:
+            self.httpd.serve_forever()
+        except KeyboardInterrupt:
+            pass
+        set_exit_callback(None)
+
+        if thread:
+            exit_event.set()
+            thread.join()
+
+        self.httpd.server_close()
+        print(f"done serving at port: {self.port}")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--hooks', required=False, action='store', help='hooks directory')
+    conf = parser.parse_args()
+
+    if conf.hooks is not None:
+        DEVKIT_HOOKS_DIR = conf.hooks
+
+    service = DevkitService()
+
+    service.publish()
+    service.run_server()
+    service.unpublish()
diff --git a/tests/smoke/frame_smoke.py b/tests/smoke/frame_smoke.py
new file mode 100644
index 0000000..6cad662
--- /dev/null
+++ b/tests/smoke/frame_smoke.py
@@ -0,0 +1,235 @@
+"""Headset smoke test: the fake Frame's core cases against a real Frame.
+
+Runs on your computer through the `frame` SSH alias (or FRAME_ALIAS), with
+Frame Control's own modules, and records what happened with the headset's
+BUILD_ID in tests/smoke/results/<time>-<BUILD_ID>.json (git-ignored):
+
+- properties.json from Valve's devkit service names the login user;
+- status (ui/frame_status.py) reads the build, battery and storage;
+- three tiny titles (tests/smoke/tiny_programs.py: ARM64 and x86-64 static
+  Linux programs, an x86-64 .exe) are installed, launched and removed with
+  ui/frame_titles.py, and Steam's logs about each are kept;
+- with --pair, a throwaway RSA key is paired through the devkit service
+  (someone has to open Settings > Developer > Pair new host and approve it in
+  the headset), checked, and taken out of authorized_keys again.
+
+Everything it installs is removed again, also when a step fails. Titles are
+named fc_smoke_*; leftovers from an interrupted run are removed first.
+
+Usage: python3 tests/smoke/frame_smoke.py [--pair]     (or scripts/frame-smoke.sh)
+Exit status: 0 all passed, 1 a step failed, 2 the headset isn't reachable.
+"""
+import argparse
+import json
+import os
+import platform
+import shlex
+import subprocess
+import sys
+import tempfile
+import time
+import traceback
+import urllib.request
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+ROOT = HERE.parent.parent
+sys.path[:0] = [str(ROOT / 'ui'), str(HERE)]
+ALIAS = os.environ.setdefault('FRAME_ALIAS', 'frame')   # read by frame_android at import
+
+import frame_android  # noqa: E402
+import frame_connect  # noqa: E402
+import frame_titles  # noqa: E402
+import tiny_programs  # noqa: E402
+
+RESULTS = HERE / 'results'
+PREFIX = 'fc_smoke_'
+# Earlier runs named titles fc-smoke*, which Steam refused to register but left on disk.
+OLD_PREFIX = 'fc-smoke'
+
+
+class Smoke:
+    def __init__(self):
+        self.steps = []
+        self.installed = set()
+
+    def step(self, name, fn, *args):
+        """Run one step; record ok/failed, its detail and how long it took."""
+        t0 = time.monotonic()
+        rec = {'step': name}
+        try:
+            detail = fn(*args)
+            rec.update(ok=True, detail=detail)
+        except Exception as e:  # a failed step is a result, not the end of the run
+            rec.update(ok=False, error=f'{type(e).__name__}: {e}', trace=traceback.format_exc(limit=3))
+        rec['seconds'] = round(time.monotonic() - t0, 1)
+        self.steps.append(rec)
+        print(f"  {'ok  ' if rec['ok'] else 'FAIL'} {name} ({rec['seconds']} s)"
+              + ('' if rec['ok'] else f": {rec['error']}"), flush=True)
+        return rec
+
+
+def ssh(cmd, timeout=60):
+    return frame_android.ssh(cmd, timeout=timeout)
+
+
+def ssh_config(key):
+    out = subprocess.run(['ssh', '-G', ALIAS], capture_output=True, text=True, timeout=10).stdout
+    for line in out.splitlines():
+        k, _, v = line.partition(' ')
+        if k == key:
+            return v.strip()
+    return None
+
+
+def os_release():
+    fields = {}
+    for line in ssh('cat /etc/os-release').splitlines():
+        k, _, v = line.partition('=')
+        fields[k] = v.strip('"')
+    return {k: fields.get(k) for k in ('VERSION_ID', 'VARIANT_ID', 'BUILD_ID')}
+
+
+def properties():
+    host = ssh_config('hostname') or ALIAS
+    with urllib.request.urlopen(frame_connect.devkit_url(host, 32000, '/properties.json'), timeout=5) as r:
+        props = json.load(r)
+    user = ssh_config('user')
+    if props.get('login') != user:
+        raise AssertionError(f"properties.json says login {props.get('login')!r}; the alias logs in as {user!r}")
+    return props
+
+
+def status(build):
+    s = json.loads(frame_android.ssh('python3 -', input=(ROOT / 'ui' / 'frame_status.py').read_text(), timeout=30))
+    if s['os']['build'] != build:
+        raise AssertionError(f"status says build {s['os']['build']}, /etc/os-release {build}")
+    for key in ('battery', 'disk', 'memory'):
+        if not s.get(key):
+            raise AssertionError(f'status has no {key}')
+    return {k: s.get(k) for k in ('os', 'battery', 'power', 'temp', 'services', 'volume')}
+
+
+def steam_log_lines(gid):
+    """What Steam logged about a title (log folder layout not verified; best effort)."""
+    out = ssh(f"grep -rsh -- {shlex.quote(gid)} ~/.local/share/Steam/logs/ 2>/dev/null | tail -n 12 || true")
+    return out.strip().splitlines()
+
+
+def title_cycle(smoke, kind, folder):
+    path = tiny_programs.write(folder, kind)
+    gid = PREFIX + kind                 # named outright: the file names would share one id
+
+    def install():
+        smoke.installed.add(gid)
+        meta = frame_titles.install(path, name=gid)
+        listed = {t['id']: t for t in frame_titles.list_titles()}
+        if gid not in listed:
+            raise AssertionError(f'{gid} is not in the title list after installing')
+        return {'id': gid, 'runtime': meta['runtime'], 'steam': meta.get('steam')}
+
+    def launch():
+        frame_titles.launch(gid)       # raises unless Steam confirmed it
+        time.sleep(4)
+        procs = ssh(f"pgrep -af -- {shlex.quote('devkit-game/' + gid)} || true").strip()
+        return {'processes': procs.splitlines(), 'steam_log': steam_log_lines(gid)}
+
+    def remove():
+        frame_titles.remove(gid)
+        left = ssh(f'ls -d ~/devkit-game/{gid} ~/devkit-game/{gid}-*.json 2>/dev/null || true').strip()
+        if left:
+            raise AssertionError(f'left behind: {left}')
+        if gid in {t['id'] for t in frame_titles.list_titles()}:
+            raise AssertionError(f'{gid} is still listed')
+        smoke.installed.discard(gid)
+        return {'removed': gid}
+
+    if smoke.step(f'{kind}: install', install)['ok']:
+        smoke.step(f'{kind}: launch', launch)
+        smoke.step(f'{kind}: remove', remove)
+
+
+def cleanup(smoke):
+    """Remove fc-smoke-* titles: this run's, and any an interrupted run left."""
+    try:
+        ids = {t['id'] for t in frame_titles.list_titles() if t['id'].startswith((PREFIX, OLD_PREFIX))}
+    except frame_android.FrameError:
+        ids = set(smoke.installed)      # can't list: try what this run installed
+    for gid in sorted(ids):
+        try:
+            frame_titles.remove(gid)
+        except frame_android.FrameError as e:
+            print(f'  could not remove {gid}: {e}')
+    return sorted(ids)
+
+
+def pair(folder):
+    """Pair a throwaway RSA key through the devkit service, check it, then remove it."""
+    key = os.path.join(folder, 'id_rsa_smoke')
+    subprocess.run(['ssh-keygen', '-q', '-t', 'rsa', '-b', '3072', '-N', '', '-C', 'frame-control-smoke',
+                    '-f', key], check=True)
+    pub = Path(key + '.pub').read_text()
+    host = ssh_config('hostname') or ALIAS
+    user = ssh_config('user')
+    comment = frame_connect.key_comment(platform.node()).replace('frame-control@', 'frame-control-smoke@')
+    print('    In the headset: Steam Settings > Developer > Pair new host, then approve '
+          f'"{comment}" (waits up to {frame_connect.PAIRING_MODE_WAIT} s)', flush=True)
+    b64 = pub.split()[1]
+    try:
+        reason = frame_connect.devkit_pair(host, pub, comment)
+        if reason:
+            raise AssertionError(reason)
+        r = subprocess.run(['ssh', '-o', 'BatchMode=yes', '-o', 'IdentitiesOnly=yes', '-o', 'ConnectTimeout=8',
+                            '-o', 'ControlPath=none', '-i', key, f'{user}@{host}', 'true'], capture_output=True, text=True)
+        if r.returncode != 0:
+            raise AssertionError(f'paired, but the key does not log in: {r.stderr.strip()}')
+        return {'comment': comment}
+    finally:
+        f = '~/.ssh/authorized_keys'
+        ssh(f'grep -vF {b64} {f} > {f}.smoke; cat {f}.smoke > {f}; rm -f {f}.smoke')
+        if b64 in ssh(f'cat {f}'):
+            raise AssertionError('the smoke key is still in authorized_keys')
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument('--pair', action='store_true', help='also pair through the devkit service (needs you in the headset)')
+    args = ap.parse_args()
+
+    r = subprocess.run(['ssh', '-o', 'ConnectTimeout=5', '-o', 'BatchMode=yes', ALIAS, 'true'],
+                       capture_output=True, text=True)
+    if r.returncode != 0:
+        print(f'{ALIAS} is not reachable over SSH: {r.stderr.strip()}', file=sys.stderr)
+        return 2
+
+    smoke = Smoke()
+    started = time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())
+    release = os_release()
+    build = release['BUILD_ID'] or 'unknown'
+    print(f'==> Frame smoke test on {ALIAS}: SteamOS {release["VERSION_ID"]} ({release["VARIANT_ID"]}), build {build}')
+    left = cleanup(smoke)
+    if left:
+        print(f'  removed leftovers from an earlier run: {", ".join(left)}')
+    folder = tempfile.mkdtemp(prefix='frame-smoke-')
+    try:
+        smoke.step('devkit service: properties.json', properties)
+        smoke.step('status', status, build)
+        for kind in ('arm64', 'x86_64', 'exe'):
+            title_cycle(smoke, kind, folder)
+        if args.pair:
+            smoke.step('devkit pairing (throwaway key)', pair, folder)
+    finally:
+        removed = cleanup(smoke)
+        subprocess.run(['rm', '-rf', folder])
+    passed = sum(s['ok'] for s in smoke.steps)
+    RESULTS.mkdir(exist_ok=True)
+    out = RESULTS / f"{started.replace(':', '')}-{build}.json"
+    out.write_text(json.dumps({'started': started, 'alias': ALIAS, 'os_release': release, 'paired': args.pair,
+                               'passed': passed, 'failed': len(smoke.steps) - passed,
+                               'cleanup_removed': removed, 'steps': smoke.steps}, indent=1))
+    print(f'==> {passed}/{len(smoke.steps)} steps passed on build {build}; results in {out.relative_to(ROOT)}')
+    return 0 if passed == len(smoke.steps) else 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())
diff --git a/tests/smoke/tiny_programs.py b/tests/smoke/tiny_programs.py
new file mode 100644
index 0000000..c598b15
--- /dev/null
+++ b/tests/smoke/tiny_programs.py
@@ -0,0 +1,89 @@
+"""Tiny test programs for sideloading, built from bytes: no compiler needed.
+
+- elf_arm64(), elf_x86_64(): static Linux executables that sleep for a few
+  seconds (nanosleep) and exit 0, so a launch can be seen in `ps`.
+- pe_x86_64(): a Windows x86-64 .exe with no imports whose entry point
+  returns 0 straight away, which ends the process (Windows and Wine both
+  exit when the main thread returns).
+
+Each is a single loadable segment or section; they are what the headset
+smoke test and the fake Frame's e2e tests install. Python stdlib only.
+"""
+import struct
+
+SLEEP_SECONDS = 5
+BASE = 0x400000
+
+
+def _elf(machine, code):
+    """ELF64 little-endian ET_EXEC with one PT_LOAD (R+X) covering the whole file."""
+    ehsize, phsize = 64, 56
+    entry = BASE + ehsize + phsize
+    size = ehsize + phsize + len(code)
+    ident = b'\x7fELF' + bytes([2, 1, 1, 0]) + b'\0' * 8
+    header = ident + struct.pack('<HHIQQQIHHHHHH', 2, machine, 1, entry, ehsize, 0, 0,
+                                 ehsize, phsize, 1, 0, 0, 0)
+    phdr = struct.pack('<IIQQQQQQ', 1, 5, 0, BASE, BASE, size, size, 0x1000)
+    return header + phdr + code
+
+
+def elf_arm64(seconds=SLEEP_SECONDS):
+    words = [
+        0x10000100,                 # adr  x0, timespec (32 bytes ahead)
+        0xD2800001,                 # mov  x1, #0
+        0xD2800CA8,                 # mov  x8, #101        (nanosleep)
+        0xD4000001,                 # svc  #0
+        0xD2800000,                 # mov  x0, #0
+        0xD2800BA8,                 # mov  x8, #93         (exit)
+        0xD4000001,                 # svc  #0
+        0xD503201F,                 # nop  (pads the timespec to offset 32)
+    ]
+    return _elf(0xB7, struct.pack('<8I', *words) + struct.pack('<qq', seconds, 0))
+
+
+def elf_x86_64(seconds=SLEEP_SECONDS):
+    code = (b'\x48\x8d\x3d\x12\x00\x00\x00'   # lea  rdi, [rip+18] (the timespec)
+            b'\x31\xf6'                       # xor  esi, esi
+            b'\xb8\x23\x00\x00\x00'           # mov  eax, 35       (nanosleep)
+            b'\x0f\x05'                       # syscall
+            b'\x31\xff'                       # xor  edi, edi
+            b'\xb8\x3c\x00\x00\x00'           # mov  eax, 60       (exit)
+            b'\x0f\x05')                      # syscall
+    assert len(code) == 25
+    return _elf(0x3E, code + struct.pack('<qq', seconds, 0))
+
+
+def pe_x86_64():
+    """PE32+ console program: one .text section holding `xor eax, eax; ret`."""
+    file_align, sect_align, image_base = 0x200, 0x1000, 0x140000000
+    dos = b'MZ' + b'\0' * 0x3A + struct.pack('<I', 0x40)
+    coff = b'PE\0\0' + struct.pack('<HHIIIHH', 0x8664, 1, 0, 0, 0, 240, 0x0022)
+    opt = struct.pack('<HBBIIIII', 0x20B, 14, 0, file_align, 0, 0, 0x1000, 0x1000)
+    opt += struct.pack('<QIIHHHHHHIIIIHHQQQQII', image_base, sect_align, file_align,
+                       6, 0, 0, 0, 6, 0, 0,          # OS, image and subsystem versions, Win32VersionValue
+                       0x2000, file_align, 0,        # SizeOfImage, SizeOfHeaders, CheckSum
+                       3, 0x8100,                    # console subsystem; NX compatible, terminal-server aware
+                       0x100000, 0x1000, 0x100000, 0x1000, 0, 16)
+    opt += b'\0' * (16 * 8)                          # no data directories: no imports, no relocations
+    assert len(opt) == 240
+    text = b'.text\0\0\0' + struct.pack('<IIIIIIHHI', 3, 0x1000, file_align, file_align, 0, 0, 0, 0, 0x60000020)
+    headers = (dos + coff + opt + text).ljust(file_align, b'\0')
+    return headers + b'\x31\xc0\xc3'.ljust(file_align, b'\xcc')
+
+
+PROGRAMS = {                        # kind -> (file name, builder)
+    'arm64': ('fc-smoke-arm64', elf_arm64),
+    'x86_64': ('fc-smoke-x86_64', elf_x86_64),
+    'exe': ('fc-smoke-exe.exe', pe_x86_64),
+}
+
+
+def write(folder, kind):
+    """Write one program into folder; returns its path."""
+    import os
+    name, build = PROGRAMS[kind]
+    path = os.path.join(folder, name)
+    with open(path, 'wb') as f:
+        f.write(build())
+    os.chmod(path, 0o755)
+    return path

From 93aebb5019877042fc1834fd1075761f0c9089fe Mon Sep 17 00:00:00 2001
From: saphid <4596216+saphid@users.noreply.github.com>
Date: Sun, 27 Sep 2026 17:22:20 +1000
Subject: [PATCH 3/7] Fix the review's findings in the test harness

Headset smoke test: drop the paired key from authorized_keys with a
same-mode copy swapped in, so a failed write can't truncate it; check the
throwaway key with no ssh_config or agent; clean up idempotently (tracked
and leftover titles, their json files, Steam's shortcuts via steamos-delete,
and ~/devkit-utils if it wasn't there before), with a failed cleanup a
failed step; count a launch only with fresh evidence (the process, Steam's
log, or the known missing-runtime line), matching with [d]evkit-game so
pgrep doesn't find its own shell. The test programs sleep 10 s.

Fake Frame: log a launch before its reaper can look for it. e2e: kill a
pairing client's process group when a test ends; accept an aarch64 program
running under QEMU on x86 hosts.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docs/testing.md                               |  14 +-
 tests/e2e/test_pairing.py                     |  14 +-
 tests/e2e/test_titles.py                      |  11 +-
 .../usr/local/lib/fakeframe/fakesteam.py      |  57 +++----
 tests/smoke/frame_smoke.py                    | 141 ++++++++++++++----
 tests/smoke/tiny_programs.py                  |   2 +-
 6 files changed, 173 insertions(+), 66 deletions(-)

diff --git a/docs/testing.md b/docs/testing.md
index e70a4a7..c95ee75 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -111,9 +111,17 @@ scripts/frame-smoke.sh --pair    # also pairs a throwaway key: approve it in the
 
 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 five seconds, and
-an x86-64 `.exe` that exits at once), keeping what Steam logged about each.
-Everything it installs is removed again, also after a failure. Results go to
+(an ARM64 and an x86-64 static Linux program that sleep for ten seconds, and
+an x86-64 `.exe` that exits at once). A launch passes only with fresh evidence:
+the ARM64 program running, the `.exe` started (its process or Steam's log),
+and the x86-64 program running or Steam logging that its runtime isn't
+installed, which is what the Frame does today. Steam's log lines about each
+title are kept.
+
+Everything it installs is removed again, also after a failure: the titles and
+their Steam shortcuts, a paired key, and `~/devkit-utils` if it wasn't there
+before (if it was, it stays, synced to this checkout as Frame Control always
+does). A cleanup that fails counts as a failed step. Results go to
 `tests/smoke/results/<time>-<BUILD_ID>.json` (not committed) with a summary on
 screen; it exits 0 when every step passed, 1 if one failed, 2 if the headset
 isn't reachable.
diff --git a/tests/e2e/test_pairing.py b/tests/e2e/test_pairing.py
index aaf1ecf..8c6aae9 100644
--- a/tests/e2e/test_pairing.py
+++ b/tests/e2e/test_pairing.py
@@ -2,6 +2,7 @@
 steamos-devkit-service on the fake Frame, and its password fallback."""
 import json
 import os
+import signal
 import stat
 import subprocess
 import sys
@@ -28,9 +29,20 @@ class Pairing(harness.FrameTestCase):
                 f.write(f'#!/bin/sh\necho {askpass}\n')
             os.chmod(script, stat.S_IRWXU)
             env.update(SSH_ASKPASS=script, SSH_ASKPASS_REQUIRE='force')
-        return subprocess.Popen([sys.executable, str(ROOT / 'ui' / 'frame_connect.py'), FAKE_HOST],
+        proc = subprocess.Popen([sys.executable, str(ROOT / 'ui' / 'frame_connect.py'), FAKE_HOST],
                                 stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
                                 text=True, env=env, start_new_session=True)
+        self.addCleanup(self.stop, proc)    # a failed test mustn't leave it pairing into the next one
+        return proc
+
+    @staticmethod
+    def stop(proc):
+        if proc.poll() is None:
+            try:
+                os.killpg(proc.pid, signal.SIGKILL)     # frame_connect.py and its ssh children
+            except OSError:
+                pass
+        proc.communicate()
 
     def finish(self, proc, timeout=120):
         out, _ = proc.communicate(timeout=timeout)
diff --git a/tests/e2e/test_titles.py b/tests/e2e/test_titles.py
index c07bc0b..82d0afb 100644
--- a/tests/e2e/test_titles.py
+++ b/tests/e2e/test_titles.py
@@ -18,8 +18,9 @@ from harness import HOME, ROOT, ctl, exists, install_title, launches, ok, ssh, s
 harness.require()
 
 GAMES = f'{HOME}/devkit-game'
-# The host container shares the fake Frame's kernel, so a native program of this
-# machine's architecture really runs there; the other one fails to exec.
+# The host container shares the fake Frame's kernel, so a program of this machine's
+# architecture really runs there. The other one fails to exec, unless QEMU is
+# registered with binfmt_misc, which runs it emulated.
 NATIVE = {'aarch64': 'arm64', 'arm64': 'arm64', 'x86_64': 'x86_64'}.get(platform.machine())
 
 
@@ -74,10 +75,8 @@ class Titles(harness.FrameTestCase):
         if NATIVE == 'arm64':
             self.assertIsNotNone(run['pid'], run)
             done = wait_for(lambda: launches('devkit')[-1].get('exit') is not None and launches('devkit')[-1],
-                            20, 'the arm64 test program to exit')
+                            30, 'the arm64 test program to exit')
             self.assertEqual(done['exit'], 0)
-        else:
-            self.assertIn('Exec format error', run.get('exec_error', ''), run)
 
     def test_single_exe_upload_launch_and_remove(self):
         exe = tiny_programs.write(self.tmp, 'exe')
@@ -131,7 +130,7 @@ class Titles(harness.FrameTestCase):
         self.assertTrue(run['started'])
         if NATIVE == 'x86_64':
             done = wait_for(lambda: launches('devkit')[-1].get('exit') is not None and launches('devkit')[-1],
-                            20, 'the x86-64 test program to exit')
+                            30, 'the x86-64 test program to exit')
             self.assertEqual(done['exit'], 0)
 
     def test_reinstall_with_another_runtime_keeps_one_shortcut(self):
diff --git a/tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakesteam.py b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakesteam.py
index c76b586..c7adcc0 100755
--- a/tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakesteam.py
+++ b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakesteam.py
@@ -220,9 +220,8 @@ def cmd_run_game(q):
         # _v2-entry-point prefix, even though Steam recorded the mapping
         # (docs/sideloading.md, 2026-09-26). So does the fake, for real.
         record.update(started=True, command=full)
-        record.update(execute(full, game['directory'], {**game.get('env', {})}, f"devkit-{gameid}"))
-    with fs.update() as state:
-        state['launches'].append(record)
+        record['run'] = (full, game['directory'], {**game.get('env', {})}, f'devkit-{gameid}')
+    add_launch(record)
     console(record['message'] if not record['started'] else f'devkit run-game: started devkit game "{gameid}"')
     respond(q['response'], text='OK\n')   # guess: steam-devkit-rpc only checks that it arrives
 
@@ -232,26 +231,31 @@ DEVKIT = {'approve-ssh-key': cmd_approve_ssh_key, 'create-shortcut': cmd_create_
           'run-game': cmd_run_game}
 
 
-def execute(path, cwd, env, label):
-    """Start a program the way Steam would, and note its pid and exit status."""
-    os.makedirs(GAME_LOGS, exist_ok=True)
-    log = open(f'{GAME_LOGS}/{label}.log', 'ab')
-    try:
-        proc = subprocess.Popen([path], cwd=cwd if os.path.isdir(cwd) else HOME, env={**os.environ, **env},
-                                stdin=subprocess.DEVNULL, stdout=log, stderr=log, start_new_session=True)
-    except OSError as e:
-        return {'pid': None, 'exec_error': str(e)}
-    finally:
-        log.close()
-
-    def reap():
-        code = proc.wait()
-        with fs.update() as state:
-            for r in state['launches']:
-                if r.get('pid') == proc.pid and 'exit' not in r:
-                    r['exit'] = code
-    threading.Thread(target=reap, daemon=True).start()
-    return {'pid': proc.pid}
+def add_launch(record):
+    """Log a launch in the state. record['run'] = (path, cwd, env, log name) also starts the
+    program the way Steam would, and notes its pid and, once it ends, its exit status."""
+    run, proc = record.pop('run', None), None
+    if run:
+        path, cwd, env, label = run
+        os.makedirs(GAME_LOGS, exist_ok=True)
+        with open(f'{GAME_LOGS}/{label}.log', 'ab') as log:
+            try:
+                proc = subprocess.Popen([path], cwd=cwd if os.path.isdir(cwd) else HOME, env={**os.environ, **env},
+                                        stdin=subprocess.DEVNULL, stdout=log, stderr=log, start_new_session=True)
+                record['pid'] = proc.pid
+            except OSError as e:
+                record.update(pid=None, exec_error=str(e))
+    with fs.update() as state:              # before the reaper looks for it, however fast the program is
+        record['n'] = len(state['launches'])
+        state['launches'].append(record)
+    if proc:
+        def reap():
+            code = proc.wait()
+            with fs.update() as state:
+                mine = state['launches'][record['n']:record['n'] + 1]
+                if mine and mine[0].get('pid') == proc.pid:   # not a reset's fresh list
+                    mine[0]['exit'] = code
+        threading.Thread(target=reap, daemon=True).start()
 
 
 # ---- steam:// URLs from the `steam` wrapper ----------------------------------
@@ -271,15 +275,14 @@ def url_rungameid(gid):
             # STEAM_COMPAT_SHADER_PATH (docs/apks.md, 2026-09-25).
             env = {'SteamAppId': str(appid), 'SteamGameId': str(gid),
                    'STEAM_FOSSILIZE_DUMP_PATH': f'{fs.STEAM_ROOT}/steamapps/shadercache/{appid}/fozpipelinesv6'}
-            record.update(appid=appid, started=True, command=sc['exe'])
-            record.update(execute(sc['exe'], sc.get('start_dir') or HOME, env, f'shortcut-{appid}'))
+            record.update(appid=appid, started=True, command=sc['exe'],
+                          run=(sc['exe'], sc.get('start_dir') or HOME, env, f'shortcut-{appid}'))
     else:
         with fs.update() as state:
             app = next((a for a in state['steam']['apps'] if a['appid'] == gid), None)
         record.update(appid=gid, started=bool(app and app['installed']),
                       message=None if app and app['installed'] else 'not installed')
-    with fs.update() as state:
-        state['launches'].append(record)
+    add_launch(record)
 
 
 def url_install(appid):
diff --git a/tests/smoke/frame_smoke.py b/tests/smoke/frame_smoke.py
index 6cad662..3f16365 100644
--- a/tests/smoke/frame_smoke.py
+++ b/tests/smoke/frame_smoke.py
@@ -13,10 +13,14 @@ BUILD_ID in tests/smoke/results/<time>-<BUILD_ID>.json (git-ignored):
   (someone has to open Settings > Developer > Pair new host and approve it in
   the headset), checked, and taken out of authorized_keys again.
 
-Everything it installs is removed again, also when a step fails. Titles are
-named fc_smoke_*; leftovers from an interrupted run are removed first.
+Everything it installs is removed again, also when a step fails: the titles
+(named fc_smoke_*, and leftovers of an interrupted run first), their Steam
+shortcuts, the paired key, and ~/devkit-utils if it wasn't there before (if it
+was, it stays, synced to this checkout as Frame Control always does). A
+cleanup that fails is a failed step.
 
 Usage: python3 tests/smoke/frame_smoke.py [--pair]     (or scripts/frame-smoke.sh)
+Env:   FRAME_ALIAS (default frame), FRAME_SMOKE_RESULTS (default tests/smoke/results)
 Exit status: 0 all passed, 1 a step failed, 2 the headset isn't reachable.
 """
 import argparse
@@ -42,7 +46,7 @@ import frame_connect  # noqa: E402
 import frame_titles  # noqa: E402
 import tiny_programs  # noqa: E402
 
-RESULTS = HERE / 'results'
+RESULTS = Path(os.environ.get('FRAME_SMOKE_RESULTS') or HERE / 'results')
 PREFIX = 'fc_smoke_'
 # Earlier runs named titles fc-smoke*, which Steam refused to register but left on disk.
 OLD_PREFIX = 'fc-smoke'
@@ -110,12 +114,19 @@ def status(build):
     return {k: s.get(k) for k in ('os', 'battery', 'power', 'temp', 'services', 'volume')}
 
 
-def steam_log_lines(gid):
-    """What Steam logged about a title (log folder layout not verified; best effort)."""
-    out = ssh(f"grep -rsh -- {shlex.quote(gid)} ~/.local/share/Steam/logs/ 2>/dev/null | tail -n 12 || true")
+def steam_log_lines(*patterns):
+    """Steam log lines holding any of the fixed strings (which files: not verified, so all)."""
+    pats = ' '.join(f'-e {shlex.quote(p)}' for p in patterns)
+    out = ssh(f"grep -rshF {pats} ~/.local/share/Steam/logs/ 2>/dev/null || true")
     return out.strip().splitlines()
 
 
+# What a launch must show, per kind. The x86-64 runtime isn't installed on the
+# Frame, so Steam acknowledges that launch and logs "... is not installed"
+# instead (docs/sideloading.md, 2026-09-26): recorded, not a failure.
+EXPECTED = {'arm64': ('running',), 'x86_64': ('running', 'runtime missing'), 'exe': ('running', 'started')}
+
+
 def title_cycle(smoke, kind, folder):
     path = tiny_programs.write(folder, kind)
     gid = PREFIX + kind                 # named outright: the file names would share one id
@@ -129,10 +140,32 @@ def title_cycle(smoke, kind, folder):
         return {'id': gid, 'runtime': meta['runtime'], 'steam': meta.get('steam')}
 
     def launch():
+        mine = (f'devkit-game/{gid}', f'"{gid}"')
+        # The missing-runtime line names Steam's app id, which we don't know, so
+        # any new one counts; nothing else is launching during the test.
+        seen, seen_missing = len(steam_log_lines(*mine)), len(steam_log_lines('but is not installed'))
         frame_titles.launch(gid)       # raises unless Steam confirmed it
-        time.sleep(4)
-        procs = ssh(f"pgrep -af -- {shlex.quote('devkit-game/' + gid)} || true").strip()
-        return {'processes': procs.splitlines(), 'steam_log': steam_log_lines(gid)}
+        outcome, procs, new = 'no evidence', [], []
+        deadline = time.monotonic() + 12
+        while time.monotonic() < deadline:
+            # [d]: the pattern mustn't match the shell running pgrep, whose command line holds it.
+            procs = ssh(f"pgrep -af -- '[d]evkit-game/{gid}/' || true").strip().splitlines()
+            new = steam_log_lines(*mine)[seen:]
+            missing = steam_log_lines('but is not installed')[seen_missing:]
+            if procs:
+                outcome = 'running'
+            elif missing:
+                outcome, new = 'runtime missing', new + missing
+            elif any('started devkit game' in line or 'chdir' in line for line in new):
+                outcome = 'started'
+            if outcome != 'no evidence':
+                break
+            time.sleep(0.5)
+        detail = {'outcome': outcome, 'processes': procs, 'steam_log': new[-12:]}
+        if outcome not in EXPECTED[kind]:
+            raise AssertionError(f"Steam acknowledged the launch, but {outcome} (expected "
+                                 f"{' or '.join(EXPECTED[kind])}): {json.dumps(detail)[:400]}")
+        return detail
 
     def remove():
         frame_titles.remove(gid)
@@ -150,17 +183,60 @@ def title_cycle(smoke, kind, folder):
 
 
 def cleanup(smoke):
-    """Remove fc-smoke-* titles: this run's, and any an interrupted run left."""
+    """Remove this run's titles and any fc_smoke_* an interrupted run left: the folder,
+    its json files, and (through steamos-delete) Steam's shortcut. Raises if anything stays."""
+    problems = []
     try:
         ids = {t['id'] for t in frame_titles.list_titles() if t['id'].startswith((PREFIX, OLD_PREFIX))}
-    except frame_android.FrameError:
-        ids = set(smoke.installed)      # can't list: try what this run installed
+    except frame_android.FrameError as e:
+        ids = set()
+        problems.append(f'could not list titles: {e}')
+    ids |= smoke.installed
     for gid in sorted(ids):
         try:
-            frame_titles.remove(gid)
+            if ssh(f'test -d ~/devkit-game/{gid} && echo yes || true').strip() == 'yes':
+                frame_titles.remove(gid)
+            # Also when remove() stopped part-way, or only the json files are left.
+            ssh(f"rm -f {' '.join(f'~/devkit-game/{gid}-{k}.json' for k in ('argv', 'env', 'settings', 'framecontrol'))}")
+            if ssh(f'ls -d ~/devkit-game/{gid} ~/devkit-game/{gid}-*.json 2>/dev/null || true').strip():
+                problems.append(f'{gid} is still on the Frame')
+            else:
+                smoke.installed.discard(gid)
         except frame_android.FrameError as e:
-            print(f'  could not remove {gid}: {e}')
-    return sorted(ids)
+            problems.append(f'{gid}: {e}')
+    if ids:
+        # steamos-delete with no title only syncs Steam's shortcuts with ~/devkit-game.
+        try:
+            ssh('python3 ~/devkit-utils/steamos-delete 2>&1 || true', timeout=120)
+        except frame_android.FrameError as e:
+            problems.append(f'syncing Steam shortcuts: {e}')
+    if problems:
+        raise AssertionError('; '.join(problems))
+    return {'removed': sorted(ids)}
+
+
+# Runs on the Frame: drop the lines holding one key from authorized_keys, writing a
+# copy with the same mode and swapping it in, so a failure can't truncate the file.
+DROP_KEY = r"""
+import os, sys, tempfile
+path = os.path.expanduser('~/.ssh/authorized_keys')
+with open(path) as f:
+    lines = f.readlines()
+keep = [line for line in lines if sys.argv[1] not in line]
+if len(keep) < len(lines):
+    fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path), prefix='.authorized_keys.')
+    try:
+        with os.fdopen(fd, 'w') as f:
+            f.writelines(keep)
+            f.flush()
+            os.fsync(f.fileno())
+        os.chmod(tmp, os.stat(path).st_mode & 0o777)
+        os.replace(tmp, path)
+    except BaseException:
+        os.unlink(tmp)
+        raise
+print(len(lines) - len(keep))
+"""
 
 
 def pair(folder):
@@ -169,8 +245,8 @@ def pair(folder):
     subprocess.run(['ssh-keygen', '-q', '-t', 'rsa', '-b', '3072', '-N', '', '-C', 'frame-control-smoke',
                     '-f', key], check=True)
     pub = Path(key + '.pub').read_text()
-    host = ssh_config('hostname') or ALIAS
-    user = ssh_config('user')
+    host, user, port = ssh_config('hostname') or ALIAS, ssh_config('user'), ssh_config('port') or '22'
+    known = ssh_config('userknownhostsfile') or '~/.ssh/known_hosts'
     comment = frame_connect.key_comment(platform.node()).replace('frame-control@', 'frame-control-smoke@')
     print('    In the headset: Steam Settings > Developer > Pair new host, then approve '
           f'"{comment}" (waits up to {frame_connect.PAIRING_MODE_WAIT} s)', flush=True)
@@ -179,16 +255,21 @@ def pair(folder):
         reason = frame_connect.devkit_pair(host, pub, comment)
         if reason:
             raise AssertionError(reason)
-        r = subprocess.run(['ssh', '-o', 'BatchMode=yes', '-o', 'IdentitiesOnly=yes', '-o', 'ConnectTimeout=8',
-                            '-o', 'ControlPath=none', '-i', key, f'{user}@{host}', 'true'], capture_output=True, text=True)
+        # Only this key: no ssh_config (whose IdentityFile lines IdentitiesOnly would
+        # still offer), no agent, no passwords.
+        r = subprocess.run(['ssh', '-F', '/dev/null', '-o', 'BatchMode=yes', '-o', 'IdentitiesOnly=yes',
+                            '-o', 'IdentityAgent=none', '-o', 'PasswordAuthentication=no',
+                            '-o', 'KbdInteractiveAuthentication=no', '-o', 'ConnectTimeout=8',
+                            '-o', 'StrictHostKeyChecking=yes', '-o', f'UserKnownHostsFile={known}',
+                            '-p', port, '-i', key, f'{user}@{host}', 'true'], capture_output=True, text=True)
         if r.returncode != 0:
             raise AssertionError(f'paired, but the key does not log in: {r.stderr.strip()}')
         return {'comment': comment}
     finally:
-        f = '~/.ssh/authorized_keys'
-        ssh(f'grep -vF {b64} {f} > {f}.smoke; cat {f}.smoke > {f}; rm -f {f}.smoke')
-        if b64 in ssh(f'cat {f}'):
+        dropped = frame_android.ssh(f'python3 - {shlex.quote(b64)}', input=DROP_KEY).strip()
+        if b64 in ssh('cat ~/.ssh/authorized_keys'):
             raise AssertionError('the smoke key is still in authorized_keys')
+        print(f'    removed the smoke key from authorized_keys ({dropped} line(s))', flush=True)
 
 
 def main():
@@ -207,9 +288,10 @@ def main():
     release = os_release()
     build = release['BUILD_ID'] or 'unknown'
     print(f'==> Frame smoke test on {ALIAS}: SteamOS {release["VERSION_ID"]} ({release["VARIANT_ID"]}), build {build}')
-    left = cleanup(smoke)
-    if left:
-        print(f'  removed leftovers from an earlier run: {", ".join(left)}')
+    # Frame Control copies Valve's devkit tools to ~/devkit-utils on the first install
+    # (as Valve's client does). If they weren't there before, they go again at the end.
+    had_utils = ssh('test -d ~/devkit-utils && echo yes || true').strip() == 'yes'
+    smoke.step('cleanup: leftovers from earlier runs', cleanup, smoke)
     folder = tempfile.mkdtemp(prefix='frame-smoke-')
     try:
         smoke.step('devkit service: properties.json', properties)
@@ -219,15 +301,18 @@ def main():
         if args.pair:
             smoke.step('devkit pairing (throwaway key)', pair, folder)
     finally:
-        removed = cleanup(smoke)
+        smoke.step('cleanup: everything this run installed', cleanup, smoke)
+        if not had_utils:
+            smoke.step('cleanup: ~/devkit-utils (not there before)', ssh,
+                       'rm -rf ~/devkit-utils ~/.devkit-utils.frame-control && echo removed')
         subprocess.run(['rm', '-rf', folder])
     passed = sum(s['ok'] for s in smoke.steps)
     RESULTS.mkdir(exist_ok=True)
     out = RESULTS / f"{started.replace(':', '')}-{build}.json"
     out.write_text(json.dumps({'started': started, 'alias': ALIAS, 'os_release': release, 'paired': args.pair,
                                'passed': passed, 'failed': len(smoke.steps) - passed,
-                               'cleanup_removed': removed, 'steps': smoke.steps}, indent=1))
-    print(f'==> {passed}/{len(smoke.steps)} steps passed on build {build}; results in {out.relative_to(ROOT)}')
+                               'devkit_utils_there_before': had_utils, 'steps': smoke.steps}, indent=1))
+    print(f'==> {passed}/{len(smoke.steps)} steps passed on build {build}; results in {out}')
     return 0 if passed == len(smoke.steps) else 1
 
 
diff --git a/tests/smoke/tiny_programs.py b/tests/smoke/tiny_programs.py
index c598b15..4323d32 100644
--- a/tests/smoke/tiny_programs.py
+++ b/tests/smoke/tiny_programs.py
@@ -11,7 +11,7 @@ smoke test and the fake Frame's e2e tests install. Python stdlib only.
 """
 import struct
 
-SLEEP_SECONDS = 5
+SLEEP_SECONDS = 10
 BASE = 0x400000
 
 

From 56bbac4ddb2b27afa29f1f4195333ebacee675b6 Mon Sep 17 00:00:00 2001
From: saphid <4596216+saphid@users.noreply.github.com>
Date: Sun, 27 Sep 2026 17:27:50 +1000
Subject: [PATCH 4/7] Smoke test: wait for the evidence a launch needs; check
 the shortcut sync

A launch that needs the program running kept looking after Steam's
"started" line, rather than failing on it before the process showed up.
Cleanup reads steamos-delete's log, which reports a failed sync but exits
0, and runs it twice to check Steam no longer lists our titles; until then
they stay tracked and the cleanup step fails.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 tests/smoke/frame_smoke.py | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/tests/smoke/frame_smoke.py b/tests/smoke/frame_smoke.py
index 3f16365..14e8ff0 100644
--- a/tests/smoke/frame_smoke.py
+++ b/tests/smoke/frame_smoke.py
@@ -158,7 +158,7 @@ def title_cycle(smoke, kind, folder):
                 outcome, new = 'runtime missing', new + missing
             elif any('started devkit game' in line or 'chdir' in line for line in new):
                 outcome = 'started'
-            if outcome != 'no evidence':
+            if outcome in EXPECTED[kind]:   # else keep looking: the log can come before the process
                 break
             time.sleep(0.5)
         detail = {'outcome': outcome, 'processes': procs, 'steam_log': new[-12:]}
@@ -192,6 +192,7 @@ def cleanup(smoke):
         ids = set()
         problems.append(f'could not list titles: {e}')
     ids |= smoke.installed
+    gone = set()
     for gid in sorted(ids):
         try:
             if ssh(f'test -d ~/devkit-game/{gid} && echo yes || true').strip() == 'yes':
@@ -201,15 +202,26 @@ def cleanup(smoke):
             if ssh(f'ls -d ~/devkit-game/{gid} ~/devkit-game/{gid}-*.json 2>/dev/null || true').strip():
                 problems.append(f'{gid} is still on the Frame')
             else:
-                smoke.installed.discard(gid)
+                gone.add(gid)
         except frame_android.FrameError as e:
             problems.append(f'{gid}: {e}')
-    if ids:
+    if gone:
         # steamos-delete with no title only syncs Steam's shortcuts with ~/devkit-game.
+        # It logs a failed sync and exits 0, so read its log; a second run lists
+        # what Steam still has registered, which must not include ours.
         try:
-            ssh('python3 ~/devkit-utils/steamos-delete 2>&1 || true', timeout=120)
-        except frame_android.FrameError as e:
-            problems.append(f'syncing Steam shortcuts: {e}')
+            first = ssh('python3 ~/devkit-utils/steamos-delete 2>&1', timeout=120)
+            second = ssh('python3 ~/devkit-utils/steamos-delete 2>&1', timeout=120)
+            for out in (first, second):
+                if 'sync of devkit games failed' in out:
+                    raise AssertionError(out.strip().splitlines()[-1])
+            for gid in sorted(gone):
+                if f'registered with Steam Client: {gid!r}' in second:
+                    problems.append(f'{gid} is still registered with Steam')
+                else:
+                    smoke.installed.discard(gid)
+        except (frame_android.FrameError, AssertionError) as e:
+            problems.append(f"syncing Steam's shortcuts: {e}")
     if problems:
         raise AssertionError('; '.join(problems))
     return {'removed': sorted(ids)}

From b7681621392e771f358129d9b72f3b7118b39616 Mon Sep 17 00:00:00 2001
From: saphid <4596216+saphid@users.noreply.github.com>
Date: Sun, 27 Sep 2026 17:33:31 +1000
Subject: [PATCH 5/7] Smoke test: read Steam's binary compat log with grep -a

On the Frame, compat_log.txt has binary bytes in it, so plain grep only said
"binary file matches" and the x86-64 launch check missed Steam's "is not
installed" line. The fake now writes that line to a compat_log.txt that starts
with a NUL, and the end-to-end test finds it the way the smoke test does.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 tests/e2e/test_titles.py                            |  3 +++
 .../rootfs/usr/local/lib/fakeframe/fakesteam.py     | 13 +++++++++++++
 tests/smoke/frame_smoke.py                          |  8 ++++++--
 3 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/tests/e2e/test_titles.py b/tests/e2e/test_titles.py
index 82d0afb..a380147 100644
--- a/tests/e2e/test_titles.py
+++ b/tests/e2e/test_titles.py
@@ -123,6 +123,9 @@ class Titles(harness.FrameTestCase):
         self.assertFalse(run['started'])
         self.assertEqual(run['message'], f'Tool 4183110 "Steam Linux Runtime 4.0" is found for appID {appid}, '
                                          'but is not installed')
+        # The headset smoke test finds this in Steam's logs, where compat_log.txt has
+        # binary bytes in it: only grep -a returns the line (Frame, 2026-09-27).
+        self.assertIn(run['message'], ssh('grep -arshF "but is not installed" ~/.local/share/Steam/logs/'))
         # With the runtime installed, it starts.
         ctl('runtime', 'SteamLinuxRuntime_4', 'installed')
         ok('POST', '/api/titles', {'action': 'launch', 'id': 'Tiny_PC_Game'})
diff --git a/tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakesteam.py b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakesteam.py
index c7adcc0..7c9ee78 100755
--- a/tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakesteam.py
+++ b/tests/fakeframe/rootfs/usr/local/lib/fakeframe/fakesteam.py
@@ -40,6 +40,10 @@ HOME = fs.HOME
 STEAM_DIR = HOME + '/.steam'
 PID_FILE, TOKEN_FILE, PIPE = (f'{STEAM_DIR}/steam.{n}' for n in ('pid', 'token', 'pipe'))
 CONSOLE_LOG = fs.STEAM_ROOT + '/logs/console_log.txt'  # guess: which file Steam logs devkit launches to
+# Steam logs compat tool lookups here, and on the Frame the file has binary bytes
+# in it, so plain grep only says "binary file matches" (headset smoke test,
+# 2026-09-27, BUILD_ID 20260922.6101926). The fake starts it with a NUL to match.
+COMPAT_LOG = fs.STEAM_ROOT + '/logs/compat_log.txt'
 DEVTOOLS_PORT = 8080
 TARGET_ID = 'F0CA11ED5EA4ED0000000000000000AB'
 GAME_LOGS = '/var/log/fakeframe'
@@ -67,6 +71,14 @@ def console(line):
         f.write(time.strftime('[%Y-%m-%d %H:%M:%S] ') + line + '\n')
 
 
+def compat(line):
+    os.makedirs(os.path.dirname(COMPAT_LOG), exist_ok=True)
+    with open(COMPAT_LOG, 'ab') as f:
+        if f.tell() == 0:
+            f.write(b'\0\n')
+        f.write((time.strftime('[%Y-%m-%d %H:%M:%S] ') + line + '\n').encode())
+
+
 def respond(path, text=None, error=None):
     """Answer a devkit request the way devkit_utils.wait_on_file_response expects."""
     lock = path + '.lock'
@@ -210,6 +222,7 @@ def cmd_run_game(q):
         name = fs.RUNTIME_NAMES.get(tool, tool)
         record.update(started=False, message=f'Tool {fs.RUNTIME_APPIDS.get(tool, 0)} "{name}" is found for '
                                               f'appID {game["appid"]}, but is not installed')
+        compat(record['message'])
     elif tool and tool.startswith('proton'):
         # How Steam ran a sideloaded .exe on the Frame (docs/sideloading.md).
         prefix = f"{fs.STEAM_ROOT}/steamapps/compatdata/{game['appid']}/pfx"
diff --git a/tests/smoke/frame_smoke.py b/tests/smoke/frame_smoke.py
index 14e8ff0..740e048 100644
--- a/tests/smoke/frame_smoke.py
+++ b/tests/smoke/frame_smoke.py
@@ -115,9 +115,13 @@ def status(build):
 
 
 def steam_log_lines(*patterns):
-    """Steam log lines holding any of the fixed strings (which files: not verified, so all)."""
+    """Steam log lines holding any of the fixed strings (which files: not verified, so all).
+
+    -a: compat_log.txt has binary bytes in it, and without it grep only says
+    "binary file matches" (seen on the Frame, 2026-09-27).
+    """
     pats = ' '.join(f'-e {shlex.quote(p)}' for p in patterns)
-    out = ssh(f"grep -rshF {pats} ~/.local/share/Steam/logs/ 2>/dev/null || true")
+    out = ssh(f"grep -arshF {pats} ~/.local/share/Steam/logs/ 2>/dev/null || true")
     return out.strip().splitlines()
 
 

From 19b9bc2dbe1f99eb2886f5492141557983338c4e Mon Sep 17 00:00:00 2001
From: saphid <4596216+saphid@users.noreply.github.com>
Date: Sun, 27 Sep 2026 17:43:49 +1000
Subject: [PATCH 6/7] E2E: follow background jobs for Flatpak installs

The tabs UI (#4) runs Flatpak installs as server.start_job jobs, so a failed
install answers 200 with a job id and reports the error on /api/job. The test
now waits for the job instead of expecting an immediate 502.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 tests/e2e/harness.py     |  6 ++++++
 tests/e2e/test_device.py | 11 ++++++-----
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/tests/e2e/harness.py b/tests/e2e/harness.py
index 9a0818d..1328f96 100644
--- a/tests/e2e/harness.py
+++ b/tests/e2e/harness.py
@@ -152,6 +152,12 @@ def ok(method, path, body=None, **kw):
     return out
 
 
+def finished(started, timeout=60):
+    """Wait for a background job (server.start_job's {"job": id}); returns its final state."""
+    return wait_for(lambda: (lambda j: j['done'] and j)(ok('GET', f"/api/job?id={started['job']}")),
+                    timeout, f"job {started['job']}")
+
+
 def upload(path, mode, name=None):
     with open(path, 'rb') as f:
         data = f.read()
diff --git a/tests/e2e/test_device.py b/tests/e2e/test_device.py
index 5888ce0..e649e02 100644
--- a/tests/e2e/test_device.py
+++ b/tests/e2e/test_device.py
@@ -3,7 +3,7 @@ through the server against the fake Frame."""
 import unittest
 
 import harness
-from harness import api, ctl, launches, ok, state, wait_for
+from harness import api, ctl, finished, launches, ok, state, wait_for
 
 harness.require()
 
@@ -46,13 +46,14 @@ class Device(harness.FrameTestCase):
         self.assertEqual(state()['clipboard'], [text])
 
     def test_flatpak_install_and_remove(self):
-        ok('POST', '/api/flatpak', {'id': 'org.videolan.VLC', 'action': 'install'})
+        # Installs run as background jobs (server.start_job); uninstall answers at once.
+        job = finished(ok('POST', '/api/flatpak', {'id': 'org.videolan.VLC', 'action': 'install'}))
+        self.assertIsNone(job['error'], job)
         self.assertEqual([f['id'] for f in ok('GET', '/api/status')['flatpaks']], ['org.videolan.VLC'])
         ok('POST', '/api/flatpak', {'id': 'org.videolan.VLC', 'action': 'uninstall'})
         self.assertEqual(state()['flatpaks'], [])
-        status, out, _ = api('POST', '/api/flatpak', {'id': 'org.example.missing', 'action': 'install'})
-        self.assertEqual(status, 502)
-        self.assertIn('Nothing matches org.example.missing', out['error'])
+        job = finished(ok('POST', '/api/flatpak', {'id': 'org.example.missing', 'action': 'install'}))
+        self.assertIn('Nothing matches org.example.missing', job['error'])
 
     def test_desktop_capture(self):
         status, png, headers = api('GET', '/api/screenshot')

From e1d138470fbe30b7d582097408f2fd3b9707038a Mon Sep 17 00:00:00 2001
From: saphid <4596216+saphid@users.noreply.github.com>
Date: Sun, 27 Sep 2026 18:16:20 +1000
Subject: [PATCH 7/7] Fake Frame on arm64: use Valve's Holo Core image, and
 show failed builds

The menci/archlinuxarm base failed `pacman -Syu` on GitHub's arm64 runner.
Valve's Holo Core aarch64 preview is the base the Frame's SteamOS is built on,
the iPhone app's frame-container already uses it, and its repos carry every
package the fake needs. A failed image build now reruns with the full log.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docs/testing.md               |  2 +-
 scripts/e2e.sh                | 10 ++++++----
 tests/fakeframe/Containerfile |  6 ++++--
 3 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/docs/testing.md b/docs/testing.md
index c95ee75..b06577d 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -48,7 +48,7 @@ its guards want.
 
 | On the fake Frame | |
 |---|---|
-| Arch Linux (`archlinux:base`, or `menci/archlinuxarm:base` on arm64), user `steamos`, `/etc/os-release` with BUILD_ID 20260922.6101926 | Real OS, Frame's identity |
+| Arch Linux (`archlinux:base`, or Valve's Holo Core aarch64 preview on arm64), user `steamos`, `/etc/os-release` with BUILD_ID 20260922.6101926 | Real OS, Frame's identity |
 | `sshd` with key and password logins, `rsync`, `python3` | Real |
 | Valve's steamos-devkit-service on port 32000 and its hooks, vendored unmodified in `tests/fakeframe/steamos-devkit-service` | Real; only its `dbus` import (for mDNS through systemd-resolved) is a stand-in that logs the registration |
 | Valve's devkit-utils, copied over by Frame Control itself | Real |
diff --git a/scripts/e2e.sh b/scripts/e2e.sh
index 2c0b1ed..c8d4ef0 100755
--- a/scripts/e2e.sh
+++ b/scripts/e2e.sh
@@ -6,7 +6,7 @@
 # harness itself didn't come up). See docs/testing.md.
 #
 # Usage: scripts/e2e.sh [TEST...]     e.g. scripts/e2e.sh test_titles test_faults.Faults.test_disk_full
-# Env:   FAKEFRAME_BASE   base image (default: archlinux:base, or menci/archlinuxarm:base on arm64)
+# Env:   FAKEFRAME_BASE   base image (default: archlinux:base, or Valve's Holo Core aarch64 on arm64)
 #        FAKEFRAME_KEEP=1 leave the containers running afterwards
 set -uo pipefail
 
@@ -14,7 +14,7 @@ root=${0:A:h:h}
 cd "$root" || exit 2
 case $(uname -m) in
   x86_64|amd64) base=archlinux:base ;;
-  aarch64|arm64) base=menci/archlinuxarm:base ;;
+  aarch64|arm64) base=registry.gitlab.steamos.cloud/holo/holo-core-aarch64-preview/base-devel:latest ;;
   *) print -u2 "No Arch Linux base image known for $(uname -m); set FAKEFRAME_BASE"; exit 2 ;;
 esac
 base=${FAKEFRAME_BASE:-$base}
@@ -22,8 +22,10 @@ compose=(docker compose -p fakeframe-e2e -f tests/fakeframe/compose.yaml)
 started=$SECONDS
 
 print "==> Building fakeframe-frame (from $base) and fakeframe-host"
-docker build -q --build-arg BASE="$base" -t fakeframe-frame -f tests/fakeframe/Containerfile tests/fakeframe || exit 2
-docker build -q -t fakeframe-host -f tests/fakeframe/host.Containerfile tests/fakeframe || exit 2
+# Quiet when it works; if a build fails, build again with the full log so CI shows why.
+build() { docker build -q "$@" >/dev/null || { docker build --progress=plain "$@"; exit 2 } }
+build --build-arg BASE="$base" -t fakeframe-frame -f tests/fakeframe/Containerfile tests/fakeframe
+build -t fakeframe-host -f tests/fakeframe/host.Containerfile tests/fakeframe
 
 logs() {
   print "\n==> Fake Frame logs"
diff --git a/tests/fakeframe/Containerfile b/tests/fakeframe/Containerfile
index ce1f2e0..eeb3dc6 100644
--- a/tests/fakeframe/Containerfile
+++ b/tests/fakeframe/Containerfile
@@ -2,8 +2,10 @@
 # Valve's steamos-devkit-service and hooks, a fake Steam client and stubs for
 # the Frame-only commands Frame Control runs. See docs/testing.md.
 #
-# BASE: archlinux:base on x86_64, menci/archlinuxarm:base on arm64 (a daily
-# Arch Linux ARM build); scripts/e2e.sh picks one from `uname -m`.
+# BASE: archlinux:base on x86_64; on arm64, Valve's Holo Core aarch64 preview
+# (registry.gitlab.steamos.cloud/holo/holo-core-aarch64-preview/base-devel), the
+# Arch Linux ARM64 port the Frame's SteamOS is built on (docs/recovery-and-images.md).
+# scripts/e2e.sh picks one from `uname -m`.
 ARG BASE=archlinux:base
 FROM ${BASE}