FrameDrop: proof of concept for installing Frametop from FrameDrop (#25)

FrameDrop sideloads a Linux zip as a Steam Devkit Game. Frametop can't be
copied over as an app, so the zip holds a small installer: playing it runs
get.sh --yes in a transient user service (Steam reaps the title's process
tree on quit) and shows progress in a GTK window.

- probe/probe.sh records what a Devkit Game can reach. On SteamOS 0.3.0 it
  runs on the host with git, podman, systemd and GTK, even with the SLR4
  compat tool set; inside SLR4, flatpak-spawn --host reaches the host.
- devkit.sh registers a folder the way FrameDrop does (Valve's devkit-utils),
  for testing without a PC.
- build.sh makes a reproducible Frametop.zip and the FrameDrop manifest.

Nothing is published. Open: whether FrameDrop keeps the exec bit, and its
start command and runtime choice.

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

docs/design.md

@@ -185,6 +185,8 @@ KWin renders with OpenGL through zink on Turnip, Vulkan on the same GPU vrcompos
 
 The nested session also runs the system's XDG autostart entries, being a KDE session. Discover's update notifier started `plasma-discover --mode update` in it (520 to 620 MB resident and about 9% of a core, plus `flatpak-system-helper` and AppStream downloads), and IBus started a daemon, the kimpanel panel and its GTK extension that nothing can use: KWin hands text input to the one input method it starts (`ft-textinput`), and the session drops `QT_IM_MODULE`, `GTK_IM_MODULE` and `XMODIFIERS`. The session hides both for this desktop only, with `Hidden=true` copies in its own autostart folder. The geoclue demo agent stays: it's what answers apps' location requests to Geoclue outside GNOME, and it costs nothing while idle. Orca's entry only starts in GNOME-family desktops.
 
+Plasma 6.2.5 keeps each panel on a screen number (`lastScreen` in `plasma-org.kde.plasma.desktop-appletsrc`), and the numbers rank the enabled outputs by priority, so 0 is the primary screen. A panel whose number is past the screen count gets no view, and Plasma never moves it: the remap it runs at every start only moves a panel whose number has no desktop, and this desktop keeps a desktop for every output it has seen, spares included. So the taskbar was lost when the number of screens went down, and once it was found saved on a spare output, number 8 of a desktop with three screens ([#18](https://github.com/DeeJanuz/frametop/issues/18)). Before Plasma starts, the session runs `session/fix-panels.py`, which moves any panel numbered past the screen count, with its system tray's containment, to screen 0, keeping its widgets and settings. A panel stays put when screen 0 already has one on that edge, and comes back by itself if the screens do. The file is backed up to `<file>.ft-bak` first. Plasma's scripting can't do this while it runs (`panel.screen` is read-only in 6.2.5), so a lost taskbar comes back at the desktop's next start. `scripts/doctor.sh` and `scripts/report.sh` list the panels and their screens.
+
 Remote desktop is a chain (krdp, then FreeRDP inside Xvnc) because nothing on SteamOS serves KWin over VNC directly. Kept connected all the time, it cost about a core with nobody watching: krdpserver 55 to 78% (it encodes H.264 in software with openh264: VA-API finds no driver for the Frame's GPU in the container), FreeRDP 16 to 27%, Xvnc 6 to 11%, and the bridge's layout check every 5 seconds another 4%. krdp creates its screencast session per RDP connection and drops it when the connection closes (`SessionController::onNewConnection` in krdp 6.7), so an idle krdpserver costs nothing and can stay up; only the RDP connection has to go. The bridge connects FreeRDP when a VNC client appears and disconnects 45 seconds after the last one leaves. Xvnc has no hook for its clients, so the bridge counts established connections to its port with `ss`, woken early by Xvnc's log output; looking with `ss` once a second cost about 0.9% of a core in bash, against about 0.1% this way. `Xvnc -inetd` from a systemd socket would start a server per connection and lose sharing between viewers. The layout check (`ft-layout remote-view`, which scans `/proc` for plasmashell and runs `kscreen-doctor -j`) now runs only while FreeRDP runs, and then only after `kwinoutputconfig.json` or `frametop-layout.json` changes, with one check a minute in case a change touched neither.
 
 Program names stay within 15 characters, because Linux truncates process names there and the scripts find programs with `pgrep -x` and `pkill -x`. That's why the prefix is `ft-`.
@@ -224,6 +226,5 @@ On the Frame, SteamVR is part of the OS image (`/opt/steamvr`, the `deckard-stea
 
 - A controller button that shows the screens during a game. Games own the controllers, so this needs SteamVR input actions for ft-screens.
 - Drawing KWin's cursor on the screens.
-- Plasma can lose its panels when the number of screens goes down, because they're saved against a screen that no longer exists. Removing `plasma-org.kde.plasma.desktop-appletsrc` and `plasmashellrc` from `~/.config/frametop` brings the default panels back.
 - Frame pacing and GPU cost with several busy screens haven't been measured.
 - Real standby on a stand, with rendering and tracking paused, not just the backlight off. SteamVR has no call for it, and its activity level follows the proximity sensor.

framedrop/README.md

@@ -0,0 +1,59 @@
+# Install with FrameDrop (proof of concept)
+
+[FrameDrop](https://framedropvr.com) is a Windows app that sideloads onto a Steam Frame: it copies a build to the headset and adds it to the Steam library. Issue #25 asks for an "Install with FrameDrop" button. Frametop isn't an app FrameDrop can copy over as is: it builds in a container, installs user services and a SteamVR driver, and asks questions in a terminal. So FrameDrop installs a small installer instead. Playing "Frametop" from the library runs the one-line installer (`get.sh --yes`) and shows its progress.
+
+Nothing here is published yet: no release asset, no manifest on Pages, no button.
+
+## How FrameDrop installs a Linux zip
+
+It uses Valve's SteamOS Devkit path: pair once with the headset's devkit service, then rsync the unpacked zip into `~/devkit-game/<name>` over SSH, and register it with Steam as a Devkit Game with a start command. `devkit.sh` here makes the same calls with Valve's devkit-utils, so all of this can be tested on the Frame without a PC.
+
+## What the probe found (SteamOS 0.3.0, build 20260922.6101926)
+
+`probe/probe.sh`, started as a Devkit Game, recorded:
+
+- Devkit titles run on the host, not in a container, as user `steamos`, from a process tree that Steam's reaper owns. This held even with the compat tool set to `SteamLinuxRuntime_4-arm64`: Steam recorded the mapping and still ran it on the host.
+- On the host, everything the installer needs works: git, curl to GitHub, podman (sees the `dev` container), `systemctl --user`, `systemd-run --user`, and GTK 4 with libadwaita.
+- A GTK window opens in gamescope (an X11 window on `:1`, drawn through gamescope's Vulkan WSI).
+- Steam puts its overlay in `LD_PRELOAD` and Steam runtime paths in `LD_LIBRARY_PATH` and `PATH`. Every host tool prints a preload error unless they're cleared.
+- Inside the Steam Linux Runtime 4 container (started by hand with its `run` script), there's no git, podman, systemctl, or GTK, but `flatpak-spawn --host` runs commands on the host.
+- Steam refuses Devkit Game names with a `-` ("missing/invalid arguments").
+- Steam doesn't make the start command executable: without the exec bit, the title exits in a second and nothing runs.
+
+## The installer
+
+`installer/frametop-install.sh` is the start command.
+
+1. In the container, it starts itself again on the host with `flatpak-spawn --host`.
+2. It clears Steam's preload and library paths.
+3. It runs `curl get.sh | bash -s -- --yes` in a transient user service, `frametop-framedrop-install`, unless one is already running. The service is used because Steam ends the title's whole process tree when it's quit, and starts it with an OOM score of 900.
+4. `installer/progress.py` (GTK 4 and libadwaita) follows the service's log, shows `install.sh`'s steps as a progress bar, and reports the result. Closing it leaves the install running. Playing the title again reattaches.
+
+`--yes` keeps the version that's installed, or installs stable. It skips the parts that need sudo (our eye tracker and the Bluetooth fixes) and the SteamVR restart. The window says to restart SteamVR.
+
+`--dry-run` clones into `~/.cache/frametop-framedrop/dry-run` and stops there (`get.sh --clone-only`).
+
+## Try it on the Frame
+
+```
+framedrop/devkit.sh add FrametopTest framedrop/installer "./frametop-install.sh --dry-run"
+framedrop/devkit.sh run FrametopTest        # or Play it from the Steam library
+framedrop/devkit.sh remove FrametopTest
+framedrop/devkit.sh add FrametopProbe framedrop/probe "./probe.sh native"   # the probe
+```
+
+The probe writes `~/.cache/frametop-framedrop/probe-native.log`, and the installer writes `~/.cache/frametop-framedrop/install.log`.
+
+## Build the download
+
+```
+framedrop/build.sh [ZIP_URL]
+```
+
+This writes `framedrop/build/Frametop.zip` (reproducible) and `frametop.framedrop.json`, FrameDrop's manifest with the zip's sha256. By default, `ZIP_URL` points at a `framedrop-installer` release asset. The button's link would be `https://framedropvr.com/install?manifest=https://deejanuz.github.io/frametop/frametop.framedrop.json`, with the manifest committed to main for Pages.
+
+## Open questions, for a test with FrameDrop on a Windows PC
+
+- Does FrameDrop keep or set the exec bit on `frametop-install.sh`? A zip unpacked on Windows loses it, and without it nothing runs.
+- What start command does FrameDrop pick for this zip, and which runtime?
+- Does the manifest's `name` become the Devkit Game name? It has to stay free of `-`.

framedrop/build.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Build the FrameDrop download: framedrop/build/Frametop.zip (the installer in a "Frametop"
+# folder) and framedrop/build/frametop.framedrop.json, the manifest an "Install with
+# FrameDrop" button points at. The zip is reproducible: same files, same sha256.
+#
+# Usage: framedrop/build.sh [ZIP_URL]
+#   ZIP_URL  where the zip will be downloaded from (default: the framedrop-installer release)
+set -euo pipefail
+
+here=$(cd "$(dirname "$0")" && pwd)
+url=${1:-https://github.com/DeeJanuz/frametop/releases/download/framedrop-installer/Frametop.zip}
+out=$here/build
+mkdir -p "$out"
+
+python3 - "$here/installer" "$out/Frametop.zip" <<'EOF'
+import os, sys, zipfile
+src, dest = sys.argv[1:]
+with zipfile.ZipFile(dest, "w", zipfile.ZIP_DEFLATED) as z:
+    for name in ("frametop-install.sh", "progress.py"):
+        info = zipfile.ZipInfo(f"Frametop/{name}", date_time=(2026, 1, 1, 0, 0, 0))
+        info.create_system = 3  # unix, so the permissions below count
+        info.external_attr = (0o100755 if os.access(os.path.join(src, name), os.X_OK) else 0o100644) << 16
+        info.compress_type = zipfile.ZIP_DEFLATED
+        with open(os.path.join(src, name), "rb") as f:
+            z.writestr(info, f.read())
+EOF
+
+sha=$(sha256sum "$out/Frametop.zip" | cut -d' ' -f1)
+python3 - "$url" "$sha" >"$out/frametop.framedrop.json" <<'EOF'
+import json, sys
+url, sha = sys.argv[1:]
+print(json.dumps({
+    "schema": "framedrop.install/v1",
+    "name": "Frametop",
+    "files": [{"url": url, "sha256": sha}],
+}, indent=2))
+EOF
+echo "built $out/Frametop.zip ($sha)"
+echo "      $out/frametop.framedrop.json"

framedrop/devkit.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Do on the Frame what FrameDrop does from a PC: copy a folder into ~/devkit-game/NAME and
+# register it with Steam as a "Devkit Game" (Valve's devkit-utils, the same calls FrameDrop and
+# the SteamOS Devkit Client make over SSH). For testing the FrameDrop installer and the probe
+# without a PC. Steam must be running, and Developer Mode on.
+#
+# Usage: devkit.sh add NAME DIR COMMAND [--compat TOOL]
+#        devkit.sh run NAME       # start it, as the library's Play button does
+#        devkit.sh remove NAME    # delete the folder and the Steam entry
+#        devkit.sh list
+#
+# NAME can't contain "-": Steam answers "missing/invalid arguments". COMMAND is relative to
+# the folder, like FrameDrop's start command ("./probe.sh native"). --compat sets the runtime
+# (SteamLinuxRuntime_4-arm64, say); on SteamOS 0.3.0 Steam recorded it but still ran the
+# title on the host. There's no environment option: this Steam ignores the devkit env file.
+#
+# devkit-utils is Valve's (LGPL, gitlab.steamos.cloud/devkit/steamos-devkit). FrameDrop and
+# the devkit client copy it to ~/devkit-utils; if that isn't there, it's fetched at a pinned
+# commit into ~/.cache/frametop-framedrop.
+set -euo pipefail
+
+devkit_rev=a00ceb7d91ea44a0c3e714a91a06417d6e5cdb33
+cache=$HOME/.cache/frametop-framedrop
+
+usage() { sed -n '7,10p' "$0" | sed 's/^# \{0,1\}//' >&2; exit 2; }
+
+utils() {
+  if [ -e "$HOME/devkit-utils/steam-client-create-shortcut" ]; then
+    echo "$HOME/devkit-utils"; return
+  fi
+  if [ ! -e "$cache/devkit-utils/steam-client-create-shortcut" ]; then
+    echo "fetching devkit-utils ($devkit_rev)" >&2
+    local tmp
+    tmp=$(mktemp -d)
+    git -C "$tmp" init -q
+    git -C "$tmp" fetch -q --depth 1 https://gitlab.steamos.cloud/devkit/steamos-devkit.git "$devkit_rev"
+    git -C "$tmp" checkout -q FETCH_HEAD
+    mkdir -p "$cache"
+    rm -rf "$cache/devkit-utils"
+    cp -r "$tmp/client/devkit-utils" "$cache/devkit-utils"
+    rm -rf "$tmp"
+  fi
+  echo "$cache/devkit-utils"
+}
+
+[ $# -ge 1 ] || usage
+cmd=$1; shift
+case $cmd in
+  add)
+    [ $# -ge 3 ] || usage
+    name=$1 src=$2 start=$3; shift 3
+    case $name in *-*) echo "NAME can't contain '-' (Steam refuses it)" >&2; exit 2 ;; esac
+    compat=
+    while [ $# -gt 0 ]; do
+      case $1 in
+        --compat) compat=${2:?}; shift ;;
+        *) usage ;;
+      esac
+      shift
+    done
+    u=$(utils)
+    dir=$(python3 "$u/steamos-prepare-upload" --gameid "$name" | python3 -c 'import json,sys; print(json.load(sys.stdin)["directory"])')
+    # FrameDrop rsyncs the unpacked zip; --delete as a clean upload would.
+    rsync -a --delete "$src/" "$dir/"
+    parms=$(python3 - "$name" "$dir" "$start" "$compat" <<'EOF'
+import json, sys
+name, directory, start, compat = sys.argv[1:]
+print(json.dumps({
+    "gameid": name, "directory": directory,
+    "argv": [start], "env": {},
+    "settings": {"steam_play": "0", "compat_tool": compat},
+    "force_appid": "", "lepton_args": "",
+}))
+EOF
+)
+    res=$(python3 "$u/steam-client-create-shortcut" --parms "$parms" | tail -1)
+    echo "Steam: $res"
+    case $res in *'"error"'*) exit 1 ;; esac
+    echo "registered $name ($dir)"
+    ;;
+  run)
+    [ $# -eq 1 ] || usage
+    python3 "$(utils)/steam-devkit-rpc" run-game "gameid=$1" | tail -1
+    echo
+    ;;
+  remove)
+    [ $# -eq 1 ] || usage
+    python3 "$(utils)/steamos-delete" --delete-title "$1"
+    rm -f "$HOME/devkit-game/$1"-*.json
+    ;;
+  list)
+    python3 "$(utils)/steam-devkit-rpc" list-shortcuts
+    ;;
+  *) usage ;;
+esac

framedrop/installer/frametop-install.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Frametop's FrameDrop installer: the start command of the "Frametop" title that FrameDrop
+# puts in the Steam library. Playing it installs Frametop (or updates it) with the one-line
+# installer, get.sh --yes, and shows its progress in a window.
+#
+# Steam ends a title's whole process tree when it's quit, and starts it with a high OOM score,
+# so the install runs in a user service of its own (frametop-framedrop-install) and the window
+# only follows its log. Quitting or closing the window leaves the install running; playing the
+# title again reattaches to it.
+#
+# Usage: frametop-install.sh [--dry-run]
+#   --dry-run  clone into ~/.cache/frametop-framedrop/dry-run instead of ~/frametop, and
+#              don't run install.sh (get.sh --clone-only), for testing this flow
+set -u
+
+here=$(cd "$(dirname "$0")" && pwd)
+self=$here/$(basename "$0")
+
+# A Linux title can be started in the Steam Linux Runtime container, which has no git, podman,
+# systemctl, or GTK. Start this again on the host. (SteamOS 0.3.0 runs devkit titles on the
+# host anyway; this is for when FrameDrop or Steam picks the runtime.)
+if [ -e /run/pressure-vessel ]; then
+  exec flatpak-spawn --host --watch-bus --env=DISPLAY="${DISPLAY-}" \
+    --env=XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR-}" --env=SteamAppId="${SteamAppId-}" \
+    --env=ENABLE_GAMESCOPE_WSI="${ENABLE_GAMESCOPE_WSI-}" /usr/bin/bash "$self" "$@"
+fi
+
+# Steam adds its overlay and runtime libraries to every child; host tools don't want them.
+unset LD_PRELOAD LD_LIBRARY_PATH
+export PATH=/usr/local/bin:/usr/bin:/bin
+
+dry_run=0
+[ "${1-}" = --dry-run ] && dry_run=1
+
+unit=frametop-framedrop-install
+state=$HOME/.cache/frametop-framedrop
+log=$state/install.log
+mkdir -p "$state"
+
+get_args="--yes"
+[ "$dry_run" = 1 ] && get_args="--yes --clone-only --dir $state/dry-run"
+
+# Start the install unless one is running already. RemainAfterExit keeps its result for the
+# window; the next start clears it.
+if [ "$(systemctl --user show -P ActiveState "$unit" 2>/dev/null)" != activating ]; then
+  systemctl --user stop "$unit" 2>/dev/null
+  systemctl --user reset-failed "$unit" 2>/dev/null
+  : >"$log"
+  systemd-run --user --unit="$unit" --description="Frametop install (FrameDrop)" \
+    --property=Type=oneshot --property=RemainAfterExit=yes \
+    --property=StandardOutput="truncate:$log" --property=StandardError=inherit \
+    --setenv=HOME="$HOME" --setenv=PATH="$PATH" --setenv=TERM=dumb \
+    --working-directory="$HOME" --quiet --no-block \
+    /usr/bin/bash -c 'set -o pipefail; curl -fsSL https://deejanuz.github.io/frametop/get.sh | bash -s -- '"$get_args" ||
+    { echo "couldn't start the install service" >&2; exit 1; }
+fi
+
+exec /usr/bin/python3 "$here/progress.py" "$unit" "$log"

framedrop/installer/progress.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Progress window for the FrameDrop installer: follows the install service's log and state.
+
+Usage: progress.py UNIT LOG
+
+Closing the window doesn't stop the install; it keeps running in the user service UNIT.
+"""
+import re
+import subprocess
+import sys
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+gi.require_version("Adw", "1")
+from gi.repository import Adw, GLib, Gtk, Pango  # noqa: E402
+
+UNIT, LOG = sys.argv[1], sys.argv[2]
+ANSI = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
+# install.sh marks each step with "== N/10 what it is"
+STEP = re.compile(r"^== (\d+)/(\d+) (.*)$")
+DONE_TEXT = ("Frametop is installed. Restart SteamVR once, or reboot the headset, so it loads "
+             "Frametop's driver. Then open Launch a program, then Desktop.")
+
+
+def unit_state():
+    out = subprocess.run(
+        ["systemctl", "--user", "show", "-P", "ActiveState", UNIT],
+        capture_output=True, text=True).stdout.strip()
+    return out or "inactive"
+
+
+class Window(Adw.ApplicationWindow):
+    def __init__(self, app):
+        super().__init__(application=app, title="Frametop")
+        self.set_default_size(900, 600)
+        self.offset = 0
+        self.partial = ""
+
+        self.status = Gtk.Label(label="Installing Frametop", xalign=0, wrap=True)
+        self.status.add_css_class("title-2")
+        self.detail = Gtk.Label(label="Starting...", xalign=0, wrap=True)
+        self.bar = Gtk.ProgressBar()
+        self.bar.pulse()
+
+        self.text = Gtk.TextView(editable=False, cursor_visible=False, monospace=True,
+                                 wrap_mode=Pango.WrapMode.WORD_CHAR)
+        self.text.set_left_margin(8)
+        self.text.set_right_margin(8)
+        scroll = Gtk.ScrolledWindow(vexpand=True, child=self.text)
+        self.scroll = scroll
+
+        self.note = note = Gtk.Label(
+            label="You can close this window: the install keeps going. Play Frametop again to "
+                  "come back to it.", xalign=0, wrap=True)
+        note.add_css_class("dim-label")
+        close = Gtk.Button(label="Close", halign=Gtk.Align.END)
+        close.connect("clicked", lambda *_: self.close())
+
+        box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=12,
+                      margin_top=18, margin_bottom=18, margin_start=18, margin_end=18)
+        for w in (self.status, self.detail, self.bar, scroll, note, close):
+            box.append(w)
+        view = Adw.ToolbarView(content=box)
+        view.add_top_bar(Adw.HeaderBar())
+        self.set_content(view)
+
+        self.finished = False
+        GLib.timeout_add(500, self.tick)
+        self.tick()
+
+    def add_lines(self, lines):
+        buf = self.text.get_buffer()
+        for line in lines:
+            m = STEP.match(line)
+            if m:
+                n, total, what = int(m[1]), int(m[2]), m[3]
+                self.bar.set_fraction((n - 1) / total)
+                self.detail.set_label(f"Step {n} of {total}: {what}")
+            buf.insert(buf.get_end_iter(), line + "\n")
+        # Keep the view at the newest line.
+        end = buf.create_mark(None, buf.get_end_iter(), False)
+        self.text.scroll_mark_onscreen(end)
+        buf.delete_mark(end)
+
+    def tick(self):
+        try:
+            with open(LOG, "rb") as f:
+                f.seek(self.offset)
+                data = f.read()
+                self.offset += len(data)
+        except FileNotFoundError:
+            data = b""
+        if data:
+            text = self.partial + ANSI.sub("", data.decode("utf-8", "replace")).replace("\r", "\n")
+            *lines, self.partial = text.split("\n")
+            self.add_lines(lines)
+
+        state = unit_state()
+        if state == "activating":
+            if self.bar.get_fraction() == 0:
+                self.bar.pulse()
+            return True
+        if self.partial:
+            self.add_lines([self.partial])
+            self.partial = ""
+        self.note.set_visible(False)
+        if state == "active":
+            self.status.set_label("Done")
+            self.detail.set_label(DONE_TEXT)
+            self.bar.set_fraction(1)
+        else:
+            self.status.set_label("The install stopped")
+            self.detail.set_label("The log above says why. Play Frametop again to try again.")
+        return False
+
+
+def main():
+    app = Adw.Application(application_id="io.github.deejanuz.FrametopInstall")
+    app.connect("activate", lambda a: Window(a).present())
+    app.run([])
+
+
+if __name__ == "__main__":
+    main()

framedrop/probe/probe.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# FrameDrop proof of concept, step 1: run as a Steam "Devkit Game" (what FrameDrop installs a
+# Linux zip as) and record what an installer started from Steam could use: host or Steam Linux
+# Runtime container, podman, the user's systemd, git, the network, GTK, and a window on screen.
+# Register and start it: framedrop/devkit.sh add FrametopProbe framedrop/probe "./probe.sh native"
+#                       framedrop/devkit.sh run FrametopProbe
+# Usage: probe.sh LABEL
+# Writes ~/.cache/frametop-framedrop/probe-LABEL.log, replacing the previous one.
+label=${1:-unlabeled}
+out=$HOME/.cache/frametop-framedrop
+mkdir -p "$out"
+log=$out/probe-$label.log
+exec >"$log" 2>&1
+
+here=$(cd "$(dirname "$0")" && pwd)
+section() { printf '\n== %s\n' "$1"; }
+have() { command -v "$1" >/dev/null 2>&1; }
+check() { # check NAME CMD...: one line, ok or failed with the exit status
+  local name=$1; shift
+  if out_=$(timeout 20 "$@" 2>&1); then echo "ok      $name: $(echo "$out_" | head -1)"
+  else echo "FAILED  $name (exit $?): $(echo "$out_" | head -2 | tr '\n' ' ')"; fi
+}
+
+section "when, who, where"
+date -Is
+echo "label=$label uid=$(id -u) user=$(id -un) pwd=$PWD here=$here"
+echo "args: $*"
+grep -E '^(ID|VARIANT_ID|VERSION_ID|BUILD_ID|PRETTY_NAME)=' /etc/os-release
+
+section "container?"
+for p in /run/pressure-vessel /.flatpak-info /run/host/os-release; do
+  [ -e "$p" ] && echo "present: $p" || echo "absent:  $p"
+done
+echo "container=${container-} PRESSURE_VESSEL_RUNTIME=${PRESSURE_VESSEL_RUNTIME-}"
+[ -e /run/host/os-release ] && grep -E '^(ID|VARIANT_ID)=' /run/host/os-release
+
+section "environment"
+env | grep -E '^(PATH|HOME|XDG_[A-Z_]+|DISPLAY|WAYLAND_DISPLAY|DBUS_SESSION_BUS_ADDRESS|SteamAppId|SteamGameId|STEAM_COMPAT_[A-Z_]+|LD_LIBRARY_PATH|LD_PRELOAD|SDL_[A-Z_]+|GDK_BACKEND|ENABLE_[A-Z_]+|PRESSURE_VESSEL_[A-Z_]+)=' | sort
+echo "process tree:"
+pid=$$
+for _ in 1 2 3 4 5 6 7 8; do
+  [ "$pid" -le 1 ] 2>/dev/null && break
+  printf '  %s %s\n' "$pid" "$(tr '\0' ' ' </proc/"$pid"/cmdline 2>/dev/null | cut -c1-200)"
+  pid=$(awk '/^PPid:/{print $2}' /proc/"$pid"/status 2>/dev/null)
+done
+
+# Steam adds its overlay (LD_PRELOAD) and runtime libraries to every child. An installer has
+# to drop them before running host tools, as the checks below do.
+unset LD_PRELOAD
+LD_LIBRARY_PATH=$(printf %s "${LD_LIBRARY_PATH-}" | tr ':' '\n' | grep -v -e '/Steam/' -e '^$' -e 'x86_64' -e 'i386' | paste -sd:)
+[ -n "$LD_LIBRARY_PATH" ] && export LD_LIBRARY_PATH || unset LD_LIBRARY_PATH
+PATH=$(printf %s "$PATH" | tr ':' '\n' | grep -v '/Steam/' | paste -sd:)
+echo "cleaned: PATH=$PATH LD_LIBRARY_PATH=${LD_LIBRARY_PATH-}"
+
+section "tools"
+for t in bash git curl python3 podman distrobox systemctl systemd-run busctl gdbus flatpak-spawn \
+         steam-runtime-launch-client konsole zenity kdialog; do
+  printf '%-28s %s\n' "$t" "$(command -v "$t" || echo -)"
+done
+
+section "what an installer needs"
+check "home writable" sh -c 'f=$HOME/.cache/frametop-framedrop/.w && : >"$f" && rm "$f" && echo yes'
+check "~/frametop visible" sh -c 'ls -d "$HOME/frametop" && git -C "$HOME/frametop" log -1 --format=%h'
+have git && check "git ls-remote github" git ls-remote --heads https://github.com/DeeJanuz/frametop.git experimental
+have curl && check "curl get.sh" sh -c 'curl -fsSL https://deejanuz.github.io/frametop/get.sh | head -1'
+have podman && check "podman ps" podman ps --format '{{.Names}}'
+have distrobox && check "distrobox list" distrobox list
+have systemctl && check "systemctl --user" systemctl --user is-system-running
+have systemctl && check "user units visible" systemctl --user is-enabled frametop-input-relay.service
+have python3 && check "python3 gi Gtk 4" python3 -c 'import gi; gi.require_version("Gtk","4.0"); gi.require_version("Adw","1"); from gi.repository import Gtk, Adw; print(Gtk.get_major_version(), Gtk.get_minor_version())'
+
+section "escape to the host (needed if this is a container)"
+# A transient user unit runs in the host's user manager, outside any container.
+if have systemd-run; then
+  rm -f "$out/escape-$label"
+  check "systemd-run --user" systemd-run --user --wait --collect --quiet -- \
+    sh -c "grep -E '^(ID|VARIANT_ID)=' /etc/os-release > '$out/escape-$label'; command -v podman git >> '$out/escape-$label'"
+  [ -s "$out/escape-$label" ] && sed 's/^/  host says: /' "$out/escape-$label"
+fi
+if have busctl; then
+  check "busctl --user (systemd1)" busctl --user get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Version
+fi
+
+section "window"
+# A plain GTK 4 window for 20 s. Watch for it on the Frame; "window: mapped" means GTK showed it.
+if have python3; then
+  timeout 40 python3 - <<'EOF'
+import sys
+try:
+    import gi
+    gi.require_version("Gtk", "4.0")
+    from gi.repository import Gtk, GLib
+except Exception as e:
+    print("window: no GTK 4:", e); sys.exit(0)
+app = Gtk.Application(application_id="io.github.deejanuz.FrametopProbe")
+def on_activate(app):
+    w = Gtk.ApplicationWindow(application=app, title="Frametop installer probe")
+    w.set_default_size(640, 240)
+    w.set_child(Gtk.Label(label="Frametop installer probe\n\nIf you can read this, a FrameDrop install can show progress.\nThis window closes in 20 seconds."))
+    w.connect("map", lambda *_: print("window: mapped", flush=True))
+    w.present()
+    GLib.timeout_add_seconds(20, app.quit)
+app.connect("activate", on_activate)
+print("window: display", Gtk.Widget.get_display(Gtk.Label()) if hasattr(Gtk.Widget, "get_display") else "?", flush=True)
+app.run([])
+print("window: closed")
+EOF
+  echo "window exit: $?"
+else
+  echo "window: no python3"
+fi
+
+section "done"
+date -Is

screens/vr.cpp

@@ -1409,6 +1409,7 @@ struct Press {
     double x = 0, y = 0;                      // ...and where on it, in buffer pixels
     double distance = 1;                      // from the laser's start to the last panel it met
     long upAt = -1;                           // the pointer helper saw left come up: release it at this tick
+    int64_t idleSince = -1;                   // the pressing controller has held nothing since (ms, ReleaseStuck)
 };
 Press g_press;
 vr::VROverlayHandle_t g_catcher = vr::k_ulOverlayHandleInvalid;
@@ -1445,6 +1446,47 @@ void ReleaseAway(uint32_t button, void (*handle)(const struct ft_event *, void *
     handle(&e, data);
 }
 
+// Whether a hand controller holds anything (a button down): 1 yes, 0 no, -1 unknown. SteamVR
+// answers overlay apps only while a VR game runs (checked 2026-10-04); outside games it can't
+// say. The Frame controller's axes have no types, so the buttons are all there is.
+int ControllerHolds(vr::TrackedDeviceIndex_t dev) {
+    vr::VRControllerState_t st{};
+    if (!vr::VRSystem()->GetControllerState(dev, &st, sizeof st)) return -1;
+    return st.ulButtonPressed ? 1 : 0;
+}
+
+// Releases SteamVR never sends. Pausing, or hiding the screen a button went down on, takes the
+// laser off it mid-click (the pause gesture's second thumbstick click does that), and SteamVR's
+// laser mouse then forgets the button: no release comes, the catcher stayed up, and the game
+// never got its controllers back (2026-10-04). So a held button is released here when it has
+// no visible screen to come up on, or when its hand controller has held nothing for kStuckMs
+// (only known during VR games, where the lost release took the game's controllers).
+// The pointer helper's virtual controller has its own word for that ("up").
+constexpr int64_t kStuckMs = 1000;
+void ReleaseStuck(void (*handle)(const struct ft_event *, void *), void *data) {
+    if (!g_press.buttons) {
+        g_press.idleSince = -1;
+        return;
+    }
+    const char *why = nullptr;
+    const auto it = g_screens.find(g_press.screen);
+    if (g_paused) why = "paused";
+    else if (g_press.screen >= 0 && (it == g_screens.end() || !it->second.visible)) why = "its screen hid";
+    else if (IsHandController(g_press.device)) {
+        const int64_t now = NowMs();
+        if (ControllerHolds(g_press.device) != 0) g_press.idleSince = -1;
+        else if (g_press.idleSince < 0) g_press.idleSince = now;
+        else if (now - g_press.idleSince >= kStuckMs) why = "the controller holds nothing";
+    }
+    if (!why) return;
+    std::printf("a held button can't come up on a screen (%s): released\n", why);
+    const vr::TrackedDeviceIndex_t dev = g_press.device;
+    for (uint32_t b = 0; b < 32; ++b)
+        if (g_press.buttons & (1u << b)) ReleaseAway(BTN_LEFT + b, handle, data);
+    g_press.buttons = 0, g_press.upAt = -1, g_press.idleSince = -1;
+    EndDragsBy(dev);
+}
+
 void ShowCatcher(bool on) {
     if (on == g_catcherShown || g_catcher == vr::k_ulOverlayHandleInvalid) return;
     g_catcherShown = on;
@@ -2232,6 +2274,7 @@ void ft_vr_poll(void (*handle)(const struct ft_event *, void *), void *data) {
         if (ev.eventType == vr::VREvent_MouseButtonUp)
             ReleaseAwayBy(ev.trackedDeviceIndex, ev.data.mouse.button, handle, data);
     if (g_press.upAt >= 0 && g_tick >= g_press.upAt) ReleaseAway(BTN_LEFT, handle, data);
+    ReleaseStuck(handle, data);
     RefreshChrome();
     while (vr::VRSystem()->PollNextEvent(&ev, sizeof ev)) {
         if (ev.eventType == vr::VREvent_Quit) {

scripts/doctor.sh

@@ -36,6 +36,10 @@ check "distrobox" on_frame 'test -x ~/.local/bin/distrobox && ~/.local/bin/distr
 check "container $FRAME_BOX" on_frame "podman ps -a --filter name=^$FRAME_BOX\$ --format '{{.Image}} {{.Status}}' | grep ."
 check "repo on the Frame" on_frame 'pwd'
 check "free space in ~" on_frame "df -h ~ | awk 'NR==2{print \$4\" free\"}'"
+# A taskbar saved on a screen the desktop doesn't have is hidden; the desktop's next start
+# moves it to the first screen (session/fix-panels.py).
+check "taskbar on a screen" on_frame 'set -o pipefail; [ -f session/fix-panels.py ] || { echo "not checked (older checkout)"; exit 0; }
+  python3 session/fix-panels.py --check | paste -sd ";" | sed "s/;/; /g"'
 
 echo "what Frametop needs from SteamOS:"
 if [ "$FRAME_LOCAL" = 1 ]; then

scripts/report.sh

@@ -42,6 +42,25 @@ for i, s in enumerate(d.get("screens", []), 1):
 print("visibility:", d.get("visibility"))
 PY
 
+section "Plasma panels and outputs"
+python3 "$repo/session/fix-panels.py" --check 2>&1 || true
+python3 - "$repo" <<'PY' 2>&1 || true
+import json, subprocess, sys
+sys.path.insert(0, sys.argv[1] + "/layout")
+import ft_layout
+env = ft_layout.nested_env()
+if not env:
+    sys.exit(print("desktop not running: no live outputs or panels"))
+outs = json.loads(subprocess.run(["kscreen-doctor", "-j"], capture_output=True, text=True, env=env, timeout=10).stdout or "{}")
+for o in outs.get("outputs", []):
+    size = o.get("size") or {}
+    print(f"output {o.get('name')}: enabled={o.get('enabled')} priority={o.get('priority')} {size.get('width')}x{size.get('height')}")
+js = "print(JSON.stringify(panels().map(p => ({id: p.id, screen: p.screen, location: p.location}))))"
+r = subprocess.run(["qdbus6", "org.kde.plasmashell", "/PlasmaShell", "org.kde.PlasmaShell.evaluateScript", js],
+                   capture_output=True, text=True, env=env, timeout=10)
+print("live panels:", (r.stdout or r.stderr).strip())
+PY
+
 section "Input relay (last 60 lines)"
 journalctl --user -u frametop-input-relay -n 60 --no-pager -o short 2>/dev/null
 section "Pointer helper (last 60 lines)"

session/fix-panels.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Bring back a taskbar that Plasma saved against a screen this desktop doesn't have.
+
+Plasma 6.2.5 ties each panel to a screen number (lastScreen in its containment), and the
+numbers rank the enabled outputs by priority: 0 is the primary screen. A panel whose
+number is past the screen count gets no view and stays hidden; Plasma never moves it,
+even on a later start (sanitizeScreenLayout() only remaps a panel whose number has no
+desktop, and the Frametop desktop keeps a desktop for every spare output it has seen).
+So a taskbar saved on a spare output (issue #18), or on a screen that a smaller layout
+dropped, was lost until the config was deleted.
+
+The session runs this before Plasma starts, so nothing races Plasma for the file. Each
+panel numbered at or past the screen count moves to screen 0, with its system tray's
+containment, and keeps its widgets and settings. A panel is left where it is when screen
+0 already has a panel on that edge: it comes back by itself if the screens do. The file
+is backed up once per repair (<file>.ft-bak), and the changes go through kwriteconfig6.
+
+  fix-panels.py [--screens N] [--file APPLETSRC] [--check]
+    --screens  the desktop's screen count (default: the configured layout's)
+    --file     default: $XDG_CONFIG_HOME/plasma-org.kde.plasma.desktop-appletsrc, with
+               XDG_CONFIG_HOME defaulting to the Frametop desktop's ~/.config/frametop
+    --check    change nothing; list the panels, and exit 1 if one is lost
+"""
+import argparse
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+EDGES = {3: "top", 4: "bottom", 5: "left", 6: "right"}  # Plasma::Types::Location
+SYSTRAY = "org.kde.plasma.private.systemtray"
+GROUP = re.compile(r"\[([^\]]*)\]")
+
+
+def parse(text):
+    """KConfig text -> {(group, subgroup, ...): {key: value}}."""
+    groups, cur = {}, None
+    for line in text.splitlines():
+        line = line.strip()
+        if line.startswith("["):
+            cur = tuple(GROUP.findall(line))
+            groups.setdefault(cur, {})
+        elif cur is not None and "=" in line and not line.startswith("#"):
+            k, v = line.split("=", 1)
+            groups[cur][re.sub(r"\[\$.*\]$", "", k.strip())] = v.strip()
+    return groups
+
+
+def number(v, default=-1):
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return default
+
+
+def panels(groups):
+    """The panels, by containment id: location, lastScreen, and the ids of their system
+    trays' own containments (which sit on the same edge and screen as the panel)."""
+    trays, found = {}, {}
+    for g, keys in groups.items():
+        if len(g) == 5 and g[0] == "Containments" and g[2] == "Applets" and g[4] == "Configuration":
+            tray = keys.get("SystrayContainmentId")
+            if tray:
+                trays.setdefault(g[1], []).append(tray)
+    owned = {t for ts in trays.values() for t in ts}
+    for g, keys in groups.items():
+        if len(g) != 2 or g[0] != "Containments" or number(g[1]) <= 0 or g[1] in owned:
+            continue
+        loc = number(keys.get("location"), 0)
+        if loc in EDGES and keys.get("plugin") != SYSTRAY:
+            found[g[1]] = {"location": loc, "screen": number(keys.get("lastScreen")),
+                           "plugin": keys.get("plugin", "?"), "trays": trays.get(g[1], [])}
+    return dict(sorted(found.items(), key=lambda kv: number(kv[0])))
+
+
+def plan(groups, screens):
+    """(moves, kept): moves are (panel id, from screen, containment ids to put on screen 0);
+    kept are (panel id, from screen, why) for lost panels left alone."""
+    found = panels(groups)
+    taken = {(p["screen"], p["location"]) for p in found.values() if 0 <= p["screen"] < screens}
+    moves, kept = [], []
+    for pid, p in found.items():
+        if p["screen"] < screens:
+            continue  # on a screen this desktop has (Plasma puts -1 on the first one itself)
+        if (0, p["location"]) in taken:
+            kept.append((pid, p["screen"], f"the first screen already has a {EDGES[p['location']]} panel"))
+            continue
+        taken.add((0, p["location"]))
+        moves.append((pid, p["screen"], [pid, *p["trays"]]))
+    return moves, kept
+
+
+def default_screens():
+    sys.path.insert(0, os.path.join(os.path.dirname(os.path.realpath(__file__)), "..", "layout"))
+    import ft_layout
+    return ft_layout.screen_count()
+
+
+def main(argv):
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("--screens", type=int)
+    ap.add_argument("--file")
+    ap.add_argument("--check", action="store_true")
+    a = ap.parse_args(argv)
+    config = os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config/frametop")
+    path = a.file or os.path.join(config, "plasma-org.kde.plasma.desktop-appletsrc")
+    screens = a.screens if a.screens else default_screens()
+    try:
+        with open(path) as f:
+            groups = parse(f.read())
+    except FileNotFoundError:
+        if a.check:
+            print("no Plasma config yet (Plasma makes the default taskbar)")
+        return 0
+    moves, kept = plan(groups, screens)
+
+    if a.check:
+        found = panels(groups)
+        for pid, p in found.items():
+            lost = " (lost: no such screen)" if p["screen"] >= screens else ""
+            print(f"panel {pid}: screen {p['screen']}, {EDGES[p['location']]}{lost}")
+        if not found:
+            print("no panels")
+        print(f"{screens} screen(s)")
+        return 1 if moves or kept else 0
+
+    if moves:
+        shutil.copy2(path, path + ".ft-bak")
+    for pid, was, ids in moves:
+        for cid in ids:
+            subprocess.run(["kwriteconfig6", "--file", os.path.abspath(path), "--group", "Containments",
+                            "--group", cid, "--key", "lastScreen", "0"], check=True)
+        print(f"frametop: panel {pid} was saved on screen {was}, which this desktop doesn't have "
+              f"({screens} screen(s)); moved it to the first screen (backup: {path}.ft-bak)", file=sys.stderr)
+    for pid, was, why in kept:
+        print(f"frametop: panel {pid} is saved on screen {was}, which this desktop doesn't have; "
+              f"left there: {why}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

session/frametop-session.sh

@@ -272,4 +272,9 @@ fi
 # with both, apps would open twice.
 kwriteconfig6 --file "$XDG_CONFIG_HOME/ksmserverrc" --group General --key loginMode emptySession
 
+# Plasma keeps a panel on a screen number, and never moves one whose screen this desktop
+# doesn't have, like a spare output or a screen a smaller layout dropped. Put such a panel
+# back on the first (primary) screen before Plasma reads the file (session/fix-panels.py).
+python3 "$here/fix-panels.py" --screens "$screens" || true
+
 dbus-run-session startplasma-wayland

session/tests/test_fix_panels.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Tests for session/fix-panels.py: issue #18's config (the taskbar saved on spare output 8
+of a 3-screen desktop), panels that are fine, an edge that's taken, and a real run of
+kwriteconfig6 on a copy. Nothing here touches the running desktop or its config.
+
+  python3 session/tests/test_fix_panels.py
+"""
+import importlib.util
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+
+HERE = os.path.dirname(os.path.realpath(__file__))
+SCRIPT = os.path.join(HERE, "..", "fix-panels.py")
+spec = importlib.util.spec_from_file_location("fix_panels", SCRIPT)
+fp = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(fp)
+
+
+def desktop(cid, screen):
+    return f"""[Containments][{cid}]
+activityId=7e1d1a3c-0000-4000-8000-000000000000
+formfactor=0
+immutability=1
+lastScreen={screen}
+location=0
+plugin=org.kde.plasma.folder
+wallpaperplugin=org.kde.image
+"""
+
+
+def panel(cid, screen, location=4, tray=None):
+    text = f"""[Containments][{cid}]
+activityId=
+formfactor=2
+immutability=1
+lastScreen={screen}
+location={location}
+plugin=org.kde.panel
+wallpaperplugin=org.kde.image
+
+[Containments][{cid}][Applets][{cid}1]
+immutability=1
+plugin=org.kde.plasma.kickoff
+"""
+    if tray:
+        text += f"""
+[Containments][{cid}][Applets][{cid}2]
+immutability=1
+plugin=org.kde.plasma.systemtray
+
+[Containments][{cid}][Applets][{cid}2][Configuration]
+PreloadWeight=90
+SystrayContainmentId={tray}
+
+[Containments][{tray}]
+activityId=
+formfactor=2
+immutability=1
+lastScreen={screen}
+location={location}
+plugin=org.kde.plasma.private.systemtray
+popupHeight=432
+"""
+    return text
+
+
+ISSUE_18 = "\n".join([desktop(1, 0), desktop(18, 1), desktop(19, 2)] + [desktop(20 + i, 3 + i) for i in range(8)]
+                     + [panel(10, 8, tray=11), "[ScreenMapping]\nitemsOnDisabledScreens=\n"])
+
+
+class Plan(unittest.TestCase):
+    def test_issue_18(self):
+        moves, kept = fp.plan(fp.parse(ISSUE_18), 3)
+        self.assertEqual(moves, [("10", 8, ["10", "11"])])
+        self.assertEqual(kept, [])
+
+    def test_panel_on_a_screen_stays(self):
+        for screen in (0, 2, -1):
+            moves, kept = fp.plan(fp.parse(desktop(1, 0) + panel(2, screen, tray=8)), 3)
+            self.assertEqual((moves, kept), ([], []), screen)
+
+    def test_tray_is_not_a_panel(self):
+        found = fp.panels(fp.parse(panel(2, 0, tray=8)))
+        self.assertEqual(list(found), ["2"])
+        self.assertEqual(found["2"]["trays"], ["8"])
+
+    def test_desktops_never_move(self):
+        moves, _ = fp.plan(fp.parse(ISSUE_18), 1)
+        self.assertEqual([m[0] for m in moves], ["10"])
+
+    def test_edge_taken_on_first_screen(self):
+        text = panel(2, 0, tray=8) + panel(10, 8, tray=11)
+        moves, kept = fp.plan(fp.parse(text), 3)
+        self.assertEqual(moves, [])
+        self.assertEqual([k[:2] for k in kept], [("10", 8)])
+
+    def test_other_edge_is_free(self):
+        moves, kept = fp.plan(fp.parse(panel(2, 0) + panel(10, 4, location=3)), 3)
+        self.assertEqual(moves, [("10", 4, ["10"])])
+        self.assertEqual(kept, [])
+
+    def test_two_lost_on_one_edge(self):
+        moves, kept = fp.plan(fp.parse(panel(10, 5) + panel(12, 8)), 3)
+        self.assertEqual([m[0] for m in moves], ["10"])
+        self.assertEqual([k[0] for k in kept], ["12"])
+
+    def test_screen_count_went_down(self):
+        moves, _ = fp.plan(fp.parse(panel(2, 1, location=3)), 1)
+        self.assertEqual(moves, [("2", 1, ["2"])])
+
+
+class Run(unittest.TestCase):
+    def setUp(self):
+        self.dir = tempfile.TemporaryDirectory()
+        self.path = os.path.join(self.dir.name, "plasma-org.kde.plasma.desktop-appletsrc")
+        with open(self.path, "w") as f:
+            f.write(ISSUE_18)
+
+    def tearDown(self):
+        self.dir.cleanup()
+
+    def run_script(self, *args):
+        return subprocess.run([sys.executable, SCRIPT, "--file", self.path, "--screens", "3", *args],
+                              capture_output=True, text=True)
+
+    def test_check_reports_and_changes_nothing(self):
+        r = self.run_script("--check")
+        self.assertEqual(r.returncode, 1)
+        self.assertIn("panel 10: screen 8, bottom (lost", r.stdout)
+        with open(self.path) as f:
+            self.assertEqual(f.read(), ISSUE_18)
+
+    def test_repair(self):
+        r = self.run_script()
+        self.assertEqual(r.returncode, 0, r.stderr)
+        self.assertIn("moved it to the first screen", r.stderr)
+        with open(self.path) as f:
+            groups = fp.parse(f.read())
+        self.assertEqual(groups[("Containments", "10")]["lastScreen"], "0")
+        self.assertEqual(groups[("Containments", "11")]["lastScreen"], "0")
+        self.assertEqual(groups[("Containments", "10", "Applets", "101")]["plugin"], "org.kde.plasma.kickoff")
+        self.assertEqual(groups[("Containments", "25")]["lastScreen"], "8")  # a spare's desktop
+        with open(self.path + ".ft-bak") as f:
+            self.assertEqual(f.read(), ISSUE_18)
+        # A second run finds nothing to do and leaves the backup alone.
+        os.remove(self.path + ".ft-bak")
+        r = self.run_script()
+        self.assertEqual((r.returncode, r.stderr), (0, ""))
+        self.assertFalse(os.path.exists(self.path + ".ft-bak"))
+        self.assertEqual(self.run_script("--check").returncode, 0)
+
+    def test_no_config_yet(self):
+        os.remove(self.path)
+        self.assertEqual(self.run_script().returncode, 0)
+        self.assertEqual(self.run_script("--check").returncode, 0)
+
+
+if __name__ == "__main__":
+    unittest.main()