diff --git a/hands/Makefile b/hands/Makefile
index 6130d8c..a606775 100644
--- a/hands/Makefile
+++ b/hands/Makefile
@@ -1,6 +1,7 @@
 # Hand tracking, built into build/ (hands/build.sh runs this in the dev container):
 #   make          ft-camd (camd/: runs on the host, so linked statically) and ft-hands (track/)
 #   make tools    ft-handreplay and ft-ringplay, for recordings
+#   make check    builds and runs the C++ unit tests (tests/sides_test.cpp)
 # The first build fetches ncnn (NCNN_TAG) and builds it into build/ncnn, which takes a few
 # minutes. NCNN=DIR uses an ncnn install already built instead.
 NCNN_TAG  = 20260526
@@ -11,7 +12,7 @@ CXXFLAGS += -std=c++17 -fopenmp -I$(NCNN)/include/ncnn
 LDLIBS    = $(NCNN)/lib/libncnn.a -ljsoncpp -fopenmp -lpthread
 
 CAMD  = camd/camd.c camd/tp.c camd/xrcams.c
-TRACK = track/calib.cpp track/nets.cpp track/tracker.cpp track/io.cpp track/record.cpp track/pinch.cpp
+TRACK = track/calib.cpp track/nets.cpp track/tracker.cpp track/io.cpp track/record.cpp track/pinch.cpp track/sides.cpp
 HDR   = $(wildcard track/*.h) camd/fhring.h include/fh_hands.h include/fh_gestures.h
 
 all: build/ft-camd build/ft-hands
@@ -29,6 +30,13 @@ build/ft-handreplay: track/replay.cpp $(TRACK) $(HDR) $(NCNN)/lib/libncnn.a
 	@mkdir -p build
 	$(CXX) $(CXXFLAGS) -o $@ track/replay.cpp $(TRACK) $(LDLIBS)
 
+build/sides-test: tests/sides_test.cpp $(TRACK) $(HDR) $(NCNN)/lib/libncnn.a
+	@mkdir -p build
+	$(CXX) $(CXXFLAGS) -o $@ tests/sides_test.cpp $(TRACK) $(LDLIBS)
+
+check: build/sides-test
+	build/sides-test
+
 build/ft-ringplay: track/ringplay.cpp track/record.h camd/fhring.h
 	@mkdir -p build
 	$(CXX) $(CXXFLAGS) -o $@ track/ringplay.cpp
@@ -44,6 +52,6 @@ build/ncnn/install/lib/libncnn.a:
 	cmake --build build/ncnn/build --target install > build/ncnn/build.log
 
 clean:
-	rm -f build/ft-camd build/ft-hands build/ft-handreplay build/ft-ringplay
+	rm -f build/ft-camd build/ft-hands build/ft-handreplay build/ft-ringplay build/sides-test
 
-.PHONY: all tools clean
+.PHONY: all tools check clean
diff --git a/hands/README.md b/hands/README.md
index cfbca6d..5b84901 100644
--- a/hands/README.md
+++ b/hands/README.md
@@ -36,7 +36,7 @@ hands/run.sh uninstall
 
 Settings in `~/.config/frametop.conf` (`FT_<name>` in the environment overrides them), read when ft-camd and ft-hands start:
 
-- `HANDS_SWAP_SIDES=1`: the two side cameras' names are swapped (see ft-camd below). Check with `tools/check_sides.py --ring`.
+- `HANDS_SWAP_SIDES=auto` (the default): ft-hands tells from the hands which side camera is which, and corrects ft-camd's names when they're backwards (see "Which camera is which" below). `1` forces them exchanged and `0` forces ft-camd's names; ft-hands still checks and logs a warning if the hands disagree.
 - `HANDS_CPUS=5,6,7`: the CPUs the model threads run on (below).
 - `HANDS_CAMERAS` (`auto`), `HANDS_BRIGHT` (`all`), `HANDS_BRIGHT_ON` (40), `HANDS_BRIGHT_OFF` (25): which cameras ft-hands tracks with, as `--cams`, `--bright`, `--bright-on` and `--bright-off` (see ft-hands). `HANDS_CAMERAS=mono` also keeps ft-camd off the colour cameras.
 - `HANDS_COLOR_LEFT` (`color_video0`), `HANDS_COLOR_CROP` (`subtract`): how the colour module's calibration maps onto its images, as `--color-left` and `--color-crop`.
@@ -86,7 +86,14 @@ Options:
 
 It exits when XRService exits, or when a camera's buffers keep going stale, which means XRService has reallocated them. The service starts it again, and it attaches to the new buffers.
 
-**Which camera is which:** video9 is `slam_left`, video13 is `slam_right`, video6 is `upper_left` and video7 is `upper_right`. This was checked by rendering the same view from each camera with the factory calibration. But ft-camd tells the side cameras' buffers apart only by XRService's allocation order, and after some XRService restarts it gets them backwards. Then every hand is seen by one camera only, at the wrong depth, and the hand holes land beside the hands. With the headset on, looking at a room with some texture, `tools/check_sides.py --ring` says whether the names are right (exit 0), swapped (exit 3), or it can't tell (exit 2). When they're swapped, set `HANDS_SWAP_SIDES=1`. The colour cameras are video3 (`arcimx616 0-0010`) and video0 (`0-001a`); which of them is `passthrough_left` in the module's calibration is for `tools/check_color.py` to settle, on a recording with texture in view.
+**Which camera is which:** video9 is `slam_left`, video13 is `slam_right`, video6 is `upper_left` and video7 is `upper_right`. This was checked by rendering the same view from each camera with the factory calibration. But ft-camd tells the side cameras' buffers apart only by XRService's allocation order, and after some XRService restarts it gets them backwards. Then every hand is seen by one camera only, at the wrong depth, and the hand holes land beside the hands. ft-hands now catches this by itself (`track/sides.h`, `HANDS_SWAP_SIDES=auto`):
+- Whenever a hand's landmarks are found in two cameras at once (one of them a side camera), it intersects the rays through the 21 landmarks twice: once with the calibrations as named, once with the two side cameras exchanged. The same hand seen the right way meets within a few mm, in front of both cameras and as far away as its size says. The wrong way misses by centimetres or meets behind a camera.
+- With the names wrong, the tracker never gets such pairs on its own: it hands the hand over to where the wrong calibration puts it and finds nothing there. So 5 times a second while undecided, the check places a tracked hand in 3D under the other naming and runs the landmark model where that puts it in the other side camera.
+- It decides after 10 votes one way and none the other, or 20 with at most a fifth the other way, over at least 1 s. That takes about 1-2 s of hands in view. If the names are backwards, it exchanges them; the tracked views move with their images. Then it checks once more, more strictly.
+- The log says what it found (`side cameras: SWAPPED, now exchanged after 3.2 s (votes ...)`). So does `/run/user/UID/frametop-hands/sides.json`, which the hand recorder reads. Recordings get a `DIR/sides.json` (hands/rec/sides.py has the rules).
+- `--record-only` can't tell (it tracks nothing): it records ft-camd's names unless `--sides 0|1` says otherwise.
+
+`tools/check_sides.py --ring` is the independent check from the scene (ORB matches meeting under each naming): exit 0 as named, 3 swapped, 2 can't tell. `--pair upper` checks the upper pair the same way: in every recording so far (3 XRService starts, both side namings) the upper pair was named right. The colour cameras are video3 (`arcimx616 0-0010`) and video0 (`0-001a`); which of them is `passthrough_left` in the module's calibration is for `tools/check_color.py` to settle, on a recording with texture in view.
 
 ## ft-hands
 
@@ -102,14 +109,14 @@ Options:
 - `--threads N`: model threads, pinned to the `--cpus` list. Default 3.
 - `--cpus LIST`: CPUs for the model threads and the main loop. Default `5,6,7` (`HANDS_CPUS`). SteamOS starts user processes on CPUs 0-4, and XRService's head tracking runs on 2-3. With the headset on, a step took 8.4 ms on 5-7 against 13.2 ms on 2-4, and SteamVR's frame timing didn't change (2026-09-29, three rounds of the same replayed frames).
 - `--contrast MODE` or `PALM/HAND`: how crops are equalized before the models see them: `clahe[:CLIP]`, `none`, or `stretch` (1st-99th percentile). Default `clahe:2/none`. In the dim recording, CLAHE let the palm search find about 10% more hands, but it made the landmarks jitter more (published median 6.9 mm, against 6.0 mm with plain landmark crops).
-- `--swap-sides`: swap the two side cameras (`HANDS_SWAP_SIDES`, see ft-camd).
+- `--sides auto|0|1`: which side camera is which (`HANDS_SWAP_SIDES`, see "Which camera is which"); `--swap-sides` is `--sides 1`.
 - `--seconds N`: stop after N seconds.
 - `--status S`: how often to print status, in seconds.
 - `--models DIR`: where the models are.
 - `--nice N`: niceness. Default 5, so the VR stack wins contested CPUs.
 - `--no-publish`: don't write the hands and gestures files.
 - `--no-gestures`: hands for the cutouts only. No pinch or grip detection, so nothing reaches the pointer and a closing hand doesn't raise the rate to 30 Hz. The gestures file is removed at start. `ft-cutouts` runs it this way.
-- `--record DIR`, `--record-for S`: save every frame set for S seconds (default 120) to `DIR/sets.bin`. That's about 80 MB/s. Sending the tracker SIGUSR1 (`pkill -USR1 -x ft-hands`) starts a recording in `~/.local/share/frametop/hands/rec-<time>` without a restart. Recordings are images of your hands and room: they stay on the headset unless you move them.
+- `--record DIR`, `--record-for S`, `--record-hz N`: save every frame set for S seconds (default 120) to `DIR/sets.bin`, or at most N sets a second with `--record-hz` (the hand recorder uses 10). Every set is about 80 MB/s. Sending the tracker SIGUSR1 (`pkill -USR1 -x ft-hands`) starts a recording in `~/.local/share/frametop/hands/rec-<time>` without a restart. Recordings are images of your hands and room: they stay on the headset unless you move them.
 - `--record-only`: record without tracking or publishing, so it can run beside the live tracker. Give it `--record DIR`, since SIGUSR1 would reach both trackers. With `ft-camd --with-dark`, recordings also hold each camera's newest dark frame as `<name>_dk`, which doubles the rate. With `--with-color`, each colour camera's newest frame is saved with every set, as `color_video<N>`, which adds about 70 MB/s. Run the recorder at normal I/O priority: idle I/O priority stalled a 165 MB/s recording.
 - `--keep-presence P`: the landmark presence a tracked view needs to stay tracked. New views always need 0.5. Default 0.5. Lowering it to 0.2 barely helped in the bright recording, because lost hands drop to near-zero presence.
 - `--ring PATH`: read frames from another ring, such as `ft-ringplay`'s.
@@ -197,7 +204,7 @@ hands/build/ft-handreplay ~/.local/share/frametop/hands/rec-20260929-120000 --co
 
 Python, with NumPy and OpenCV. `setup/dev-container.sh` doesn't install them, because Fedora's `python3-opencv` pulls in over a gigabyte; in the dev container, run `sudo dnf install python3-numpy python3-opencv` once. Off the Frame, `FRAME_JOB_DEVICE_ROOT` can point at a folder with copies of the headset's calibration files.
 
-- `tools/check_sides.py --ring` (or a recording): are the side cameras named right?
+- `tools/check_sides.py --ring` (or a recording, a sets file, `--pair upper`, `--calib DIR`, `--json`): are the side cameras named right, from the scene? ft-handreplay's `--sides file|0|1|auto` replays with DIR/sides.json's names (the default), as recorded, exchanged, or as auto decides, and reports what the side check found and when.
 - `tools/check_color.py REC`: how the colour module's calibration maps onto its images.
 - `tools/show_set.py REC`: a recording's frame sets as images.
 - `tools/watch_gestures.py [--distance]`: pinches and grips, live.
@@ -207,15 +214,59 @@ Python, with NumPy and OpenCV. `setup/dev-container.sh` doesn't install them, be
 
 To try the hand cutouts without restarting the desktop, `screens/build/ft-handtest [--distance m] [--width m] [--seconds s]` (built by `screens/build.sh`, run in the dev container, with hand tracking on) shows a test panel of its own, a light grid 1 m wide and 0.8 m ahead by default, and cuts your hands out of it the way ft-screens cuts them out of the screens.
 
+## Camera check
+
+Hand tracking needs all four mono cameras and the headset's IR light. With the Arcturus colour module attached, SteamVR's XRService loads an FPGA image ("VCINT") onto the module every time it opens the cameras: when SteamVR starts and after every wake. When that load fails, XRService runs only the two side cameras, the frames come out darker and noisier, and ft-hands finds no hands at all. It happened on 2026-10-02 at 17:02, after the headset slept; the hand recorder then said "I can't see your hands" for a whole session.
+
+`hands/camcheck.py` (system Python, standard library) tells whether the four cameras run: `ok`, `degraded: upper cameras and IR light off (VCINT FPGA failed to load)` (or another `degraded:` reason), or `unknown` (SteamVR not running, the cameras closed while the headset sleeps). It prints the log lines and other evidence it used; `--json` is for programs; the exit status is 0, 1 or 2. It reads:
+- the running XRService's log (`~/.local/share/Steam/logs/xrservice.txt`): the last camera start (from the FPGA check to the next "Closing tracking camera interfaces"), its VCINT result, `Upper cameras FPGA interleaving support: N`, `Created N tasks (T tracking, P passthrough)` and the `TrackingCameraInit` lines. A wake that works prints no "Created N tasks", so an older one doesn't count;
+- which `/dev/video*` XRService has open (`/proc/PID/fd`; video9 and video13 are the side pair, video6 and video7 the upper pair). Only on the host: the dev container can't read another process's open files, so there it's skipped;
+- ft-camd's ring header, when it runs: how many mono cameras it publishes.
+
+The hand recorder runs it before a session (DESIGN.md, "Camera check"). `hands/tests/test_camcheck.py` runs it on the 2026-10-02 log cut at several points, and on made-up logs.
+
+### The watcher (off by default)
+
+`hands/ft-camwatch` follows the XRService log (a stat every 2 s, reading only what's new). On a VCINT failure it posts a notification in the Frametop desktop, on the desktop's own D-Bus, found through its plasmashell as `decoration/apply.sh` does. With `CAMWATCH_AUTO_RESTART=1` in `~/.config/frametop.conf` it also restarts SteamVR, but only:
+- while the headset isn't worn (frame-job's check: `vrcompositor` runs and a `/sys/class/backlight/*/brightness` is over 0), and after it has been off for `CAMWATCH_IDLE_S` (60);
+- with no app Steam launched (`SteamLaunch AppId=N` in a process's arguments; `CAMWATCH_IGNORE_APPIDS` lists ids that don't count) and nobody on the remote desktop (an established connection to the VNC port, `VNC_PORT`, 5900);
+- once per failure, and not again within `CAMWATCH_COOLDOWN_MIN` (30) of the last automatic restart. It remembers both in `~/.local/state/frametop/camwatch.json`, so its own restart doesn't reset them.
+
+It logs every decision to the journal. `ft-camwatch --once` prints the state and what it would do, and does nothing; `--dry-run` keeps watching without acting. `hands/frametop-camwatch.service` is the unit (a template, `@REPO@` as in the others; nothing installs or enables it yet). It isn't `PartOf=steamvr.service`, so it outlives the restart it asks for. `CAMWATCH_NOTIFY=0` turns the notification off. `hands/tests/test_camwatch.py` tests its decisions with made-up inputs.
+
+### What a SteamVR restart does to Frametop
+
+Read from the code on the experimental branch, not tried live:
+- ft-screens quits when SteamVR does: on `VREvent_Quit` it ends its Wayland display (`screens/vr.cpp`, `ft_vr_poll`; `screens/compositor.c`, `handle_vr_event`). It never connects to SteamVR again: `ft_vr_init` runs once, at its start.
+- KWin runs nested in ft-screens, so the Frametop desktop ends with it, every window in it too (the hand recorder's as well). Its unit, `frametop-desktop`, is a transient `systemd-run` unit with `Restart=no`, so the desktop doesn't come back by itself: start it again (Desktop in the library, or `desktops.sh start`).
+- When the unit stops, systemd ends what's left in it. `session/keep-apps.sh` moves programs started in the desktop out of the unit first, but only `desktops.sh stop` runs it; here they stop too. Programs in the dev container (ft-screens, the hand recorder) are in the container's cgroup and end when their Wayland connection goes.
+- The units that are `PartOf=steamvr.service` restart with it: `frametop-camd`, `frametop-hands`, the pointer helper, gaze and power, and the hand recorder's own transient ft-camd and ft-hands units.
+
+### Verified, and what's a guess
+
+Verified, from the XRService logs of 2026-10-01 and 2026-10-02 and the running system:
+- The failure's log lines and its effect: "Failed to load VCINT FPGA image when passthrough cameras are connected", interleaving support 0, "Created 4 tasks (2 tracking, 2 passthrough)", and only video9 and video13 opened. At 19:38-19:59 XRService held only those two of the four (plus video0 and video3), and ft-camd published two mono cameras.
+- A wake's load can work and can fail. Both wakes in the logs started from an FPGA that answered nothing ("ERROR/UNKNOWN"): the one at 2026-10-01 16:39 loaded VCINT, the one at 2026-10-02 17:02 failed ("FPGA config_done signal did not assert").
+- After a reboot the FPGA reads PASSTHRU and SteamVR's start loads VCINT (2026-10-01 21:53, 2026-10-02 13:39).
+- A SteamVR restart within a boot found VCINT still loaded and loaded nothing (2026-10-01 15:27): XRService checks the FPGA when it starts and loads only when it must.
+
+Guesses, not tested:
+- **Whether a SteamVR restart fixes it.** After a failed load the FPGA doesn't answer, so a new XRService would run the same load a wake runs, which has worked once and failed once. It's never been tried after a failure. If it doesn't help, only a reboot is known to work (the FPGA comes up as PASSTHRU, and the load at SteamVR's start has worked both times).
+- That the IR light is off because of the FPGA: the frames are darker and the illuminator ring isn't seen, and the FPGA loader lists a `room_led_en` pin, but nothing shows the light's state directly.
+- That a sleep and wake (taking the headset off long enough) would retry the load too: it should, since every wake loads VCINT, but no failure has been followed by a wake yet.
+- How the Frametop desktop behaves on a SteamVR restart (above): read from the code only.
+- That Steam-launched apps carry `SteamLaunch AppId=N`: from Steam on other Linux systems; no VR game has run on the Frame to confirm it.
+
 ## Build
 
 `hands/build.sh` builds in the dev container on the Frame, into `hands/build/`, with `hands/Makefile`. The first build fetches ncnn at a pinned tag (`NCNN_TAG` in the Makefile) and builds it into `hands/build/ncnn`, which takes a few minutes; `NCNN=DIR` points at an ncnn install already built instead. ft-camd is linked statically, because it runs on the host, which has an older glibc than the container.
 
 ## Known issues
 
-- **The side cameras can come out swapped.** ft-camd tells the side cameras' buffers apart only by XRService's allocation order, and some XRService restarts reverse it. For now it's caught by hand: `tools/check_sides.py --ring`, then `HANDS_SWAP_SIDES=1`. It needs a fix in ft-camd, or at least an automatic check when it starts.
+- **The side cameras can come out swapped.** ft-camd tells the side cameras' buffers apart only by XRService's allocation order, and some XRService restarts reverse it. ft-hands corrects it from the hands (`HANDS_SWAP_SIDES=auto`, the default). Until it has seen about 1-2 s of hands in both namings' reach, the cutouts may sit beside the hands. ft-camd itself still can't tell.
 - **The colour cameras can't be used while the headset is worn.** The colour module then writes only a half-size image into the top-left quarter of its buffers, and ft-camd drops those frames. So the service runs the mono cameras only, and tracking in bright light, where the mono cameras see dark hands, doesn't get the colour pair's help.
 - **The colour calibration mapping isn't settled.** Which colour camera is `passthrough_left` (`HANDS_COLOR_LEFT`) and how the module's crop applies (`HANDS_COLOR_CROP`) still need `tools/check_color.py` on a recording with a lit, textured view.
 - **Depth when one camera loses the hand.** A hand seen in one camera drifts 10% per update toward the one-camera depth guess (`kMonoDepthGain`, 0.1, in `track/tracker.cpp`). In the 2026-09-30 replays that was worse than keeping the last distance (see "3D" above). A smaller gain, such as 0.02, is the next thing to try.
 - **Pinches aren't reliable enough for everyday use yet.** That's why hand tracking stays off until `ft-handsctl on`, and `POINTER_HANDS` is 0 by default.
+- **SteamVR can leave the upper cameras and the IR light off after a wake**, and then no hands are found. See "Camera check" above: `camcheck.py` tells, the hand recorder won't start a session, and the fix is a SteamVR restart or a reboot.
 - **Floating windows don't get hand cutouts.** Their panels show crops of the client buffer, which the cutouts' side-by-side buffer doesn't match (`screens/vr.cpp`, `UpdateCutouts`).
diff --git a/hands/camcheck.py b/hands/camcheck.py
new file mode 100755
index 0000000..84e70b6
--- /dev/null
+++ b/hands/camcheck.py
@@ -0,0 +1,422 @@
+#!/usr/bin/env python3
+"""camcheck: are the headset's four mono tracking cameras running, so that ft-camd and
+ft-hands see them all?
+
+The Frame has four mono IR tracking cameras: the side pair slam_left and slam_right
+(/dev/video9 and /dev/video13) and the upper pair (/dev/video6 and /dev/video7). With the
+Arcturus colour module attached, SteamVR's XRService loads an FPGA image ("VCINT") onto the
+module whenever it opens the cameras (at start and after every wake). When that load fails
+(seen 2026-10-02 17:02, after a sleep), XRService runs only the two side cameras, the IR
+illuminator seems to stay off, and ft-hands finds no hands at all.
+
+What it looks at, cheapest first, all read-only:
+  1. The newest XRService log (~/.local/share/Steam/logs/xrservice.txt, a symlink to the
+     running instance's log): the last camera start, its VCINT result, "Upper cameras FPGA
+     interleaving support: N", "Created N tasks (T tracking, P passthrough)" and the
+     TrackingCameraInit lines. A wake doesn't always print "Created N tasks", so the parser
+     tracks each camera start ("episode") from the FPGA check to the next close.
+  2. Which /dev/video* XRService has open (/proc/PID/fd). Only on the host: the dev container
+     can't read another process's fd table (checked 2026-10-02), and then this is skipped.
+  3. A running ft-camd's ring header (/run/user/UID/frametop-hands/cam-ring): how many mono
+     cameras it publishes.
+
+Status: "ok", "degraded: <why>" or "unknown" (SteamVR not running, the cameras closed while
+the headset sleeps, no log). Exit status 0, 1, 2 for those.
+
+  python3 hands/camcheck.py             # the status and its evidence
+  python3 hands/camcheck.py --json      # for programs
+  python3 hands/camcheck.py --log FILE --no-proc --no-ring   # a saved log only (tests)
+
+System Python, standard library only; session.py and ft-camwatch import it.
+"""
+import argparse
+import glob
+import json
+import os
+import re
+import struct
+import sys
+import time
+
+LOG_DIR = os.path.expanduser("~/.local/share/Steam/logs")
+LOG_LINK = os.path.join(LOG_DIR, "xrservice.txt")
+SIDE_NODES = (9, 13)     # slam_left, slam_right (TrackingCameraInit index 0 and 1)
+UPPER_NODES = (6, 7)     # the upper pair (index 2 and 3)
+TRACKING = 4
+
+VCINT_REASON = "upper cameras and IR light off (VCINT FPGA failed to load)"
+DEGRADED_VCINT = "degraded: " + VCINT_REASON
+
+# What the window and the recorder say when the check fails this way.
+USER_TEXT = ("The headset's upper cameras and IR light are off. SteamVR couldn't start the colour camera "
+             "module (it happens sometimes after the headset sleeps). Restart SteamVR, or restart the headset "
+             "if that doesn't fix it.")
+
+ANSI = re.compile(r"\x1b\[[0-9;]*m")
+STAMP = re.compile(r"^\w{3} \w{3} \d{2} \d{4} (\d{2}:\d{2}:\d{2})\.\d+ (\w+): ?(.*)$")
+# Lines worth reading; anything else is skipped before the regexes (the log grows by MBs a day).
+KEYS = ("FPGA", "VCINT", "Created", "TrackingCameraInit", "Closing tracking camera", "Streaming",
+        "systemd suspend", "systemd resume", "XRService logging to", "Exiting XRService")
+RE_PASSTHRU = re.compile(r"Passthrough connected but FPGA is (\S+) - loading VCINT")
+RE_INTERLEAVE = re.compile(r"Upper cameras FPGA interleaving support: (\d)")
+RE_TASKS = re.compile(r"Created (\d+) tasks \((\d+) tracking, (\d+) passthrough\)")
+RE_INIT = re.compile(r"TrackingCameraInit: index: (\d+)\. video device: /dev/video(\d+)")
+RE_STREAM = re.compile(r"Streaming resumed \(FPGA: (\S+), VC interleaving: (\w+)\)")
+RE_STATE = re.compile(r"FPGA state check: (\S+)")
+
+
+class LogState:
+    """Reads an XRService log line by line (feed), so the watcher can follow it as it grows.
+
+    An episode is one opening of the cameras: from the first FPGA, task or camera-init line
+    after the log starts or after "Closing tracking camera interfaces", to the next close."""
+
+    def __init__(self, path=""):
+        self.path = path
+        self.instance = ""        # the "XRService logging to" line's time
+        self.exited = False
+        self.closed = False       # the cameras were closed and haven't opened again
+        self.closed_at = ""
+        self.episode = None
+        self.nodes = {}           # TrackingCameraInit index -> /dev/videoN, from the whole log
+        self.failures = []        # [(time, line)]: every VCINT failure in this log
+        self.lines = 0
+
+    def _new_episode(self, t):
+        self.closed = False
+        self.episode = {"start": t, "fpga_before": "", "vcint": "", "interleave": None, "tasks": None,
+                        "inits": {}, "stream": "", "failure": "", "evidence": []}
+        if self.closed_at:
+            self.episode["evidence"].append(self.closed_at)
+
+    def _ep(self, t):
+        if self.episode is None or self.closed:
+            self._new_episode(t)
+        return self.episode
+
+    def feed(self, raw):
+        self.lines += 1
+        if not any(k in raw for k in KEYS):
+            return
+        line = ANSI.sub("", raw).rstrip("\n")
+        m = STAMP.match(line)
+        if not m:
+            return   # the FPGA loader's own output, without a time
+        t, _level, text = m.groups()
+        short = ("%s %s" % (t, text))[:220]
+        if "XRService logging to" in text:
+            lines = self.lines
+            self.__init__(self.path)
+            self.instance, self.lines = t, lines
+            return
+        if "Exiting XRService" in text:
+            self.exited = True
+            return
+        if "Closing tracking camera interfaces" in text:
+            self.closed, self.closed_at = True, short
+            return
+        if "systemd suspend notification" in text or "systemd resume notification" in text:
+            if "resume" in text:
+                self.closed_at = (self.closed_at + " / " if self.closed_at else "") + short
+            return
+        m = RE_PASSTHRU.search(text)
+        if m:
+            ep = self._ep(t)
+            ep["fpga_before"] = m.group(1)
+            ep["evidence"].append(short)
+            return
+        if "FPGA image VCINT loaded and verified successfully" in text:
+            ep = self._ep(t)
+            ep["vcint"] = "ok"
+            ep["evidence"].append(short)
+            return
+        if "Failed to load VCINT FPGA image" in text:
+            ep = self._ep(t)
+            ep["vcint"] = "failed"
+            ep["failure"] = t
+            ep["evidence"].append(short)
+            self.failures.append((t, short))
+            return
+        if "FPGA load failed" in text:
+            self._ep(t)["evidence"].append(short)
+            return
+        m = RE_INTERLEAVE.search(text)
+        if m:
+            ep = self._ep(t)
+            ep["interleave"] = int(m.group(1))
+            ep["evidence"].append(short)
+            return
+        m = RE_TASKS.search(text)
+        if m:
+            ep = self._ep(t)
+            ep["tasks"] = tuple(int(v) for v in m.groups())
+            ep["evidence"].append(short)
+            return
+        m = RE_INIT.search(text)
+        if m:
+            ep = self._ep(t)
+            idx, node = int(m.group(1)), int(m.group(2))
+            ep["inits"][idx] = node
+            self.nodes[idx] = node
+            ep["evidence"].append(short)
+            return
+        m = RE_STREAM.search(text)
+        if m:
+            ep = self._ep(t)
+            ep["stream"] = "%s, interleaving %s" % m.groups()
+            ep["evidence"].append(short)
+            return
+        m = RE_STATE.search(text)
+        if m:
+            ep = self._ep(t)
+            if not ep["fpga_before"] and not ep["vcint"]:
+                ep["fpga_before"] = m.group(1)
+                if m.group(1) == "VCINT":
+                    ep["vcint"] = "loaded"   # already there: no load needed (a SteamVR restart in the same boot)
+                ep["evidence"].append(short)
+
+    def feed_text(self, text):
+        for line in text.splitlines():
+            self.feed(line)
+        return self
+
+    def upper_nodes(self):
+        got = tuple(self.nodes[i] for i in (2, 3) if i in self.nodes)
+        return got if len(got) == 2 else UPPER_NODES
+
+    def tracking_nodes(self):
+        got = tuple(self.nodes[i] for i in range(TRACKING) if i in self.nodes)
+        return got if len(got) == TRACKING else SIDE_NODES + UPPER_NODES
+
+    def verdict(self):
+        """(status, reason, evidence): status "ok", "degraded" or "unknown"."""
+        if self.lines == 0:
+            return "unknown", "the XRService log is empty", []
+        if self.exited:
+            return "unknown", "XRService has exited (SteamVR isn't running)", []
+        if self.episode is None:
+            return "unknown", "the cameras haven't started yet in this log", []
+        ep = self.episode
+        ev = ep["evidence"][-14:]
+        if self.closed:
+            return "unknown", "the cameras are closed (the headset is asleep, or SteamVR is stopping)", \
+                ev + [self.closed_at]
+        tracking = len(ep["inits"]) if ep["inits"] else (ep["tasks"][1] if ep["tasks"] else None)
+        if ep["vcint"] == "failed":
+            return "degraded", VCINT_REASON, ev
+        if tracking is not None and tracking < TRACKING:
+            why = "only %d of %d tracking cameras running" % (tracking, TRACKING)
+            if ep["interleave"] == 0:
+                why += " (upper cameras' FPGA interleaving off)"
+            return "degraded", why, ev
+        if tracking == TRACKING:
+            return "ok", "%d tracking cameras running" % TRACKING, ev
+        return "unknown", "the cameras are starting", ev
+
+    def snapshot(self):
+        status, reason, ev = self.verdict()
+        ep = self.episode or {}
+        return {"status": status, "reason": reason, "evidence": ev, "log": self.path, "instance": self.instance,
+                "episode": {k: (list(v) if isinstance(v, tuple) else v) for k, v in ep.items() if k != "evidence"},
+                "failure": "%s@%s" % (self.path, ep["failure"]) if ep.get("vcint") == "failed" else ""}
+
+
+# ------------------------------------------------------------------------------------------
+# Processes
+
+def proc_argv(pid):
+    try:
+        with open("/proc/%s/cmdline" % pid, "rb") as f:
+            return [a.decode(errors="replace") for a in f.read().split(b"\0") if a]
+    except OSError:
+        return []
+
+
+def xrservice_pid():
+    """XRService's pid (its main thread renames itself XRServiceLoopTh), or None."""
+    for pid in os.listdir("/proc"):
+        if not pid.isdigit():
+            continue
+        try:
+            with open("/proc/%s/comm" % pid) as f:
+                if not f.read().startswith("XRService"):
+                    continue
+        except OSError:
+            continue
+        argv = proc_argv(pid)
+        if argv and os.path.basename(argv[0]) == "XRService":
+            return int(pid)
+    return None
+
+
+def xrservice_fds(pid):
+    """{"videos": [N, ...], "log": path or ""} from /proc/PID/fd, or None if it can't be read
+    (the dev container can't)."""
+    try:
+        fds = os.listdir("/proc/%d/fd" % pid)
+    except OSError:
+        return None
+    videos, log = set(), ""
+    for fd in fds:
+        try:
+            target = os.readlink("/proc/%d/fd/%s" % (pid, fd))
+        except OSError:
+            continue
+        m = re.match(r"/dev/video(\d+)$", target)
+        if m:
+            videos.add(int(m.group(1)))
+        elif re.search(r"/XRService-[^/]*\.log$", target):
+            log = target
+    if not videos and not log:
+        return None   # nothing readable: as good as no access
+    return {"videos": sorted(videos), "log": log}
+
+
+def newest_log():
+    """The running XRService's log: the xrservice.txt symlink, else the newest by time."""
+    if os.path.exists(LOG_LINK):
+        return os.path.realpath(LOG_LINK)
+    found = glob.glob(os.path.join(LOG_DIR, "XRService-*", "XRService-*.log"))
+    found += glob.glob(os.path.join(LOG_DIR, "XRService-*.log"))
+    found = [p for p in found if os.path.isfile(p)]
+    return max(found, key=os.path.getmtime) if found else ""
+
+
+def read_log(path):
+    st = LogState(path)
+    with open(path, "r", errors="replace") as f:
+        for line in f:
+            st.feed(line)
+    return st
+
+
+# ------------------------------------------------------------------------------------------
+# ft-camd's ring (camd/fhring.h; the header only, as session.py's Ring reads it)
+
+RING_HDR = struct.Struct("<8sIIIIQqQ16x")
+RING_CAM = struct.Struct("<32s32siIIIIIQQQQQIf24x")
+FH_CAM_DARK, FH_CAM_COLOR = 1, 2
+
+
+def default_ring():
+    return "/run/user/%d/frametop-hands/cam-ring" % os.getuid()
+
+
+def read_ring(path):
+    """{"alive", "writer_pid", "mono": [{"name", "sensor", "node"}]} or None (no ring)."""
+    try:
+        with open(path, "rb") as f:
+            data = f.read(RING_HDR.size + 8 * RING_CAM.size)
+    except OSError:
+        return None
+    if len(data) < RING_HDR.size:
+        return None
+    magic, version, _, ncams, _, _, writer, _ = RING_HDR.unpack_from(data, 0)
+    if magic != b"FHRING01" or version != 1:
+        return None
+    hb = struct.unpack_from("<Q", data, 40)[0]
+    alive = hb != 0 and (time.clock_gettime_ns(time.CLOCK_MONOTONIC) - hb) / 1e9 < 2.0
+    mono = []
+    for i in range(min(ncams, 8)):
+        off = RING_HDR.size + i * RING_CAM.size
+        if off + RING_CAM.size > len(data):
+            break
+        f = RING_CAM.unpack_from(data, off)
+        sensor = f[0].split(b"\0", 1)[0].decode(errors="replace")
+        name = f[1].split(b"\0", 1)[0].decode(errors="replace")
+        if f[13] & (FH_CAM_DARK | FH_CAM_COLOR) or name.endswith("_dk") or name.startswith("color"):
+            continue
+        mono.append({"name": name, "sensor": sensor, "node": f[2]})
+    return {"alive": alive, "writer_pid": writer, "mono": mono}
+
+
+# ------------------------------------------------------------------------------------------
+# The check
+
+def check(log=None, proc=True, ring=True, ring_path=None):
+    """The cameras' state: {"status": "ok"|"degraded"|"unknown", "summary": "ok" or
+    "degraded: ..." or "unknown: ...", "reason", "evidence": [lines], "log", "xrservice", "ring"}."""
+    evidence = []
+    pid = xrservice_pid() if proc else None
+    fds = xrservice_fds(pid) if pid else None
+    path = log or (fds or {}).get("log") or newest_log()
+    state = None
+    if path:
+        try:
+            state = read_log(path)
+        except OSError as e:
+            evidence.append("log %s: %s" % (path, e))
+    if state:
+        status, reason, ev = state.verdict()
+        evidence += ["log %s:" % path] + ["  " + e for e in ev]
+    else:
+        status, reason = "unknown", "no XRService log in %s" % LOG_DIR
+    out = {"log": path, "xrservice": None, "ring": None,
+           "episode": state.snapshot()["episode"] if state else {},
+           "failure": state.snapshot()["failure"] if state else ""}
+
+    if proc:
+        if pid is None:
+            # The log can't tell a killed XRService from a running one; no process settles it.
+            evidence.append("XRService isn't running")
+            status, reason = "unknown", "SteamVR isn't running (no XRService)"
+        elif fds is None:
+            evidence.append("XRService pid %d: its open files can't be read here (in the dev container?)" % pid)
+            out["xrservice"] = {"pid": pid, "videos": None}
+        else:
+            videos = fds["videos"]
+            want = state.tracking_nodes() if state else SIDE_NODES + UPPER_NODES
+            upper = state.upper_nodes() if state else UPPER_NODES
+            have = [n for n in want if n in videos]
+            evidence.append("XRService pid %d has open: %s (tracking cameras: %s; upper: %s)" % (
+                pid, " ".join("video%d" % n for n in videos) or "no cameras",
+                " ".join("video%d" % n for n in want), " ".join("video%d" % n for n in upper)))
+            out["xrservice"] = {"pid": pid, "videos": videos, "tracking_open": len(have)}
+            closed = state is not None and state.closed
+            if not closed and len(have) == TRACKING and status == "unknown":
+                status, reason = "ok", "XRService has all %d tracking cameras open" % TRACKING
+            elif not closed and videos and not all(n in videos for n in upper) and status != "degraded":
+                status, reason = "degraded", ("XRService has %d of %d tracking cameras open (the upper pair "
+                                              "is missing)" % (len(have), TRACKING))
+
+    if ring:
+        r = read_ring(ring_path or default_ring())
+        out["ring"] = r
+        if r is None:
+            evidence.append("ft-camd: no camera ring (not running)")
+        else:
+            names = " ".join(c["name"] for c in r["mono"]) or "none"
+            evidence.append("ft-camd (pid %d, %s): %d mono cameras: %s" % (
+                r["writer_pid"], "running" if r["alive"] else "stale ring", len(r["mono"]), names))
+            if r["alive"] and len(r["mono"]) < TRACKING and status == "ok":
+                status, reason = "degraded", ("ft-camd publishes only %d of %d mono cameras (it started while "
+                                              "they were missing: restart it)" % (len(r["mono"]), TRACKING))
+    out.update(status=status, reason=reason, evidence=evidence,
+               summary="ok" if status == "ok" else "%s: %s" % (status, reason))
+    return out
+
+
+def is_vcint_failure(result):
+    return bool(result) and result.get("status") == "degraded" and result.get("reason") == VCINT_REASON
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="Are the headset's four mono tracking cameras running?")
+    ap.add_argument("--json", action="store_true", help="print the result as JSON")
+    ap.add_argument("--log", help="read this XRService log (default: the running instance's)")
+    ap.add_argument("--no-proc", action="store_true", help="don't look at XRService's process")
+    ap.add_argument("--no-ring", action="store_true", help="don't look at ft-camd's ring")
+    ap.add_argument("--ring", help="ft-camd's ring (default /run/user/UID/frametop-hands/cam-ring)")
+    a = ap.parse_args(argv)
+    r = check(log=a.log, proc=not a.no_proc, ring=not a.no_ring, ring_path=a.ring)
+    if a.json:
+        print(json.dumps(r, indent=1))
+    else:
+        print(r["summary"])
+        for line in r["evidence"]:
+            print("  " + line)
+    return {"ok": 0, "degraded": 1}.get(r["status"], 2)
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/hands/frametop-camwatch.service b/hands/frametop-camwatch.service
new file mode 100644
index 0000000..e251b13
--- /dev/null
+++ b/hands/frametop-camwatch.service
@@ -0,0 +1,21 @@
+# Template: the installer replaces @REPO@ with the repo path on the Frame. Not installed or
+# enabled by anything yet (hands/README.md, "Camera check").
+[Unit]
+Description=Frametop camera watch: tells you when SteamVR leaves the headset's upper cameras off
+Documentation=file://@REPO@/hands/README.md
+# Not PartOf=steamvr.service: it has to outlive the SteamVR restart it may ask for.
+
+[Service]
+# On the host, system Python, standard library only. It stats the XRService log every 2 s and
+# reads only what's new. Notifications go to the Frametop desktop's own D-Bus (found through its
+# plasmashell). With CAMWATCH_AUTO_RESTART=1 in ~/.config/frametop.conf it may restart SteamVR
+# while the headset isn't worn: that also closes the Frametop desktop.
+ExecStart=/usr/bin/python3 @REPO@/hands/ft-camwatch
+Restart=on-failure
+RestartSec=30
+Nice=10
+CPUQuota=5%
+MemoryMax=64M
+
+[Install]
+WantedBy=default.target
diff --git a/hands/ft-camwatch b/hands/ft-camwatch
new file mode 100755
index 0000000..b250f6a
--- /dev/null
+++ b/hands/ft-camwatch
@@ -0,0 +1,378 @@
+#!/usr/bin/env python3
+"""ft-camwatch: watches SteamVR's XRService log for the camera failure that turns off the
+headset's upper cameras and IR light (a VCINT FPGA load that fails, usually after a wake;
+hands/camcheck.py), tells the Frametop desktop, and can restart SteamVR by itself.
+
+Off by default: hands/frametop-camwatch.service is a template the installer doesn't enable.
+Settings in ~/.config/frametop.conf:
+  CAMWATCH_AUTO_RESTART=1    restart SteamVR on a failure (default 0: only a notification). Only
+                             while the headset isn't worn (frame-job's check: vrcompositor runs and
+                             a backlight is on), after it has been off for CAMWATCH_IDLE_S, with no
+                             Steam-launched app running and nobody on the remote desktop (VNC).
+                             At most once per failure, and not again within CAMWATCH_COOLDOWN_MIN.
+  CAMWATCH_IDLE_S=60         how long the headset must be off first
+  CAMWATCH_COOLDOWN_MIN=30   the least time between two automatic restarts
+  CAMWATCH_IGNORE_APPIDS=    Steam app ids that don't count as a running VR app (comma-separated)
+  CAMWATCH_NOTIFY=1          post a notification in the Frametop desktop (0: log only)
+
+A SteamVR restart also closes the Frametop desktop and every window in it (ft-screens quits
+with SteamVR, and the desktop's unit doesn't restart: see hands/README.md, "Camera check").
+
+It follows the log with a stat every 2 s (no inotify, nothing else while all is well), and
+logs every decision to stdout (the journal). --dry-run never notifies or restarts; --once
+prints the state and what it would do now, and exits.
+"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+import camcheck  # noqa: E402
+
+CONF = os.path.expanduser("~/.config/frametop.conf")
+STATE = os.path.expanduser("~/.local/state/frametop/camwatch.json")
+BACKLIGHTS = "/sys/class/backlight"
+POLL_S = 2.0
+MAX_READ = 16 << 20     # a poll reads at most this much of a log that grew
+NOTIFY_TITLE = "Hand tracking: cameras off"
+NOTIFY_TEXT = ("The headset's upper cameras and IR light are off: SteamVR couldn't start the colour camera "
+               "module (it happens sometimes after the headset sleeps). Restart SteamVR, or the headset if "
+               "that doesn't fix it. Restarting SteamVR closes this desktop and its windows.")
+DEFAULTS = {"CAMWATCH_AUTO_RESTART": "0", "CAMWATCH_IDLE_S": "60", "CAMWATCH_COOLDOWN_MIN": "30",
+            "CAMWATCH_IGNORE_APPIDS": "", "CAMWATCH_NOTIFY": "1", "VNC_PORT": "5900"}
+
+
+def log(text):
+    print("%s %s" % (time.strftime("%H:%M:%S"), text), flush=True)
+
+
+def read_conf(path=CONF):
+    """KEY=VALUE lines of a shell-style file (comments and quotes stripped), over DEFAULTS."""
+    conf = dict(DEFAULTS)
+    try:
+        with open(path) as f:
+            for line in f:
+                line = line.split("#", 1)[0].strip()
+                if "=" not in line:
+                    continue
+                k, v = line.split("=", 1)
+                k, v = k.strip(), v.strip().strip("'\"")
+                if k.replace("_", "").isalnum():
+                    conf[k] = v
+    except OSError:
+        pass
+    return conf
+
+
+def conf_int(conf, key):
+    try:
+        return int(float(conf.get(key, DEFAULTS.get(key, "0"))))
+    except ValueError:
+        return int(DEFAULTS.get(key, "0") or 0)
+
+
+# ------------------------------------------------------------------------------------------
+# What's going on around (all read-only, from /proc and /sys)
+
+def process_running(name):
+    for pid in os.listdir("/proc"):
+        if pid.isdigit():
+            try:
+                with open("/proc/%s/comm" % pid) as f:
+                    if f.read().strip() == name:
+                        return True
+            except OSError:
+                pass
+    return False
+
+
+def headset_worn(backlights=BACKLIGHTS):
+    """frame-job's check: vrcompositor runs and any panel's backlight is on (SteamVR turns the
+    panels off 5 s after the headset comes off)."""
+    lit = False
+    try:
+        for name in os.listdir(backlights):
+            try:
+                with open(os.path.join(backlights, name, "brightness")) as f:
+                    lit = lit or int(f.read().strip()) > 0
+            except (OSError, ValueError):
+                pass
+    except OSError:
+        return False
+    return lit and process_running("vrcompositor")
+
+
+def vr_apps(ignore=()):
+    """Apps Steam launched ("SteamLaunch AppId=N" in a process's arguments, as Steam's reaper
+    runs them): ["AppId=N ..."]. Steam's own processes, SteamVR's and Frametop's services aren't
+    launched this way. A guess: no VR game has been run on the Frame to confirm the form."""
+    out = set()
+    for pid in os.listdir("/proc"):
+        if not pid.isdigit():
+            continue
+        argv = camcheck.proc_argv(pid)
+        if "SteamLaunch" not in argv:
+            continue
+        ids = [a.split("=", 1)[1] for a in argv if a.startswith("AppId=")]
+        if ids and ids[0] not in ignore:
+            out.add("AppId=" + ids[0])
+    return sorted(out)
+
+
+def remote_viewers(port=5900, tables=("/proc/net/tcp", "/proc/net/tcp6")):
+    """Established connections to the remote desktop's VNC port, from /proc/net/tcp(6)."""
+    out = []
+    for path in tables:
+        try:
+            with open(path) as f:
+                next(f)
+                for line in f:
+                    p = line.split()
+                    if len(p) > 3 and p[3] == "01" and int(p[1].rsplit(":", 1)[1], 16) == port:
+                        out.append(p[2])
+        except (OSError, StopIteration, ValueError):
+            pass
+    return out
+
+
+def frametop_bus():
+    """The Frametop desktop's D-Bus (from its plasmashell, as decoration/apply.sh finds it), or None."""
+    for pid in os.listdir("/proc"):
+        if not pid.isdigit():
+            continue
+        try:
+            with open("/proc/%s/comm" % pid) as f:
+                if f.read().strip() != "plasmashell":
+                    continue
+            with open("/proc/%s/environ" % pid, "rb") as f:
+                env = dict(kv.split(b"=", 1) for kv in f.read().split(b"\0") if b"=" in kv)
+        except OSError:
+            continue
+        if env.get(b"XDG_RUNTIME_DIR", b"").endswith(b"/frametop") and b"DBUS_SESSION_BUS_ADDRESS" in env:
+            return env[b"DBUS_SESSION_BUS_ADDRESS"].decode()
+    return None
+
+
+def notify(title, text):
+    bus = frametop_bus()
+    if not bus:
+        log("no Frametop desktop running: no notification")
+        return False
+    r = subprocess.run(["notify-send", "-a", "Frametop", "-u", "critical", "-i", "dialog-warning", title, text],
+                       env=dict(os.environ, DBUS_SESSION_BUS_ADDRESS=bus), capture_output=True, text=True,
+                       timeout=10)
+    if r.returncode:
+        log("notify-send failed (%d): %s" % (r.returncode, r.stderr.strip()))
+    return r.returncode == 0
+
+
+def restart_steamvr():
+    # --no-block: the job runs in systemd; the Frametop desktop closing doesn't cut it short.
+    r = subprocess.run(["systemctl", "--user", "restart", "--no-block", "steamvr.service"],
+                       capture_output=True, text=True, timeout=30)
+    log("systemctl --user restart steamvr.service: exit %d %s" % (r.returncode, (r.stderr or "").strip()))
+    return r.returncode == 0
+
+
+def environment(conf):
+    ignore = tuple(a.strip() for a in conf.get("CAMWATCH_IGNORE_APPIDS", "").replace(",", " ").split() if a.strip())
+    return {"steamvr": camcheck.xrservice_pid() is not None, "worn": headset_worn(),
+            "vr_apps": vr_apps(ignore), "remote": remote_viewers(conf_int(conf, "VNC_PORT"))}
+
+
+# ------------------------------------------------------------------------------------------
+# The decision (pure: tests feed it made-up states)
+
+def new_memory():
+    return {"pending": "", "notified": [], "restarted": {}, "last_restart": 0.0, "idle_since": None, "why": ""}
+
+
+def decide(now, failure, env, mem, conf):
+    """What to do now. failure: the current VCINT failure's id ("" if none: the cameras run,
+    or they're closed); env: {"steamvr", "worn", "vr_apps", "remote"} (only looked at while a
+    failure is current); mem: new_memory(), updated in place; now: wall-clock seconds.
+    Returns [("log", text) | ("notify", failure) | ("restart", failure)]."""
+    acts = []
+    if not failure:
+        if mem["pending"]:
+            acts.append(("log", "failure %s is no longer current" % mem["pending"]))
+        mem.update(pending="", idle_since=None, why="")
+        return acts
+    if mem["pending"] != failure:
+        mem.update(pending=failure, why="")
+        acts.append(("log", "VCINT failure: %s (upper cameras and IR light off)" % failure))
+    if failure not in mem["notified"]:
+        mem["notified"] = (mem["notified"] + [failure])[-20:]
+        if conf.get("CAMWATCH_NOTIFY", "1") != "0":
+            acts.append(("notify", failure))
+    if env.get("worn"):
+        mem["idle_since"] = None
+    elif mem["idle_since"] is None:
+        mem["idle_since"] = now
+    idle_s = conf_int(conf, "CAMWATCH_IDLE_S")
+    cooldown = conf_int(conf, "CAMWATCH_COOLDOWN_MIN") * 60
+    if conf.get("CAMWATCH_AUTO_RESTART", "0") != "1":
+        why = "no automatic restart (CAMWATCH_AUTO_RESTART=1 in ~/.config/frametop.conf turns it on)"
+    elif failure in mem["restarted"]:
+        why = "SteamVR was restarted once for this failure already: restart the headset"
+    elif mem["last_restart"] and now - mem["last_restart"] < cooldown:
+        why = "no restart: the last automatic one was %d min ago (cooldown %d min)" % (
+            (now - mem["last_restart"]) // 60, cooldown // 60)
+    elif not env.get("steamvr"):
+        why = "no restart: SteamVR isn't running"
+    elif env.get("worn"):
+        why = "no restart while the headset is worn"
+    elif env.get("vr_apps"):
+        why = "no restart: a VR app is running (%s)" % ", ".join(env["vr_apps"])
+    elif env.get("remote"):
+        why = "no restart: someone is on the remote desktop (%s)" % ", ".join(env["remote"])
+    elif now - mem["idle_since"] < idle_s:
+        why = "waiting for the headset to stay off for %d s" % idle_s
+    else:
+        mem["restarted"][failure] = now
+        mem["last_restart"] = now
+        why = "restarting SteamVR (the headset is off, nothing else in VR)"
+        acts.append(("log", why))
+        acts.append(("restart", failure))
+        mem["why"] = why
+        return acts
+    if why != mem["why"]:
+        mem["why"] = why
+        acts.append(("log", why))
+    return acts
+
+
+def load_memory(path=STATE):
+    mem = new_memory()
+    try:
+        with open(path) as f:
+            saved = json.load(f)
+        mem["notified"] = list(saved.get("notified", []))[-20:]
+        mem["restarted"] = dict(saved.get("restarted", {}))
+        mem["last_restart"] = float(saved.get("last_restart", 0.0))
+    except (OSError, ValueError, TypeError, AttributeError):
+        pass
+    return mem
+
+
+def save_memory(mem, path=STATE):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    tmp = path + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump({"notified": mem["notified"], "restarted": mem["restarted"],
+                   "last_restart": mem["last_restart"]}, f)
+    os.replace(tmp, path)
+
+
+# ------------------------------------------------------------------------------------------
+# Following the log
+
+class Follower:
+    """The running XRService's log, read as it grows. A new log (SteamVR restarted) starts afresh."""
+
+    def __init__(self, path=None):
+        self.fixed = path
+        self.path, self.ino, self.offset, self.rest = "", None, 0, ""
+        self.state = None
+
+    def poll(self):
+        path = self.fixed or camcheck.newest_log()
+        if not path:
+            return None
+        try:
+            st = os.stat(path)
+        except OSError:
+            return self.state
+        if path != self.path or st.st_ino != self.ino or st.st_size < self.offset:
+            self.path, self.ino, self.offset, self.rest = path, st.st_ino, 0, ""
+            self.state = camcheck.LogState(path)
+            log("following %s" % path)
+        if st.st_size > self.offset:
+            with open(path, "rb") as f:
+                f.seek(self.offset)
+                data = f.read(MAX_READ)
+            self.offset += len(data)
+            text = self.rest + data.decode(errors="replace")
+            lines = text.split("\n")
+            self.rest = lines.pop()
+            for line in lines:
+                self.state.feed(line)
+        return self.state
+
+
+def current_failure(state, steamvr_running=True):
+    """The failure id if the log's current camera start is a VCINT failure, else ""."""
+    if state is None or not steamvr_running:
+        return ""
+    snap = state.snapshot()
+    return snap["failure"] if snap["status"] == "degraded" and snap["reason"] == camcheck.VCINT_REASON else ""
+
+
+def act(acts, dry):
+    changed = False
+    for kind, arg in acts:
+        if kind == "log":
+            log(arg)
+        elif kind == "notify":
+            changed = True
+            if dry:
+                log("(dry run) would notify: %s" % NOTIFY_TITLE)
+            else:
+                notify(NOTIFY_TITLE, NOTIFY_TEXT)
+        elif kind == "restart":
+            changed = True
+            if dry:
+                log("(dry run) would restart SteamVR")
+            else:
+                restart_steamvr()
+    return changed
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="Watch for the camera failure that turns off the upper cameras.")
+    ap.add_argument("--dry-run", action="store_true", help="log what it would do; never notify or restart")
+    ap.add_argument("--once", action="store_true", help="look once, print the decision (a dry run), and exit")
+    ap.add_argument("--log", help="follow this file instead of the running XRService's log (tests)")
+    ap.add_argument("--state", default=STATE, help="where it remembers past failures (default %(default)s)")
+    a = ap.parse_args(argv)
+    dry = a.dry_run or a.once
+    mem = load_memory(a.state)
+    follower = Follower(a.log)
+    conf = read_conf()
+    conf_mtime = 0.0
+    log("watching; automatic restart %s" % ("on" if conf.get("CAMWATCH_AUTO_RESTART") == "1" else "off"))
+    while True:
+        try:
+            m = os.stat(CONF).st_mtime
+        except OSError:
+            m = 0.0
+        if m != conf_mtime:
+            conf, conf_mtime = read_conf(), m
+        state = follower.poll()
+        failure = current_failure(state)
+        env = {}
+        if failure or mem["pending"]:
+            env = environment(conf)
+            if not env["steamvr"] and not a.log:
+                failure = ""   # the log's last word, but XRService is gone
+        acts = decide(time.time(), failure, env, mem, conf)
+        if a.once:
+            snap = state.snapshot() if state else {"status": "unknown", "reason": "no log"}
+            print("log: %s\nstate: %s %s\nenvironment: %s" % (follower.path, snap["status"], snap["reason"],
+                                                              json.dumps(env)))
+            act(acts, True)
+            return 0
+        if act(acts, dry) and not dry:
+            save_memory(mem, a.state)
+        time.sleep(POLL_S)
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except KeyboardInterrupt:
+        sys.exit(0)
diff --git a/hands/rec/CONSENT.md b/hands/rec/CONSENT.md
new file mode 100644
index 0000000..4b0dc6a
--- /dev/null
+++ b/hands/rec/CONSENT.md
@@ -0,0 +1,97 @@
+# Recording your hands for the Frametop hand dataset
+
+Version: 2026-10-03
+
+Frametop's hand tracking needs a small model that finds hands in the headset's camera images. To train it, we're collecting recordings of many people's hands into a public dataset. This page explains what the hand recorder records, where it goes, and what you agree to if you take part. Please read all of it.
+
+## Who runs this
+
+Frametop is an independent open-source project, maintained by DeeJanuz (<https://github.com/DeeJanuz>). It isn't affiliated with or endorsed by Valve or Hugging Face. Steam and Steam Frame are trademarks of Valve Corporation. This text was written without a lawyer, in good faith; if something in it seems wrong or unclear, please say so before you take part.
+
+You can reach the maintainer through the Frametop repository's issues (<https://github.com/DeeJanuz/frametop/issues>) or the dataset's discussion page on Hugging Face. Both are public.
+
+## Who can take part
+
+- You must be **18 or older**.
+- For now, you can't take part if you live in **Illinois, Texas or Washington** (USA). Those states have laws about biometric data (such as hand geometry) that need more than this project can provide yet.
+- Take part only if you're comfortable with images of your hands and the room in front of you being public.
+
+## What is recorded
+
+While a session runs, the hand recorder saves:
+
+- **Camera images.** Infrared images from the headset's 4 tracking cameras, about 10 sets a second. They show your hands, your arms, your clothing and whatever is in front of you: your room, your desk and the things on it. They're grey, low-detail images, but people and things can be recognised in them. The size and shape of your hands can be measured from them: that's part of what they're for.
+- **Motion.** The position and rotation of the headset, many times a second, and of the controllers when you use them in the recording.
+- **Prompts.** What you were asked to do and when, and what the live hand tracker saw at the time.
+- **Calibration.** Where the cameras sit on the headset and how their lenses bend the image. Serial numbers and other fields that identify your headset are removed first, and the export lists what was removed.
+- **Your answers.** Which objects you had, the lighting, whether you wore sleeves, rings or a watch, your handedness if you gave it, and any notes you typed in the checklist or in Review. Notes are uploaded with the recordings and read by the maintainer: don't put anything in them that identifies you.
+- **Times.** When each session was recorded, with your time zone.
+- **A contributor id.** A random number made on your headset the first time you agree to this page. It isn't made from your name, your Steam account or your headset. It keeps your sessions together and lets you withdraw them.
+
+The recorder doesn't record sound, your name, your email address or your Steam account. The tracking cameras look outward, so your eyes and face aren't recorded, unless a mirror or something shiny shows them: avoid those.
+
+**Your Hugging Face account.** You upload with your own Hugging Face account, and your pull request shows its username next to your contributor id, publicly. So anyone can see which Hugging Face account contributed which recordings. Use an account you're happy to have linked to them.
+
+## What it's used for
+
+- Training and testing hand-tracking models: finding hands, their keypoints, their shape and how far away they are. Mainly for Frametop's hand cutouts, and by anyone else for non-commercial work under the dataset's license.
+- It isn't used to recognise or identify people, and the dataset's terms forbid anyone from trying.
+
+## Nothing leaves your headset unless you send it
+
+- Recordings stay on your headset, in `~/.local/share/frametop/hands/contrib`. Nothing is uploaded automatically.
+- Before you share anything, you can watch every recording in the Review page. You can delete any stretch of a recording, a whole take or a whole session. Export leaves out what you deleted.
+- You upload the export yourself, from the Upload page. That opens a pull request on the dataset. The maintainer checks it before it becomes part of the dataset, and may decline it. Until it's merged, you can close the pull request yourself.
+
+## Where it goes
+
+- **The dataset is public.** It's hosted on Hugging Face (<https://huggingface.co/datasets/DeeJanuz/frametop-hands>), whose servers may be outside your country, for example in the USA. Anyone who accepts the dataset's terms can download it.
+- People who download it agree not to try to identify anyone or anything in it, and to delete recordings that are later withdrawn. We can't enforce that against everyone: assume copies may exist.
+- Recordings stay in the dataset until they're withdrawn or the dataset is taken down.
+
+## Keep other people and private things out of view
+
+While recording, please:
+
+- face away from other people, mirrors, screens showing private things, papers, letters, photos and anything else you wouldn't want public;
+- make sure nobody else's face or hands are in view, and record only where the people you share the space with are fine with it;
+- don't record children.
+
+If something private got into a recording, delete that stretch in Review before you export. If you notice it after uploading, withdraw the session (below).
+
+## Safety
+
+The sessions ask you to move your hands and arms around you, out to full reach. Sit where you normally use the headset, clear an arm's reach around you, and stop whenever anything is uncomfortable. You take part at your own risk.
+
+## The license
+
+- **The dataset is published under Creative Commons Attribution-NonCommercial 4.0 (CC BY-NC 4.0).** Anyone may use it for non-commercial purposes, with attribution. Your contribution is credited by its contributor id, not your name.
+- **You also give the maintainer of Frametop a non-exclusive, worldwide, royalty-free license to use your contribution for any purpose, including commercially.** That includes copying it, changing it, and training, publishing and selling models made from it, in Frametop and elsewhere. The maintainer today is DeeJanuz. If someone else, or an organization, takes over maintaining Frametop, this license passes to them. It's non-exclusive: you keep any rights you have in your recordings and can do what you like with your own copies. It ends for a recording when you withdraw it, except for models already trained with it.
+- You confirm that you have the right to give these licenses: the recordings are yours, and nothing in them belongs to someone who hasn't agreed.
+- There is no payment. The dataset and the hand recorder come with no warranty, and as far as the law allows, the maintainer isn't liable for any loss or damage from taking part.
+
+## Withdrawing
+
+You can withdraw a contribution at any time, without giving a reason:
+
+- **Before it's merged:** close your pull request on Hugging Face. The maintainer deletes its files.
+- **After it's merged:** post on the dataset's discussion page, or in the Frametop repository's issues, with your contributor id (shown in the hand recorder) and which sessions, or "all". Post from the Hugging Face account that uploaded them if you can, so the maintainer can tell it's you; otherwise, say how to check. These requests are public, so don't add anything else that identifies you.
+
+Then, usually within 30 days:
+
+- your recordings are deleted from the dataset and purged from its repository's history, so they can't be downloaded from there again;
+- they're left out of anything trained after that.
+
+What can't be undone: copies others downloaded before the withdrawal, and models already trained with them.
+
+## Your rights
+
+Depending on where you live (for example in the EU or the UK, under the GDPR), the law may give you more rights over this data: to get a copy of it, to have it corrected or deleted, to object to its use, and to complain to your data protection authority. The data is used because you agreed to it, and you can withdraw that agreement at any time, as above. Withdrawing doesn't make earlier use unlawful. To use any of these rights, contact the maintainer as above.
+
+## Changes to this text
+
+If this text changes, the hand recorder shows the new version and asks you again before your next session. Each upload records the version you agreed to, and recordings you already uploaded stay under that version, unless you agree to a newer one or withdraw them.
+
+## Agreeing
+
+By ticking the three boxes and "Agree and continue", you confirm that you're 18 or older, that you don't live in Illinois, Texas or Washington, and that you agree to the above. You can still decide not to upload anything.
diff --git a/hands/rec/DESIGN.md b/hands/rec/DESIGN.md
new file mode 100644
index 0000000..f67a7da
--- /dev/null
+++ b/hands/rec/DESIGN.md
@@ -0,0 +1,366 @@
+# Hand recorder: design (Phase 1 of the hands plan)
+
+The hand recorder guides a person through recording their hands with the headset's cameras. It saves the recordings as files, lets them review and delete anything, then exports a package to contribute to the open hand dataset. Recordings never leave the headset unless the person uploads them.
+
+The plan this belongs to is `~/Desktop/Projects/frame-hands/notes/hands-plan.md` (on the maintainer's Frame). In short, the dataset trains a small hand model for Frametop's hand cutouts.
+
+## Parts
+
+| Part | What it does |
+|---|---|
+| `hands/rec/panel/ft-handpanel.cpp` (C++, dev container) | The headset panel: a SteamVR overlay fixed to the head that shows the prompts. It also places the "touch the dot" target in the room and logs head and controller poses. Driven over `@ft_handpanel`. |
+| `hands/rec/session.py` (Python, no Qt) | The session runner. It reads `script.json`, starts and stops the recordings, and drives the panel. It reads the live hands file for feedback and writes each take's files. It also runs from the command line (`--dry-run`) for testing. |
+| `hands/rec/script.json` | The guided script: sections, prompts, timings. |
+| `hands/rec/poses/` | The pose pictures, `poses.json` and its PNGs (below). |
+| `hands/rec/takes.py` (Python, no Qt) | Reads sessions and takes from disk: frame sets for review, deleted ranges, export (compress, strip, manifest, checksums). |
+| `hands/rec/ft_handrec.py` + `main.qml` (PySide6 + Kirigami, dev container) | The desktop window: consent, the before-you-start checklist, the session controls, review, export and upload instructions. |
+| `hands/rec/ft-handrec` | The host launcher, like `input-settings/ft-input-settings`. |
+| `hands/rec/build.sh` | Builds `ft-handpanel` into `hands/rec/build/`, like `gaze/build.sh`. |
+| `hands/rec/CONSENT.md`, `hands/rec/UPLOAD.md` | The texts the window shows. |
+| `hands/rec/install.sh` | Installs the recorder on a Frame with Frametop: the dev container's packages, hands/build.sh, the panel, ft-camd's capabilities, and the menu entry (`uninstall` removes the entry). |
+| ft-hands `--record-hz N` (done) | Records at most N frame sets a second. The recorder uses 10. |
+| `hands/camcheck.py` (shared, standard library) | Are all four mono cameras running? The recorder runs it before a session and when a step sees no hands (below; `hands/README.md`, "Camera check"). |
+
+Every part runs in the dev container, as ft-hands and Input Settings do. The host Python isn't used: it lacks PySide6 and zstd. `setup/dev-container.sh` gains `zstd`.
+
+## Processes during a session
+
+- **ft-camd** publishes the camera ring. If it isn't running, the session starts it as the transient user unit `frametop-handrec-camd.service`, the way `hands/ft-cutouts` starts `frametop-cutouts-camd.service` (needs `hands/build/ft-camd` with capabilities: `hands/run.sh caps`). An ft-camd already running from ft-cutouts or ft-handsctl is used as it is.
+- **A tracking ft-hands** gives feedback through the hands file: which hands are seen, the palm's distance, the index tip. If none is running, the session starts `ft-hands --no-gestures --status 0` (unit `frametop-handrec-hands.service`). An ft-hands already running is used as it is.
+- **A recording ft-hands** runs once per recording part: `ft-hands --record-only --record DIR --record-for SECONDS --record-hz 10 --status 0 --sides auto|0|1` (below, "Side cameras"). It runs as a plain child process of the session, ended with SIGTERM when the part ends. SIGTERM ends ft-hands' loop, and `Recorder` writes out its queue when it's destroyed. In step mode (below) a part is one step's countdown and hold, so a take has one part per step (about 40 in the hand poses); in auto mode a take is one part, plus one more after each pause. `--record-for` is only a safety net.
+  - Why a process per part rather than one kept alive and paused: measured in the dev container with `ft-ringplay`'s ring (2026-10-02), `ft-hands --record-only` writes its first set 16-27 ms after it starts and ends 4-6 ms after SIGTERM, so a new part costs nothing the 3 s countdown doesn't cover. Every reader already takes parts in order (`takes.py`, `validate.py` through the export's single stream, the labeller's `fhl_io.py`, numbering `sets-10.bin` after `sets-9.bin`), ft-hands needs no new control, and nothing is written while a step waits. Before the hold starts the session checks that the part has written a set (`Recorder.has_data`, up to 3 s more), so the hold is recorded from its first frame.
+- **Side cameras.** ft-camd can name the two side cameras the wrong way round (hands/README.md, "Which camera is which"). The tracking ft-hands decides from the hands within about 2 s of them being in view (`HANDS_SWAP_SIDES=auto`, hands/track/sides.h) and publishes that in `/run/user/UID/frametop-hands/sides.json`. The session reads it (`sides.py`, `read_live`) and stores it in session.json `"sides"`. Each later part is recorded named right (`--sides 1` or `0`). Parts recorded before the decision use ft-camd's names (`--sides auto`; a record-only ft-hands can't tell), and readers rename them (`sides.py`). Each part's `names_swapped` goes into take.json `"parts"`. Without a tracking ft-hands nothing decides: `"swapped": null`, the names stay as recorded, and the maintainer's check (`hub_review check`, check_sides on a few sets per take) tells. `takes.py sides SESSION --set swapped|named` records a decision by hand.
+- **ft-handpanel** runs as a child process with `--watch-stdin`. It shows the panel and logs poses during each take.
+- **The headset button's reader** is a thread of the session (`ButtonReader`, below), not a process.
+
+Test hooks:
+- `--ring PATH` goes to both ft-hands (`ft-ringplay` publishes a recording there, so the whole flow runs without the headset).
+- `--no-start` uses only what's already running.
+- `--dry-run` runs no processes and only prints the panel commands, with timing sped up by `--speed X`.
+- `--next-after S` presses Next by itself after S seconds of waiting (real time), so a step-mode session runs unattended. Lines on stdin steer it too: `n` or an empty line is Next, `p` pause or resume, `r` redo, `s` skip the section, `q` stop.
+- `--no-headset-button` leaves the headset's button alone (`ft-handrec --no-headset-button` too). `--button-device PATH` reads it from PATH instead, an event device or a FIFO of `input_event` structs, also in a dry run: a simulated button for tests.
+- `--auto` runs the timed flow; `--poses DIR` takes the pose pictures from DIR; `--plan` prints the sections, their steps and length.
+- `--ignore-cameras` (`ft-handrec --ignore-cameras` too) starts even when the camera check fails. A dry run and `--ring` skip the check by themselves.
+
+## Files
+
+```
+~/.local/share/frametop/hands/contrib/
+  profile.json                  consent and contributor id (below)
+  sessions/<YYYYMMDD-HHMMSS>/   (a second session started in the same second gets -2, and so on)
+    session.json                the session: checklist answers, lighting, versions, mode, takes
+    calibration.json            /persist/xrservice.json with identifying fields removed (below)
+    device.json                 the rig's pose in the CAD frame from /persist/device_config.json (below)
+    takes/<NN>-<section>/
+      sets.bin                  ft-hands' recording (FHSET01, hands/track/record.h), 10 sets/s: the first part
+      sets-2.bin, sets-3.bin, ...  the next parts (step mode: one per step; any mode: after a pause)
+      prompts.jsonl             what the person was asked to do, when (below)
+      poses.jsonl               head and controller poses from ft-handpanel (below)
+      take.json                 {"section", "title", "started_ns", "ended_ns", "status": "complete"|"stopped"|"skipped",
+                                 "deleted": [[from_ns, to_ns], ...], "notes": "",
+                                 "parts": {"sets.bin": {"names_swapped": false}, "sets-2.bin": {...}},
+                                 "clock": [[mono_ns, raw_minus_mono_ns], ...]}
+  exports/<session>/            what export writes (below)
+```
+
+All `_ns` times are CLOCK_MONOTONIC nanoseconds, the clock of `dqbuf_ns` in sets.bin and of `capture_ns` in the hands file. sets.bin's `capture_ns` is the camera clock (CLOCK_MONOTONIC_RAW). The two drift apart with NTP's corrections: on 2026-10-03 RAW ran 0.80 s ahead, gaining about 10 ppm. take.json `"clock"` samples the difference (RAW minus MONOTONIC, as ft-hands' `raw_minus_mono_ns()`) when each part starts and stops, so a set's exposure time on the poses' clock is `capture_ns - raw_minus_mono_ns`, interpolated between samples. `dqbuf_ns` is on the right clock already, but a few ms after the exposure. Takes recorded before 2026-10-03 have no `"clock"`.
+
+### profile.json
+
+```json
+{"schema": 1, "contributor": "<random uuid4>", "consent": {"version": "2026-10-02", "accepted": "<ISO time>", "adult": true},
+ "optional": {"handedness": "right|left|both|", "notes": ""}}
+```
+
+No name, email, or account. The contributor id is random, so several sessions from one person can be held out together in evaluation. Withdrawal also goes by that id.
+
+### session.json
+
+```json
+{"schema": 1, "tool": "ft-handrec <git describe>", "started": "<ISO>", "contributor": "<uuid>",
+ "lighting": {"chosen": "dim|room|daylight|indoor", "source": "measured|picked", "measured": "indoor|daylight|",
+              "ambient_ir": 0.0, "ring": {"<cam>": {"mean": 0.0, "dark_mean": 0.0}}},
+ "checklist": {"objects": ["pencil", "phone", "cup", "keyboard", "mouse", "gamepad", "small"], "own_objects": ["..."],
+               "controllers": "straps|none", "sleeves": "short|long|", "rings": false, "watch": false, "notes": ""},
+ "device": {"steamos": "<VERSION_ID from /etc/os-release>", "steamvr": "<version if known>", "cameras": [{"name", "width", "height"}]},
+ "mode": "step|auto", "quick": false, "shuffle": {"seed": 123, "sweeps": {"pose-sweeps": [{"id", "hands", "cues"}]}},
+ "takes": ["01-hand-size", "..."],
+ "camera": {"status": "ok|unknown|degraded", "reason": "..."}, "stop_reason": "...",
+ "sides": {"swapped": true|false|null, "decided_by": "auto|config|option|manual", "state": "decided|confirmed|...",
+           "evidence": {"as_named": 0, "swapped": 10, "seconds": 1.8, "miss_mm": [-1, 4.2], "probes": 30, "found": 10},
+           "decided_at": "<ISO>", "decided_ns": 0}}
+```
+
+`sides`: whether ft-camd's side camera names were backwards during the session (`swapped`), as the live tracker decided it (above, "Side cameras"); `null` while nobody knows. A part's names are right when its take.json `names_swapped` equals `swapped`. Parts without a `parts` entry were recorded with ft-camd's names. Sessions from before this have no `sides`.
+
+`camera` is the camera check's verdict at the start (no paths or log lines: those go to `session.log`). `stop_reason` is there when a session was stopped at the no-hands screen, with the check's result.
+
+A session started before step mode existed has no `mode`: it ran as `auto`. `quick` and `shuffle` (below, "Sweeps" and "Quick round") are missing from sessions before the sweeps.
+
+### calibration.json
+
+This is a copy of `/persist/xrservice.json` (`/run/host/persist/` in the container). Keep the cameras' intrinsics and extrinsics, and drop anything that identifies the unit: keys containing `serial`, `sn`, `uuid`, `mac` or `id`, or values that look like serial numbers. List what was removed in `session.json` (`"calibration_removed": [...]`), so a reviewer can check it.
+
+### device.json
+
+The head frame needs the rig's pose in the CAD frame, from `/persist/device_config.json`. Only two of its keys are kept, `cv.cad_from_cal` (Cam0 in the CAD frame) and `head` (the head in CAD), in the shape the labeller in frame-hands `train/label` reads, as its `cut.py` writes it:
+
+```json
+{"cv": {"cad_from_cal": {"method": "FrontAndUpperCamPositions", "plus_x": [x, y, z], "plus_z": [x, y, z], "position": [x, y, z]}},
+ "head": {"plus_x": [x, y, z], "plus_z": [x, y, z], "position": [x, y, z]}}
+```
+
+The rest of that file identifies the unit (serial number, display EDID) and is never copied. The two kept keys go through `strip_calibration` as well, and anything it removes is listed in `calibration_removed` as `device.json:<path>`. Sessions recorded before device.json existed have none: they still validate, with a warning, and the labeller falls back to another unit's pose.
+
+### prompts.jsonl
+
+One JSON object per line:
+
+```json
+{"t": 123, "event": "take", "section": "static-poses", "take": "03-static-poses"}
+{"t": 123, "event": "prompt", "id": "static-poses/fist/left/near", "text": "...", "hands": "left|right|both|none",
+ "pose": "fist", "distance": "near|mid|far|", "position": "centre|left|right|up|down|", "object": "", "controller": false}
+{"t": 123, "event": "target", "id": "touch/3", "head": [x, y, z], "room": [x, y, z], "state": "show|hold|done|timeout"}
+{"t": 123, "event": "bar", "target": 0.0}
+{"t": 123, "event": "feedback", "left": true, "right": false, "palm_m": [0.0, 0.0]}
+{"t": 123, "event": "pause"}
+{"t": 123, "event": "resume"}
+{"t": 123, "event": "ready", "id": "static-poses/fist/left/near", "seconds": 3}
+{"t": 123, "event": "wait"}
+{"t": 123, "event": "redo", "id": "static-poses/fist/left/near", "from": 123, "to": 123}
+{"t": 123, "event": "nohands", "id": "hand-size/flat/both", "reads": 120, "published": 118}
+{"t": 123, "event": "end", "status": "complete|stopped|skipped"}
+```
+
+`feedback` is written about twice a second while recording. It's the live tracker's view, kept for later checks; it's not a label.
+
+A prompt holds from its `prompt` until the next `prompt`, `ready`, `wait` or `end`. A step in step mode reads:
+
+```
+ready      Next pressed: recording part N starts, the 3-2-1 countdown runs (recorded, no label)
+prompt     the hold: its labels start here
+(bar, target, feedback, pause/resume during the hold)
+wait       the hold is over: no labels from here; part N stops
+```
+
+The touch-the-dot targets after the first follow straight on: no `ready` or `wait` between them. `redo` marks a try done again (R): `from` is that step's `ready` (or its `prompt` if it had none), `to` its end. Its prompt is skipped; the sets stay. In auto mode there's no `ready` or `wait`, and the intro is a recorded prompt `<section>/intro`. `nohands` marks the first hand-size step stopped because no hand was seen (below, "Camera check"); a `redo` over the same range follows it, so the try gets no labels. A sweep step (below, "Sweeps") has a `prompt` per cue, each with its `pose`, `"cue": true` and `"step"`, the step's id; its `ready`, `wait` and `redo` carry the step's id. Readers that knew only `prompt` and `end` keep working, but they'd give the countdown to the step before: `hub_review.py` (frame-hands `train/hub`) shows it as "(countdown)", redone prompts as "(redone)" and cues as "[pose] text"; `FORMAT.md` in the dataset repo has the rules.
+
+### poses.jsonl
+
+ft-handpanel writes one line per sample, 250 a second, from `GetDeviceToAbsoluteTrackingPose(TrackingUniverseStanding, 0)`:
+
+```json
+{"t": 123, "hmd": {"m": [12 floats, row-major 3x4], "r": 200, "ok": true},
+ "left": {"m": [...], "r": 200, "ok": true}, "right": null}
+```
+
+`r` is `ETrackingResult` (200 = Running_OK, 201 = Running_OutOfRange, and so on). `left` and `right` are the devices holding those controller roles, or null. No device serials are logged.
+
+## The panel (`ft-handpanel`)
+
+- **Placement.** A SteamVR overlay fixed to the head, like `gaze/panel/ft-gazepanel.cpp`: key `frametop.handpanel`, sort order 250. It sits 1.2 m ahead, centred 12 degrees above straight ahead, so the hands stay clear below it. It's 36 degrees wide, 4:3, 1024x768 pixels, dim and see-through. It's drawn on the CPU with stb_truetype (and stb_image for the pose pictures, PNG only, the same pinned stb commit) into three shared DMA-BUFs SteamVR imports once, as ft-gazepanel does, and is drawn again only when something changes.
+- **Layout.** The title and step on top (a red "Rec" by the step while recording), a rule. With a pose picture or a diagram, a 14-degree column on the left holds the picture (or the flipped copy and the picture side by side) and the where-to diagram under it; the text takes the right. The text column holds the instruction, the orange note, the big countdown ("3", "2", "1", then "Hold" or "Go") and the cyan action line ("Ready? Press Space or click Next"), centred together. At the bottom: the near/far bar, the hand chips, the time-left bar and the key hints.
+- **Socket.** Abstract unix datagram `@ft_handpanel` (`--socket NAME`). A sender with an address gets `ok ...` or `error ...`.
+- **Options:** `--watch-stdin` (quit when stdin closes), `--socket NAME`, `--distance M`, `--no-vr`. `--no-vr` makes no SteamVR connection and prints each picture's text to stdout: for testing without a headset.
+
+Commands (UTF-8; `|` starts a new line in text):
+
+| Command | Effect |
+|---|---|
+| `show` / `hide` | The panel. A "show" makes it visible with its first picture. |
+| `title <text>` | Big line at the top. |
+| `step <text>` | Small line at the top right, e.g. `Section 3 of 11`. |
+| `text <text>` | The instruction, large, wrapped to the panel's width, centred. |
+| `note <text>` | An orange line under the instruction: a warning ("I can't see your left hand"). Empty clears it. |
+| `countdown <0..1>` / `countdown off` | A thin bar along the bottom: the share of this prompt's time left. |
+| `hands <left> <right>` | Two chips, "Left hand" and "Right hand", each `seen` (green), `lost` (orange) or `off` (hidden). |
+| `bar <target 0..1> <current 0..1 or -1> [near label] [far label]` / `bar off` | The near/far bar for the push out and back: a horizontal track with a target marker and the hand's current position. |
+| `paused on` / `paused off` | A "Paused" overlay over the picture. |
+| `image <path> [mirror\|both]` / `image off` | The pose picture, a PNG (below), in the left column. `mirror` flips it (a left hand); `both` draws a flipped copy on its left. A file that can't be read: `error ...` and no picture. |
+| `where <position\|-> <distance\|->` / `where off` | The where-to diagram under the picture: a 3x3 front view with the asked cell lit (`centre`, `left`, `right`, `up`, `down`, and the push sections' `chest`, `desk`, `eye`), and a side view of the head and three marks for `near` ("Close"), `mid` ("Halfway out") and `far` ("Arm out"). `-` leaves that half out. |
+| `action <text>` | The cyan line under the instruction (empty clears it). |
+| `big <text>` | Large cyan text under the instruction: the countdown (empty clears it). |
+| `keys <text>` | The faint key hints along the bottom. |
+| `rec on` / `rec off` | The red "Rec" by the step line. |
+| `strip <cue> <path>\|<mode>\|<label>;...` / `strip off` | A sweep's row of pose pictures (path `-`: none; mode `-` or `mirror`), each with its label under it; the one at index `cue` (from 0, -1 for none) framed in cyan and bright, the others dim. It sits along the bottom of the space left, the where-to diagram at its right end if there is one, and the text above it; it takes the left column's place. Each picture is loaded once. A file that can't be read: `error can't read ...`, and that item shows an empty frame. |
+| `target <x> <y> <z> [show\|hold <0..1>\|done]` / `target off` | The touch target: a small sphere-like dot about 2 cm across, in its own overlay (`frametop.handpanel.target`). The point is in the head frame (metres, +x right, +y up, -z forward). The first `target` with a new point places it in the room with the current HMD pose, and it stays there. Later commands with the same point change only the state. `hold` draws a filling ring, `done` turns it green. Reply: `ok <room x> <room y> <room z>`. |
+| `poses start <path>` / `poses stop` | Log poses to the path (appending, `poses.jsonl` format above) from a thread at 250 Hz, until stopped. |
+| `devices` | Reply: `ok hmd <r> left <r or -> right <r or ->`, the current `ETrackingResult` values (`-` for no device in that role). |
+| `head` | Reply: `ok <12 floats>`, the current HMD pose (standing universe). |
+| `ping` | `ok shown` or `ok hidden`. |
+
+It quits on SteamVR's quit event, as ft-gazepanel does. `--no-vr --dump DIR` writes each picture to `DIR/panel.pam`, to check the layout without a headset.
+
+## The pose pictures (`poses/`)
+
+`poses/poses.json` maps the script's `pose` ids to pictures: `{"<pose>": {"file": "<name>.png", "two_hands": false, "caption": "..."}}`. Each PNG is RGBA, square (512x512), drawn as the wearer sees it: a right hand, unless `two_hands` (then it shows both). How a prompt shows it (`session.pose_view`):
+
+| Prompt's `hands` | Picture |
+|---|---|
+| `right` (and `any`, `none`, empty) | as drawn |
+| `left` | flipped left to right (`image ... mirror`) |
+| `both`, not `two_hands` | a flipped copy on the left, the picture on the right (`image ... both`) |
+| anything, `two_hands` | as drawn |
+
+A pose with no entry, or whose file is missing, shows no picture: the text alone. The session reads `poses.json` when it starts. The window shows the same picture (QML `Image.mirror`), its caption, and the same diagram.
+
+## The script (`script.json`)
+
+```json
+{"version": 1,
+ "cue_names": {"thumbs-up": "Thumbs up", "...": "..."},
+ "sections": [
+   {"id": "hand-size", "title": "Hand size", "requires": [], "intro": "text shown before the first prompt: 4 s, or until Next", "go": "Hold",
+    "quick": true, "prompts": [{"text": "...", "cues": ["flat", "flat-back", "spread"], "cue_s": 5, "hands": "both", "distance": "mid"}]},
+   {"id": "pose-sweeps", "title": "Hand poses", "kind": "sweep", "quick": true, "cue_s": 4, "step_s": 20,
+    "groups": [["open", "fist", "point", "pinch"], ["ok", "thumbs-up", "spread", "claw"], ["count-1", "...", "count-5"]],
+    "sweeps": [{"hands": "both", "group": "next", "text": "..."}, {"hands": "left", "group": "any", "quick": false, "text": "..."}]},
+   {"id": "objects", "title": "Things you hold", "requires": ["objects"], "for_each": "object",
+    "prompts": [{"text": "Pick up the {object} and use it the way you normally would.", "seconds": 15, "hands": "both", "object": "{object}"}]},
+   {"id": "touch", "title": "Touch the dot", "kind": "targets", "hold_s": 1.0, "timeout_s": 8,
+    "targets": [[0.0, -0.15, -0.40], ...], "text": "Touch the dot with your index fingertip and hold still."},
+   {"id": "controller-push", "title": "Depth with controllers", "requires": ["controllers"], "kind": "bar",
+    "intro": "...", "heights": ["chest", "desk", "eye", "left", "right"], "reps": 5, "period_s": 6, "near_m": 0.2, "far_m": 0.6}
+ ]}
+```
+
+- `requires`: `objects` (at least one object ticked), `controllers` (straps ticked). A section whose requirements aren't met is skipped and logged.
+- `go`: the word the countdown ends on, "Go" unless set ("Hold" for the still poses).
+- `quick`: the section is in a quick round; a step with `"quick": false` isn't (below).
+- `kind`:
+  - `prompts` (the default): each prompt shows for its `seconds` with a countdown. A prompt with `cues` (and `cue_s`) is a sweep step with those cues in that order, `seconds` = cues x cue_s (hand size; the mouse and switch step).
+  - `sweep`: steps built from `sweeps` (below).
+  - `targets`: each target shows until the live index tip is within 3 cm of it for `hold_s`, or `timeout_s` passes.
+  - `bar`: the target marker sweeps near to far and back, `reps` times per height, at `period_s` per sweep. The current marker follows the live palm distance.
+- Each section is one take. Prompts within it are marked in `prompts.jsonl`.
+- `cue_names`: the short labels under the strip's pictures (otherwise the pose id).
+
+### Sweeps
+
+The second in-headset session (sessions/20261002-202734) took about 16 min and was "super long and kind of annoying": the 36 held poses alone took 7.9 min, 3.2 of it reading, and the person skipped the wrist turns and gave up on the bare push after 3 steps. The labels come from the auto-labeller (teacher model and triangulation, frame-hands `train/label`), not from the prompts, so what the recordings need is variety (shapes, distances, angles), not clean holds. So the poses are swept:
+
+- A sweep step shows a strip of 2-5 pose pictures and asks for slow, continuous movement (near and far, all around) while the hands change shape with the lit picture. The light moves on every `cue_s` (4 s), cycling, over `step_s` (20 s): 5 cues for a group of 4 or 5. Each cue is a `prompt` event with that `pose`, `"cue": true` and `"step"` (the step's id); `distance` and `position` are "" (varied). So the timeline tags each pose roughly, and the countdown, `wait` and `redo` work per step as before. The time-left bar covers the whole step.
+- `groups`: lists of poses. A step takes `"group": "next"` (the groups in turn) or `"any"` (one drawn at random, a different one for each "any" while there are groups left), or names its own `cues`. `"shuffle": false` (gestures) keeps the script's order; `"cycle": false` runs the cues once; `"fixed": true` keeps one step's order.
+- The pose sweeps: 3 two-hand sweeps, one per group ([open, fist, point, pinch], [ok, thumbs-up, spread, claw], [count-1 ... count-5]); then a left-hand and a right-hand sweep (the other hand in the lap) on groups drawn from those three, which also turn the wrist as they go, so the wrist angles come for free (the old wrist-turns section is gone).
+- **The shuffle, per session.** The groups' order, the "any" draws and the cues' order in each step are shuffled with a seed from the session's id (`session_seed`: the first 8 hex digits of its SHA-256), separately per section (`random.Random("<seed>/<section>")`). The sections' order isn't shuffled (the controller sections need their before and after). session.json records `"shuffle": {"seed", "sweeps": {section: [{"id", "hands", "cues"}]}}`, and `build_plan(script, checklist, seed=...)` gives the same again. `--seed N` overrides it; `--plan` without one shows the script's order.
+- The strip has one picture per pose, a single hand: both hands make the same shape, and five pairs wouldn't fit. A left hand's pictures are flipped.
+- Gestures are sweeps too, in order and once: tap then drag; grab, cross, overlap; near the face then a screen's distance. Hand size is one step of three held shapes (flat, backs, spread; 5 s each), still the no-hands check's first step.
+
+### Quick round
+
+For more lighting rounds: "Quick round (about 3 min)" on the checklist page, `session.py --quick`. It has the sections marked `quick` (hand size, the pose sweeps without the one-hand ones, touch the dot, no hands), about 2 min recorded in 6 steps. session.json gets `"quick": true`. The checklist page suggests it (and picks it) once a full session has gone to the end (`Backend.hasFullSession`: a session.json with status `done`, not quick, not a dry run).
+
+### Step mode (the default) and auto mode
+
+The first in-headset session (2026-10-02) went too fast: each prompt advanced after 4-8 s, before there was time to read it and find the hand shape. So by default every step waits:
+
+1. **Ready.** The panel shows the step: section title, "step N of M", the instruction, the pose picture, the where-to diagram, and the Next hint ("Ready? Press the button on the right side of the headset", or with a mouse also Space and Next: see Controls). The hand chips show which hands are seen, with no warnings yet. It waits as long as it takes, and nothing records.
+2. **Countdown.** Next starts a new recording part and a "ready" event, and the panel counts 3, 2, 1 (big), recorded so the hold is captured from its first frame. In the push sections the bar sits at near meanwhile.
+3. **Hold.** The `prompt` event, the section's word ("Hold" or "Go") and the time-left bar for the prompt's seconds (or the bar's sweeps, or the targets). Then a `wait` event and the part stops.
+
+Steps that wait: each prompt, each bar height, and the first touch-the-dot target (the others follow straight on, as each waits for the touch anyway). Before a section, one screen shows the section's intro (with its `before` text, such as putting on the controllers) and waits for Next too; the welcome screen as well. The take starts with the section's first countdown, so a section skipped at its intro leaves no take. A pause in a hold works as before (the part stops; resume starts the next one).
+
+Auto mode ("Advance by itself" on the checklist page, `session.py --auto`) is the old timed flow: the welcome, the between and before screens, the intro (recorded) and each prompt for its seconds, one recording per take. R still works there: it restarts the step running.
+
+Steps are 20 s sweeps, 16-18 s gestures, 10-12 s desk and object steps, the touch targets (6) and the push heights (2, 3 reps of 6 s). The core session (no objects, no controllers) records about 5 min in 15 steps; with 5 s of reading a step that's about 6 min. Everything ticked (four objects, controllers): about 7.3 min recorded in 24 steps. A quick round: about 2 min in 6 steps. The window and `session.py --plan` give these (`plan_summary`); in step mode they leave the reading time out and say so.
+
+The sections, in this order (see the plan):
+1. hand size (one step: flat, backs, spread)
+2. pose sweeps (above: 3 with both hands, one with each hand)
+3. gestures (3 sweeps: pinch taps and drags; grabs, crossing and overlapping; near the face, then pointing at screen distance)
+4. desk work (typing or pretend typing; the mouse, with switching to the keyboard when both are there)
+5. objects (one prompt per ticked object, own objects included)
+6. touch the dot (6 dots spread near and far, left and right, low)
+7. controller depth, straps (push out and back at chest and eye level, 3 reps each; then the wrists and fingers with the controllers on). "Out and back" is straight away from the headset and back toward it: the first in-headset session took the left-right bar for sideways. The texts say so, the bar's ends read "At your chest" and "Arm out" (`near_label`, `far_label`, sent as `bar ... At your chest|Arm out`), and the picture is a side view.
+8. bridge (one controller on, the bare fingertip on its thumbstick while that hand moves from close to arm's length and back, then swap; then a controller on the desk, touched from the front and above, then from the sides: 4 steps, the controller changes during the ready screens)
+9. bare repeat of section 7's pushes, controllers off
+10. no hands (10 s)
+
+Before section 7: "Put on both controllers and tighten the straps". Before section 9: "Take the controllers off and put them out of view".
+
+### Feedback while recording
+
+- **Hands seen:** from the hands file. A hand counts as seen if its flags match the side and the file is fresh (publish within 0.3 s). Prompts with `hands` set show the `hands` chips. If an asked-for hand is lost for more than 1.5 s, the note says "I can't see your left hand: bring it into view".
+- **Controller tracking:** in sections 8 and 9, `devices` is polled once a second. A result other than 200 for more than 1 s says "The left controller lost tracking: turn your palm slightly toward you". Each such stretch goes into `prompts.jsonl` as `feedback` with `"controller": {...}`.
+- **Lighting, measured:** the checklist page measures the light when it opens, starting ft-camd (`frametop-handrec-camd.service`) if nothing runs it; the window stops it again on quit if it started it. The mean of every mono camera's `mean` and `dark_mean` from the ring (`hands/tools/ring.py` layout; struct only, no numpy) is compared with the person's earlier sessions. If it matches an earlier round's within 15%, the window says so before starting.
+- **Lighting label:** "Measured by the cameras" is the default. `ambient_ir`, the mono cameras' mean `dark_mean` (the room's infrared), labels the round `daylight` from 6.0 and `indoor` below (`session.classify_lighting`). Lamps and LEDs give off hardly any infrared, so a dim room and a lit one read about the same (1.8 by one lamp, 2.2 in a lamp-lit room) and the cameras can't tell them apart; the person can pick dim, room or daylight instead (`source: "picked"`). The 6.0 threshold is a guess until a daylight round is measured.
+
+### Camera check
+
+On 2026-10-02 a whole session showed "I can't see your hands": after the headset slept, SteamVR had failed to load the colour module's FPGA image, which left the upper cameras and the IR light off (`hands/README.md`, "Camera check"). Two checks keep that from wasting a session:
+
+- **Before the session.** The window runs `hands/camcheck.py` when the checklist page opens ("Tracking cameras:", with the evidence under Details and Check again), and again when Start is pressed; `session.py` runs it first thing, before it makes the session's folder or starts anything (`Session._preflight`). If it finds the cameras degraded, the session doesn't start. The window says: "The headset's upper cameras and IR light are off. SteamVR couldn't start the colour camera module (it happens sometimes after the headset sleeps). Restart SteamVR, or restart the headset if that doesn't fix it." (another `degraded:` reason gets a sentence naming it), and Start stays off. `unknown` (SteamVR not running, the cameras asleep) doesn't stop it: the session's own start fails clearly then. From the command line, `session.py` prints the check and exits with status 3.
+- **Restart SteamVR.** The message has a Restart SteamVR button. After a confirmation it runs `systemctl --user restart --no-block steamvr.service` on the host (through `distrobox-host-exec`), then checks the cameras every 3 s, for up to 2 minutes, until a new XRService has opened its cameras. The confirmation says what really happens: every VR app closes, and so does the Frametop desktop with all its windows, this one included, and it doesn't come back by itself (`hands/README.md`, "What a SteamVR restart does to Frametop"). So the check after the restart mostly happens when the recorder is opened again; it re-runs when the checklist page opens. `--no-block` lets the restart finish after the window is gone.
+- **No hands in the first step.** The first step of the hand-size section has both hands up, about 40 cm away. During its hold, the session counts the hands file's reads (about 20 a second). If the tracker published in at least half of at least 10 reads and never saw a hand, the step stops: a `wait` and the recording stops as usual, then a `nohands` event and a `redo` over the try. The session runs the camera check and shows "I can't see your hands" with its result (the camera text above when it's the VCINT failure, else "The camera check found nothing wrong"). The state is `nohands`, waiting: Next (the headset button, Space, Try again) or R starts the same step's countdown at once; Stop (Esc) ends the session with `stop_reason` set; S skips the section. One missed step costs a retry, not the session, and every hold of that step is logged ("hands check ...: a hand in N of M reads"). Without a tracker publishing the session can't tell, logs that, and goes on. Only that one step is checked: later steps have their notes ("I can't see your left hand") as before. Auto mode does the same; its recording pauses meanwhile.
+
+### Controls
+
+- The window has Start, a big Next (while a step waits; its hint is the panel's), Pause/Resume, Redo step, Skip section and Stop. While it has focus: Space is Next, P pauses or resumes, R redoes, S skips the section, Esc stops. The panel's bottom line and the window list them. The window also shows the step's picture, diagram, countdown and "Hold".
+- **The headset's button.** The Frame has a click button on its right side, for use without controllers: `KEY_SELECT` (353) on the evdev device `gpio-keys`. While a step waits (the welcome, a section's intro, a step's ready screen) a press is Next; during a countdown or hold (and auto mode's timed screens) it pauses; while paused it resumes. The session finds the device in `/proc/bus/input/devices` by name and its KEY bitmap (`event3` on the maintainer's Frame) and reads `input_event` structs with plain `struct` (no python-evdev), from a thread. Only key-downs count (value 1: releases and autorepeat, value 2, don't), and presses closer than 0.3 s count once.
+  - It's read, never grabbed (`EVIOCGRAB`). Frametop's input relay (`input/input-relay.py`), ft-powerd, SteamVR and gamescope read the same device, and the relay remaps its volume keys (the experimental branch's `docs/hazards.md`). A grab would take the volume keys from the relay.
+  - `steamos` is in the `input` group, so it needs no sudo. The dev container sees the host's `/dev/input` and `/proc/bus/input/devices`, and the group carries over (checked 2026-10-02), so it works from the window there and from `session.py` on the host. If the device is missing or can't be opened, the session logs it, keeps trying every 5 s, and the hints don't mention the button.
+  - **Not known yet (needs the headset):** what SteamVR and gamescope do with the same press. They read it too, so it may also click whatever is under the head or gaze pointer in VR, or open something. Check on the first session; if it does, the fix is on their side or a different button, not a grab.
+- **The Next hint follows what's there.** No mouse connected: "Ready? Press the button on the right side of the headset" (the window's Next can't be clicked, and Space needs the window focused). A mouse: "Ready? Press Space, click Next, or press the headset button". No button: "Ready? Press Space or click Next". The panel's bottom line leads with "Headset button: next, pause". A mouse is a device in `/proc/bus/input/devices` with EV_REL, REL_X and REL_Y that isn't made in software: uinput devices (Frametop's virtual mouse, frame-voice's keyboard) sit under `/devices/virtual/input` or on the virtual bus (6), and are left out; Bluetooth mice come through uhid, under `/devices/virtual/misc/uhid`, and count. It's looked at again at each step, so a mouse plugged in mid-session counts from the next step.
+- **R (redo).** During a step's countdown or hold: that step starts again from its ready screen. At a step's ready screen: the step before it (in this section) goes again. Either way a `redo` event marks the range of the try being redone, so its labels are skipped; the sets stay, to delete in review if wanted.
+- A pause stops the take's recording and starts it again on resume as the next part of the same take (`sets-2.bin`, and so on). takes.py reads all parts in order. A pause while a step waits only shows "Paused"; a Next pressed while paused doesn't count.
+
+## Review and export (`takes.py`, the window)
+
+- **Review.** Each session lists its takes: title, duration, status, a thumbnail (the first set's `slam_left`). A viewer shows one frame set (all cameras side by side, 8-bit grey) at a time with a slider. It can mark a range and delete it. Deleted ranges go into `take.json`, and export leaves them out; the files keep everything until export. A whole take or session can be deleted (files removed, after a confirmation).
+- **Export.** It writes `exports/<session>/`:
+  - `manifest.json`: profile fields except `optional.notes` unless kept, session.json (without its `uploads` records), takes, schema, tool version, the consent version.
+  - `calibration.json` and `device.json`, when the session has them.
+  - Per take: `prompts.jsonl`, `poses.jsonl`, `take.json`, and `sets.bin.zst` (sets in deleted ranges removed, then zstd -10 with 2 threads).
+  - The side cameras are named right in every exported set when the session's `sides.swapped` is known: parts that need it get slam_left and slam_right (and their `_dk`) exchanged in the set headers as they're compressed. The exported take.json says `"parts": {"sets.bin": {"names_swapped": <swapped>}}`, and the manifest's take entry `"sides": {"names_swapped", "renamed_sets"}`. Unknown, the names stay as recorded.
+  - `poses.jsonl` and `prompts.jsonl` without what's in the deleted ranges: no poses and no live-tracker `feedback` there (the prompt timeline stays). With the checklist's controllers at `none`, the controllers' poses are null and `feedback` has no `controller` (`takes.export_jsonl`): controllers left switched on still get tracked, and their poses would pass for the hands' ground truth.
+  - `SHA256SUMS`.
+
+  Compression runs at nice 19. While it runs with the headset worn, the window notes that VR may stutter a little (exports are done in the headset). Worn is judged the way `frame-job` does: `vrcompositor` runs and a `/sys/class/backlight/*/brightness` reads over 0 (SteamVR turns the panel off 5 s after the headset comes off). CPU work while in VR causes stutter. The proximity sensor is no use here: it read 9-43 with the headset sitting unworn.
+- **Upload.** The Upload page uploads an export from the window, logging in included: no terminal. Below its steps it shows `UPLOAD.md` ("About uploading"), with the export's path, size and contributor id filled in.
+  - **`hands/rec/validate.py`** (standard library) checks an export. The window runs it before an upload, and the maintainer runs it on each submission (`validate.py DIR [--json]`, exit status 1 on errors). It checks:
+    - `SHA256SUMS`: every file listed and matching.
+    - An allow-list: `manifest.json`, `calibration.json`, `device.json` and `SHA256SUMS` at the top, and `prompts.jsonl`, `poses.jsonl`, `take.json` and `sets.bin.zst` in `takes/<NN>-<section>/`. Anything else is an error, and so is a symlink.
+    - The manifest's schema, keys and types, and that it matches the files.
+    - The consent version is present and the contributor confirmed being an adult. The contributor id is a uuid4.
+    - `calibration.json` has nothing that `session.py`'s `strip_calibration` would still remove.
+    - `device.json` holds only `cv.cad_from_cal` and `head`, each `plus_x`, `plus_z` and `position` as 3 numbers (plus `cad_from_cal`'s `method`). Without it: a warning.
+    - Each `sets.bin.zst` decompresses to its end, so a truncated one fails, and every set's FHSET01 header is sane: camera names, sizes, record length. Set counts and raw bytes match the manifest. Pixels aren't decoded.
+    - Every jsonl line parses.
+    - `session.sides` is `{"swapped": true|false|null}`, and every take's `sides.names_swapped` equals it (else an error: export again). Without `sides`, or `null`: a warning (the maintainer's check tells).
+    - The total size: a warning over 15 GB, an error over 40 GB.
+
+    Warnings cover notes kept in the export, a home folder path in the manifest, and missing `poses.jsonl` files.
+
+    It runs on Linux and on Windows (the maintainer's PC) with Python 3.12 or later. It decompresses with Python 3.14's `compression.zstd`, else the `zstandard` package, else the `zstd` program, and handles several zstd frames in a row.
+  - **`hands/rec/hub.py`** does the upload. It runs as a child process of the window (Cancel ends it), or from the command line (`hub.py [--base DIR] whoami | login | upload SESSION [--dry-run] [--again] [--json]`). It uses `huggingface_hub` (`python3-huggingface-hub` in the dev container) with the login saved in huggingface_hub's token file.
+    - **`login`** is huggingface_hub's browser login (OAuth device code), the same as `hf auth login`'s default since huggingface_hub 1.x. It asks Hugging Face for a link (`https://hf.co/oauth/device`) and a short code, prints them (`{"phase": "code", "url", "code", "expires_in"}`), and waits while the person enters the code in their browser and approves. Then it saves the token, which can refresh itself. Nobody types or pastes a token, and the window never sees one. It uses huggingface_hub's own helpers (`request_device_code`, `poll_device_token`, `_save_oauth_token`), as there's no public call that hands back the code. On 2026-10-03 the code lasted 5 minutes and wasn't filled into the link. The consent screen lists the person's organizations: none are needed, as a pull request on a public dataset comes from the person's own account.
+
+    An upload goes through these steps: An upload goes through these steps:
+    1. Validate, and stop on errors.
+    2. Stop if the same export was uploaded before (same `SHA256SUMS`), unless asked again.
+    3. Stop while the texts are drafts, unless `FT_HANDREC_ALLOW_UPLOAD=1`.
+    4. `whoami`: a read-only token is refused.
+    5. `auth_check` on the dataset: a gated dataset whose terms aren't accepted gives "accept the dataset's terms first", with the link.
+    6. Open the pull request first: `create_pull_request(HF_DATASET, title, description=...)`, an empty draft. Its link goes to the window right away (`{"phase": "opened", "pr_url"}`), which tells the person to plug the headset in and leave it. Record `{"repo", "pr_url", "pr_num", "started", "export_sha", "status": "started"}` in `uploads` in `session.json`. A retry of the same export goes on in that pull request while it's draft or open.
+    7. `upload_folder(repo_id=HF_DATASET, repo_type="dataset", folder_path=EXPORT, path_in_repo="contributions/<contributor>/<session>", revision="refs/pr/N", commit_message=..., commit_description=...)`. The description summarizes the manifest: takes, minutes, sets, lighting, objects, controllers, the consent and tool versions, the size, and validate's warnings. Then mark the pull request open if it's still a draft (the maintainer's `list` shows open ones, so drafts are uploads still in progress).
+    8. Mark the record `"status": "done"` with `uploaded`. `export_sha` is the SHA256 of `SHA256SUMS`. The file keeps its modification time, so the export doesn't count as out of date. Only finished records count as "uploaded before" (records without a status are from before 2026-10-03 and finished).
+
+    Errors get a plain explanation: not logged in, a login Hugging Face rejects (401), a login that can't open a pull request (403), terms not accepted, dataset not found, network errors. `--dry-run` does everything except the network calls and the record, and lists what it would upload.
+  - **The page** has three numbered steps:
+    1. Choose the export, with its size.
+    2. Log in to Hugging Face. The page shows whether someone is logged in (`whoami`). Log in runs `hub.py login`, opens the link in the browser, and shows the code large, with Copy code and Cancel. "Use another account" logs in again. A classic read-only token counts as not logged in.
+    3. Upload, with a note to accept the dataset's terms the first time.
+
+    Upload has Cancel, the phase with a progress bar (a share while the export is checked, a sweep while it's sent, as `huggingface_hub` reports no progress), the pull request's link once it's open, with "plug in the headset and leave it plugged in until this says Uploaded", and Uploaded at the end. If this export was uploaded before, the page says so, and uploading it again asks first. A stale export can't be uploaded.
+  - **Staying awake:** while an export or an upload runs, the window holds a host unit, `frametop-handrec-awake.service`, running `systemd-inhibit --what=sleep:idle --mode=block ... sleep infinity`, and stops it when the last of them ends (or on quit). It's meant to keep Steam from putting the Frame to sleep with the headset off; whether Steam's sleep honours a logind block inhibitor is still to be checked on the device. Exports and uploads are done in the headset: the export page only notes that VR may stutter a little while it compresses.
+  - **While the texts are drafts**, Upload stays off unless `FT_HANDREC_ALLOW_UPLOAD=1`, so the maintainer can rehearse against a private test repo. `FT_HANDREC_DATASET` overrides `HF_DATASET`. `ft-handrec --hub-dry-run` makes Upload a dry run: no network, so it isn't held back by the drafts.
+  - **Rehearsal: `hands/rec/rehearse.sh [--repo ID]`** runs it all without the headset, in the dev container, in one `frame-job --local` scope when frame-job is installed. `ft-ringplay` plays 30 s of a recording into a ring in `/run/user/UID`. A tracking ft-hands that's already running is used, or one is started on that ring. `ft-handpanel --no-vr` stands in for the panel. `session.py --no-start --next-after 0.3` records a three-section test script (a prompt, a two-cue sweep, no hands) in step mode, three parts of 6 s (countdown and hold), about 360 MB once exported. Then `takes.py` exports, `validate.py` checks, and `hub.py` uploads: a dry run by default, or for real to `--repo ID` with `FT_HANDREC_ALLOW_UPLOAD=1`. It prints a summary, deletes its temporary folders (camera images of a room) and stops everything it started, Ctrl+C included. The `--no-vr` panel logs no poses, so `poses.jsonl` is missing there (a warning).
+
+## Licensing and consent (texts in `CONSENT.md`)
+
+- The dataset is CC BY-NC 4.0.
+- Contributors also grant the maintainer (DeeJanuz) a broad, non-exclusive license to their contribution.
+- Contributors confirm they're 18 or older.
+- The text explains what's recorded and that nothing uploads automatically, how review works, how to withdraw (by contributor id), and that a withdrawal is purged from the repo's history.
+- The texts need a legal review before the dataset launches. Until then they carry a "draft" banner, and the Upload page says contributions aren't open yet.
+- The dataset repo: `HF_DATASET` in `hub.py`, `DeeJanuz/frametop-hands` (private until launch).
diff --git a/hands/rec/UPLOAD.md b/hands/rec/UPLOAD.md
new file mode 100644
index 0000000..22e2ed3
--- /dev/null
+++ b/hands/rec/UPLOAD.md
@@ -0,0 +1,9 @@
+### About uploading
+
+- **What's sent:** the export in `@EXPORT_PATH@` (@EXPORT_SIZE@), into `contributions/@CONTRIBUTOR@/@SESSION@` in [@DATASET@](https://huggingface.co/datasets/@DATASET@). Upload first checks that every file is complete and matches its checksum, and that nothing identifying is left in.
+- **Your account:** the pull request comes from your Hugging Face account, and anyone can see its username next to your contributor id, `@CONTRIBUTOR@`. The dataset itself credits the contributor id, not your name. The login stays saved on this headset, so you only log in once.
+- **The dataset's terms:** the first time, open the dataset's page and accept its terms. Until you have, Upload stops with "accept the dataset's terms first".
+- **Once your pull request's link shows, plug in the headset and leave it plugged in until this page says Uploaded.** A round is several gigabytes, so this can take a while. You can take the headset off: the Hand Recorder keeps it awake until the upload is done. Keep the Hand Recorder open, since closing it stops the upload.
+- **If it stops partway** (Cancel, or the network drops), press Upload again. It carries on in the same pull request, and files already sent aren't sent twice.
+- **The maintainer's review:** they check that the files are complete, and that nobody else and nothing private is in view, before merging. You can follow it and answer questions on the pull request's page. Once it's merged, you can delete the session and its export here to free the space.
+- **Withdrawing:** see "Withdrawing" in the consent text. You'll need your contributor id, `@CONTRIBUTOR@`.
diff --git a/hands/rec/build.sh b/hands/rec/build.sh
new file mode 100755
index 0000000..21a730f
--- /dev/null
+++ b/hands/rec/build.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Build the hand recorder's headset panel ft-handpanel in the dev container on the Frame
+# (hands/rec/build/; it also runs there). Like gaze/build.sh: the pinned public OpenVR header
+# (the DMA-BUF import is newer than the header shipped with SteamVR's samples), stb_truetype
+# for the text and stb_image (PNG only) for the pose pictures, at the same stb commit.
+set -euo pipefail
+root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
+"$root/scripts/sync.sh" >/dev/null
+exec "$root/scripts/frame.sh" -C hands/rec 'set -e; mkdir -p build/include
+openvr=v2.15.6
+[ -f build/include/openvr-$openvr ] || { curl -fsSL "https://raw.githubusercontent.com/ValveSoftware/openvr/$openvr/headers/openvr.h" -o build/include/openvr.h && touch build/include/openvr-$openvr; }
+stb=2c980bb59875b0d32144a71867fbdebb2f77cd20
+[ -f build/include/stb-$stb ] || { curl -fsSL "https://raw.githubusercontent.com/nothings/stb/$stb/stb_truetype.h" -o build/include/stb_truetype.h && touch build/include/stb-$stb; }
+[ -f build/include/stb_image-$stb ] || { curl -fsSL "https://raw.githubusercontent.com/nothings/stb/$stb/stb_image.h" -o build/include/stb_image.h && touch build/include/stb_image-$stb; }
+g++ -std=c++17 -O2 -Wall -Wno-unused-parameter -Wno-missing-field-initializers -Ibuild/include $(pkg-config --cflags gbm libdrm) \
+  -o build/ft-handpanel panel/ft-handpanel.cpp -L/opt/steamvr/bin/linuxarm64 -lopenvr_api -Wl,-rpath,/opt/steamvr/bin/linuxarm64 \
+  $(pkg-config --libs gbm libdrm) -lpthread
+echo "built build/ft-handpanel"'
diff --git a/hands/rec/ft-handrec b/hands/rec/ft-handrec
new file mode 100755
index 0000000..a9d4da9
--- /dev/null
+++ b/hands/rec/ft-handrec
@@ -0,0 +1,21 @@
+#!/bin/bash
+# Launch the Frametop Hand Recorder from a Plasma session on the Frame host.
+# The app runs in the dev container (PySide6, Kirigami and zstd come from Fedora there).
+# podman needs the real XDG_RUNTIME_DIR and the real user bus (to reach systemd for
+# the container's cgroup; the Frametop session runs on a private bus from
+# dbus-run-session). The session's Wayland socket and bus go to the app itself.
+# Options go to ft_handrec.py: --base DIR, --page NAME, and --dry-run for testing.
+here=$(cd "$(dirname "$(readlink -f "$0")")" && pwd)
+wl=${WAYLAND_DISPLAY:-wayland-0}
+case $wl in /*) ;; *) wl="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/$wl" ;; esac
+session_bus=${DBUS_SESSION_BUS_ADDRESS:-}
+export XDG_RUNTIME_DIR=/run/user/$(id -u)
+export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus
+# From the home folder: the app's host commands (distrobox-host-exec) run in its folder on the
+# host, and a folder only the container has, such as /run/host/tmp, makes them all fail.
+cd "$HOME" || exit 1
+"$here/../../scripts/container-up.sh"
+exec "$HOME/.local/bin/distrobox" enter dev -- env WAYLAND_DISPLAY="$wl" DISPLAY="${DISPLAY:-}" \
+  XAUTHORITY="${XAUTHORITY:-}" DBUS_SESSION_BUS_ADDRESS="$session_bus" \
+  QT_QPA_PLATFORM="wayland;xcb" \
+  python3 "$here/ft_handrec.py" "$@"
diff --git a/hands/rec/ft-handrec.desktop b/hands/rec/ft-handrec.desktop
new file mode 100644
index 0000000..e49e2d3
--- /dev/null
+++ b/hands/rec/ft-handrec.desktop
@@ -0,0 +1,9 @@
+[Desktop Entry]
+Type=Application
+Name=Frametop Hand Recorder
+GenericName=Record your hands for the hand dataset
+Comment=Record, review and export hand recordings for Frametop's open hand dataset
+Exec=@REPO@/hands/rec/ft-handrec
+Icon=camera-video
+Categories=Utility;
+Keywords=hands;hand tracking;dataset;record;frametop;
diff --git a/hands/rec/ft_handrec.py b/hands/rec/ft_handrec.py
new file mode 100755
index 0000000..49a323c
--- /dev/null
+++ b/hands/rec/ft_handrec.py
@@ -0,0 +1,1214 @@
+#!/usr/bin/env python3
+"""Frametop Hand Recorder: record your hands for the open hand dataset (hands/rec/DESIGN.md).
+
+A Kirigami (QML) app with a Python backend. It runs in the dev container:
+  - Welcome: the consent text (CONSENT.md), shown the first time and again when its version
+    changes. Agreeing writes profile.json with a random contributor id.
+  - Before you start: the checklist (objects, controller straps, lighting, sleeves, privacy,
+    free space), the camera check (hands/camcheck.py: Start stays off while the upper cameras
+    are off, with a Restart SteamVR button; --ignore-cameras overrides it), a full session or a
+    quick round (suggested once a full one is done) and what will happen. Start hands it to
+    the session runner (session.py).
+  - Session: the runner's live status with the step's pose picture and where-to diagram, Next,
+    Pause/Resume, Redo, Skip section and Stop (Space: Next, P, R, S and Esc while the window has
+    focus; the button on the headset's right side is Next, pause and resume). The prompts appear
+    in the headset. Each step waits for Next unless "Advance by itself" was ticked.
+  - Review: sessions, their takes, and a viewer for one frame set at a time, where ranges,
+    takes and sessions can be deleted (takes.py).
+  - Export: compress what's kept into exports/<session>/ at nice 19 (takes.py), with a warning
+    when the headset is worn.
+  - Upload: the Hugging Face login status, and Upload: hub.py checks the export (validate.py)
+    and uploads it as a pull request, in a child process (Cancel ends it). UPLOAD.md explains
+    the steps, with the export filled in, and the command to copy for a terminal upload.
+Everything lives under ~/.local/share/frametop/hands/contrib (--base). Nothing is uploaded
+unless the person presses Upload; while CONSENT.md or UPLOAD.md is a draft, Upload stays off
+unless FT_HANDREC_ALLOW_UPLOAD=1 (the maintainer's rehearsal against a test repo, picked with
+FT_HANDREC_DATASET). --hub-dry-run does everything but the network calls.
+Launch with hands/rec/ft-handrec (host wrapper).
+"""
+import argparse
+import datetime
+import json
+import os
+import re
+import signal
+import subprocess
+import sys
+import threading
+import time
+import uuid
+
+from PySide6.QtCore import Property, QObject, Qt, QTimer, QUrl, Signal, Slot
+from PySide6.QtGui import QColor, QDesktopServices, QFont, QGuiApplication, QIcon, QImage, QPainter, QPalette
+from PySide6.QtQml import QQmlApplicationEngine
+from PySide6.QtQuick import QQuickImageProvider
+from PySide6.QtQuickControls2 import QQuickStyle
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+import hub  # noqa: E402
+import takes  # noqa: E402  (next to this file)
+
+# The dataset contributions go to (hub.py; FT_HANDREC_DATASET overrides it, for tests).
+HF_DATASET = hub.HF_DATASET
+CONSENT_PATH = hub.CONSENT_PATH
+UPLOAD_PATH = hub.UPLOAD_PATH
+HUB_PATH = os.path.join(HERE, "hub.py")
+VALIDATE_PATH = os.path.join(HERE, "validate.py")
+AWAKE_UNIT = "frametop-handrec-awake.service"
+SCRIPT_PATH = os.path.join(HERE, "script.json")
+# The headset counts as worn while vrcompositor runs and a display panel is lit: SteamVR turns
+# the panels off 5 s after the headset comes off (frame-job's check; the proximity sensor's
+# readings are too noisy). The dev container sees the host's processes and /sys.
+BACKLIGHTS = "/sys/class/backlight"
+ROUND_BYTES = 10 * 1000 ** 3  # about what one round of recording takes
+# The checklist's choices; the keys are what session.json stores.
+OBJECTS = [("pencil", "Pencil or pen"), ("phone", "Phone"), ("cup", "Cup or mug (empty)"),
+           ("keyboard", "Keyboard"), ("mouse", "Mouse"), ("gamepad", "Gamepad"),
+           ("small", "Something small (a coin, a key, a bottle cap)")]
+# "auto": the cameras' measurement (session.classify_lighting: indoor or daylight); the rest
+# correct it, since the cameras can't tell a dim room from a bright one.
+LIGHTING = [("auto", "Measured by the cameras"), ("dim", "Dim: one lamp only"), ("room", "Normal room light"),
+            ("daylight", "Daylight near a window")]
+LIGHTING_TEXT = dict(LIGHTING[1:], indoor="Indoor light")
+SLEEVES = [("short", "Short sleeves or bare arms"), ("long", "Long sleeves"), ("", "Rather not say")]
+HANDEDNESS = [("", "Rather not say"), ("right", "Right-handed"), ("left", "Left-handed"),
+              ("both", "Both (ambidextrous)")]
+ACTIVE_STATES = ("starting", "intro", "ready", "countdown", "running", "paused", "between", "nohands")
+# After Restart SteamVR: look at the cameras again this often, for at most this long.
+RECHECK_S = 3
+RECHECK_FOR_S = 120
+# Shown side by side in the viewer at this height; thumbnails are smaller.
+SET_HEIGHT = 480
+THUMB_HEIGHT = 96
+
+
+def read_text(path):
+    try:
+        with open(path, encoding="utf-8") as f:
+            return f.read()
+    except OSError:
+        return ""
+
+
+def consent_version():
+    """The "Version: ..." line of CONSENT.md: a new one asks everyone to agree again."""
+    m = re.search(r"^Version:\s*(\S+)", read_text(CONSENT_PATH), re.M)
+    return m.group(1) if m else "unknown"
+
+
+def process_running(name):
+    """Like pgrep -x NAME, from /proc."""
+    for pid in os.listdir("/proc"):
+        if pid.isdigit():
+            try:
+                with open(f"/proc/{pid}/comm") as f:
+                    if f.read().strip() == name:
+                        return True
+            except OSError:
+                pass
+    return False
+
+
+def headset_worn():
+    """True while vrcompositor runs and any panel's backlight is on; False if unreadable."""
+    lit = False
+    try:
+        for name in os.listdir(BACKLIGHTS):
+            try:
+                with open(os.path.join(BACKLIGHTS, name, "brightness")) as f:
+                    lit = lit or int(f.read().strip()) > 0
+            except (OSError, ValueError):
+                pass
+    except OSError:
+        return False
+    return lit and process_running("vrcompositor")
+
+
+def gigabytes(n):
+    return f"{n / 1000 ** 3:.1f} GB"
+
+
+def session_label(sid):
+    """20261002-101500 -> 2026-10-02 10:15; 20261002-101500-2 -> 2026-10-02 10:15 (2)."""
+    stamp, _, n = sid[:15], sid[15:16], sid[16:]
+    try:
+        label = datetime.datetime.strptime(stamp, "%Y%m%d-%H%M%S").strftime("%Y-%m-%d %H:%M")
+    except ValueError:
+        return sid
+    return f"{label} ({n})" if n else label
+
+
+def grey_image(cam):
+    """A camera's raw 8-bit pixels as a QImage that owns its data."""
+    img = QImage(cam["pixels"], cam["width"], cam["height"], cam["width"], QImage.Format_Grayscale8)
+    return img.copy()
+
+
+class FrameProvider(QQuickImageProvider):
+    """image://frames/set/SESSION/TAKE/INDEX: one frame set, every camera side by side.
+    image://frames/thumb/SESSION/TAKE: the take's first slam_left image, small.
+    Anything after "?" is ignored (it makes QML load the image again)."""
+
+    def __init__(self, store):
+        super().__init__(QQuickImageProvider.ImageType.Image)
+        self.store = store
+
+    def requestImage(self, ident, size, requested):
+        parts = ident.split("?", 1)[0].split("/")
+        try:
+            if parts[0] == "thumb" and len(parts) == 3:
+                return self._thumb(parts[1], parts[2])
+            if parts[0] == "set" and len(parts) == 4:
+                return self._set(parts[1], parts[2], int(parts[3]),
+                                 requested.height() if requested.height() > 0 else SET_HEIGHT)
+        except (OSError, ValueError, IndexError, KeyError) as e:
+            print(f"ft-handrec: image {ident}: {e}", file=sys.stderr)
+        img = QImage(4, 3, QImage.Format_Grayscale8)
+        img.fill(0)
+        return img
+
+    def _index(self, session, take):
+        return takes.take_index(self.store.take_dir(session, take))
+
+    def _thumb(self, session, take):
+        index = self._index(session, take)
+        if not len(index):
+            raise ValueError("no sets")
+        names = [c["name"] for c in index.cams]
+        cams = index.read_set(0, only="slam_left" if "slam_left" in names else names[0])
+        return grey_image(cams[0]).scaledToHeight(THUMB_HEIGHT, Qt.SmoothTransformation)
+
+    def _set(self, session, take, i, height):
+        cams = self._index(session, take).read_set(i)
+        scaled = [grey_image(c).scaledToHeight(height, Qt.SmoothTransformation) for c in cams]
+        gap = 8
+        out = QImage(sum(s.width() for s in scaled) + gap * (len(scaled) - 1), height, QImage.Format_RGB32)
+        out.fill(QColor(30, 30, 30))
+        p = QPainter(out)
+        font = QFont()
+        font.setPixelSize(max(12, height // 28))
+        p.setFont(font)
+        x = 0
+        for cam, img in zip(cams, scaled):
+            p.drawImage(x, 0, img)
+            p.setPen(QColor(255, 200, 80))
+            p.drawText(x + 6, 6 + font.pixelSize(), cam["name"])
+            x += img.width() + gap
+        p.end()
+        return out
+
+
+class Backend(QObject):
+    profileChanged = Signal()
+    diskChanged = Signal()
+    lightingChanged = Signal()
+    statusChanged = Signal()
+    sessionsChanged = Signal()
+    exportChanged = Signal()
+    message = Signal(str, bool)  # text, is error
+    # From other threads (the session runner, export, the lighting check): queued to this one.
+    _statusArrived = Signal(dict)
+    _lightingArrived = Signal(str, str)
+    _exportProgress = Signal(float, str)
+    _exportFinished = Signal(str, str)  # path, error ("" when it worked; "cancelled")
+    loginChanged = Signal()
+    uploadChanged = Signal()
+    _loginArrived = Signal(dict)
+    _loginLine = Signal(dict)
+    _uploadLine = Signal(dict)
+    _uploadFinished = Signal(dict)
+    cameraChanged = Signal()
+    _cameraArrived = Signal(dict)
+
+    def __init__(self, store, session_options=None, hub_dry_run=False, ignore_cameras=False):
+        super().__init__()
+        self.store = store
+        self._session_options = session_options or {}  # Session options: dry_run, speed, poses_dir (tests), button
+        self._hub_dry_run = hub_dry_run
+        self._login = {"state": "dry" if hub_dry_run else "unknown"}
+        self._login_busy = False
+        self._login_proc = None      # hub.py login: waiting for the browser
+        self._login_cancelled = False
+        self._upload_proc = None
+        self._upload_thread = None
+        self._upload_cancelled = False
+        self._upload = {}
+        os.makedirs(store.base, mode=0o700, exist_ok=True)
+        self._session_mod = None
+        self._session_error = ""
+        self._session = None
+        self._session_id = ""
+        self._status = {}
+        self._lighting_note = ""
+        self._lighting_measured = ""
+        self._lighting_busy = False
+        self._camd_started = False   # ft-camd started for the light check: stopped on quit
+        self._awake = set()          # what keeps the Frame awake now: "export", "upload"
+        self._awake_lock = threading.Lock()
+        self._export_cancel = None
+        self._export_thread = None
+        self._export_fraction = 0.0
+        self._export_text = ""
+        self._export_session = ""
+        self._statusArrived.connect(self._on_status)
+        self._ignore_cameras = ignore_cameras
+        self._camera = {}            # the last camera check (session.camera_check)
+        self._camera_busy = False
+        self._restarting = False
+        self._cameraArrived.connect(self._on_camera)
+        self._lightingArrived.connect(self._on_lighting)
+        self._exportProgress.connect(self._on_export_progress)
+        self._exportFinished.connect(self._on_export_finished)
+        self._loginArrived.connect(self._on_login)
+        self._loginLine.connect(self._on_login_line)
+        self._uploadLine.connect(self._on_upload_line)
+        self._uploadFinished.connect(self._on_upload_finished)
+        self.disk_timer = QTimer(interval=30000, timeout=self.diskChanged.emit)
+        self.disk_timer.start()
+
+    def _thread(self, fn):
+        thread = threading.Thread(target=fn, daemon=True)
+        thread.start()
+        return thread
+
+    # --- the session runner, imported when first needed (it's written separately)
+    def _runner(self):
+        if self._session_mod is None and not self._session_error:
+            try:
+                import session as mod
+                self._session_mod = mod
+            except Exception as e:  # missing, or broken: say so, the rest of the app still works
+                self._session_error = f"The session runner (hands/rec/session.py) can't be loaded: {e}"
+        return self._session_mod
+
+    @Property(str, notify=statusChanged)
+    def runnerError(self):
+        self._runner()
+        return self._session_error
+
+    # --- consent and profile
+    @Property(str, constant=True)
+    def consentText(self):
+        return read_text(CONSENT_PATH) or "CONSENT.md is missing."
+
+    @Property(str, constant=True)
+    def consentVersion(self):
+        return consent_version()
+
+    @Property(bool, constant=True)
+    def textsDraft(self):
+        return hub.texts_draft()
+
+    @Property(bool, notify=profileChanged)
+    def needsConsent(self):
+        profile = self.store.profile()
+        consent = profile.get("consent") or {}
+        return not (profile.get("contributor") and consent.get("adult") is True
+                    and consent.get("version") == consent_version())
+
+    @Property(str, notify=profileChanged)
+    def contributor(self):
+        return self.store.profile().get("contributor", "")
+
+    @Property(str, notify=profileChanged)
+    def consentAccepted(self):
+        return (self.store.profile().get("consent") or {}).get("accepted", "")
+
+    @Property(str, notify=profileChanged)
+    def handedness(self):
+        return (self.store.profile().get("optional") or {}).get("handedness", "")
+
+    @Property("QVariantList", constant=True)
+    def handednessChoices(self):
+        return [{"value": k, "text": v} for k, v in HANDEDNESS]
+
+    @Slot(bool, bool, bool, str)
+    def acceptConsent(self, adult, region, agree, handedness):
+        """Write profile.json. A contributor id, once made, stays (a new consent version keeps it).
+        region: not living in Illinois, Texas or Washington (CONSENT.md "Who can take part")."""
+        if not (adult and region and agree):
+            self.message.emit("All three boxes need ticking to take part", True)
+            return
+        profile = self.store.profile()
+        optional = profile.get("optional") if isinstance(profile.get("optional"), dict) else {}
+        optional["handedness"] = handedness if handedness in dict(HANDEDNESS) else ""
+        optional.setdefault("notes", "")
+        profile = {"schema": 1, "contributor": profile.get("contributor") or str(uuid.uuid4()),
+                   "consent": {"version": consent_version(),
+                               "accepted": datetime.datetime.now().astimezone().isoformat(timespec="seconds"),
+                               "adult": True, "region_ok": True},
+                   "optional": optional}
+        takes.write_json(self.store.profile_path, profile)
+        self.profileChanged.emit()
+        self.message.emit("Thank you. Your contributor id: " + profile["contributor"], False)
+
+    # --- the checklist
+    @Property("QVariantList", constant=True)
+    def objects(self):
+        return [{"value": k, "text": v} for k, v in OBJECTS]
+
+    @Property("QVariantList", constant=True)
+    def lightingChoices(self):
+        return [{"value": k, "text": v} for k, v in LIGHTING]
+
+    @Property("QVariantList", constant=True)
+    def sleeveChoices(self):
+        return [{"value": k, "text": v} for k, v in SLEEVES]
+
+    @Property(str, notify=diskChanged)
+    def freeText(self):
+        return gigabytes(takes.free_bytes(self.store.base))
+
+    @Property(bool, notify=diskChanged)
+    def diskOk(self):
+        return takes.free_bytes(self.store.base) >= ROUND_BYTES
+
+    @Property(str, notify=lightingChanged)
+    def lightingNote(self):
+        """A warning: this light is like an earlier round's, or it couldn't be measured."""
+        return self._lighting_note
+
+    @Property(str, notify=lightingChanged)
+    def lightingMeasured(self):
+        """What the cameras see: "Indoor light" or "Daylight…", "Measuring…", or ""."""
+        return "Measuring…" if self._lighting_busy else self._lighting_measured
+
+    @Slot(str)
+    def checkLighting(self, chosen):
+        """Measure the light (starting ft-camd if nothing runs it) and compare it with earlier
+        rounds (session.similar_lighting): a round in light like an earlier one adds less."""
+        mod = self._runner()
+        if not mod or self._lighting_busy:
+            return
+        base = self.store.base
+        self._lighting_busy = True
+        self.lightingChanged.emit()
+
+        def run():
+            measured = ""
+            try:
+                ring = mod.ring_lighting()
+                if ring is None and not self.sessionActive:
+                    if mod.start_camd():
+                        self._camd_started = True
+                    time.sleep(1.0)    # the first near-black frames
+                    ring = mod.ring_lighting()
+                if ring is None:
+                    note = ("The cameras aren't running, so the light can't be measured now. The session "
+                            "measures it when it starts.")
+                else:
+                    kind = mod.classify_lighting(ring)
+                    ir = mod.ambient_ir(ring)
+                    measured = (f"{LIGHTING_TEXT.get(kind, kind)} (infrared {ir:.1f})" if kind
+                                else "The cameras couldn't measure the light yet.")
+                    match = mod.similar_lighting(base, {"chosen": chosen, "ring": ring})
+                    note = "" if not match else (
+                        f"The cameras see about the same light as in your round of {session_label(match[0])} "
+                        f"({LIGHTING_TEXT.get(match[1], match[1] or 'not given')}). A different light helps the "
+                        "dataset more: change the lighting if you can, or go ahead anyway.")
+            except Exception as e:
+                note = f"Couldn't measure the light: {e}"
+            self._lightingArrived.emit(note, measured)
+        self._thread(run)
+
+    def _on_lighting(self, note, measured):
+        self._lighting_busy = False
+        self._lighting_note = note
+        self._lighting_measured = measured
+        self.lightingChanged.emit()
+
+    # --- the camera check (hands/camcheck.py through session.camera_check)
+    @Property(str, notify=cameraChanged)
+    def cameraState(self):
+        """ok, degraded, unknown; checking while it runs; "" before the first check."""
+        if self._camera_busy and not self._camera:
+            return "checking"
+        return self._camera.get("status", "")
+
+    @Property(str, notify=cameraChanged)
+    def cameraText(self):
+        """What to tell the person when the cameras aren't all running ("" otherwise)."""
+        mod = self._runner()
+        return mod.camera_text(self._camera) if mod and self._camera else ""
+
+    @Property(str, notify=cameraChanged)
+    def cameraSummary(self):
+        return self._camera.get("summary", "")
+
+    @Property(str, notify=cameraChanged)
+    def cameraEvidence(self):
+        return "\n".join(self._camera.get("evidence", []))
+
+    @Property(bool, constant=True)
+    def camerasIgnored(self):
+        return self._ignore_cameras
+
+    @Property(bool, notify=cameraChanged)
+    def cameraBusy(self):
+        return self._camera_busy
+
+    @Property(bool, notify=cameraChanged)
+    def restartingSteamVR(self):
+        return self._restarting
+
+    @Property(bool, notify=cameraChanged)
+    def camerasBlockStart(self):
+        """Start stays off: the check found the cameras degraded (unless --ignore-cameras)."""
+        return not self._ignore_cameras and self._camera.get("status") == "degraded"
+
+    def _check_now(self):
+        mod = self._runner()
+        if not mod or self._session_options.get("dry_run"):
+            return {"status": "unknown", "summary": "not checked (dry run)", "reason": "dry run", "evidence": []}
+        return mod.camera_check()
+
+    @Slot()
+    def checkCameras(self):
+        """Run the camera check off this thread (it reads the XRService log: a few MB)."""
+        if self._camera_busy:
+            return
+        self._camera_busy = True
+        self.cameraChanged.emit()
+        self._thread(lambda: self._cameraArrived.emit(self._check_now()))
+
+    def _on_camera(self, result):
+        self._camera = result
+        self._camera_busy = self._restarting
+        self.cameraChanged.emit()
+
+    @Slot()
+    def restartSteamVR(self):
+        """systemctl --user restart steamvr.service on the host (--no-block: the job runs in
+        systemd, so it finishes even when this window closes with the Frametop desktop), then
+        the camera check every few seconds until the new XRService has opened its cameras."""
+        mod = self._runner()
+        if not mod or self._restarting or self.sessionActive:
+            return
+        self._restarting = self._camera_busy = True
+        self.cameraChanged.emit()
+        before = self._camera.get("log", "") if self._camera else ""   # each XRService start writes a new log
+
+        def run():
+            result = None
+            try:
+                r = subprocess.run(mod.host_command("systemctl", "--user", "restart", "--no-block",
+                                                    "steamvr.service"), capture_output=True, text=True, timeout=60)
+                if r.returncode != 0:
+                    raise RuntimeError((r.stderr or r.stdout).strip() or "exit %d" % r.returncode)
+                end = time.monotonic() + RECHECK_FOR_S
+                time.sleep(RECHECK_S * 2)
+                while time.monotonic() < end:
+                    result = self._check_now()
+                    # Done once a new XRService (a new log) has opened its cameras, ok or not.
+                    if result.get("status") in ("ok", "degraded") and result.get("log") != before:
+                        break
+                    time.sleep(RECHECK_S)
+            except Exception as e:
+                result = {"status": "unknown", "summary": f"unknown: couldn't restart SteamVR ({e})",
+                          "reason": str(e), "evidence": []}
+            self._restarting = False
+            self._cameraArrived.emit(result or self._check_now())
+        self._thread(run)
+
+    # --- the session
+    @Property("QVariantMap", notify=statusChanged)
+    def status(self):
+        return self._status
+
+    @Property(bool, notify=statusChanged)
+    def sessionActive(self):
+        return self._session is not None and self._status.get("state", "starting") in ACTIVE_STATES
+
+    @Property(str, notify=statusChanged)
+    def sessionId(self):
+        return self._session_id
+
+    @Slot("QVariantMap", bool, bool, result=str)
+    def planText(self, checklist, auto, quick):
+        """How long a session with these answers takes (session.plan_summary), or a quick round."""
+        mod = self._runner()
+        if not mod:
+            return ""
+        try:
+            script = mod.load_script(SCRIPT_PATH)
+            plan, _ = mod.build_plan(script, dict(checklist), quick=quick)
+            return mod.plan_summary(script, plan, auto=auto)
+        except Exception as e:
+            return f"Couldn't read the script: {e}"
+
+    @Property(bool, notify=sessionsChanged)
+    def hasFullSession(self):
+        """A full session (not a quick round, not a dry run) went to the end: the window then
+        suggests a quick round, in another light."""
+        for s in self.store.sessions():
+            meta = takes.read_json(os.path.join(self.store.session_dir(s["id"]), "session.json"))
+            if meta.get("status") == "done" and not meta.get("quick") and not meta.get("dry_run"):
+                return True
+        return False
+
+    @Slot("QVariantMap", str, bool, bool, result=bool)
+    def startSession(self, checklist, lighting, auto, quick):
+        if self.sessionActive:
+            return False
+        mod = self._runner()
+        if not mod:
+            self.message.emit(self._session_error, True)
+            return False
+        if self.needsConsent:
+            self.message.emit("Agree to the consent text first (Welcome page)", True)
+            return False
+        if not self._ignore_cameras and not self._session_options.get("dry_run"):
+            self._camera = self._check_now()   # fresh: it takes a fraction of a second
+            self.cameraChanged.emit()
+            if self._camera.get("status") == "degraded":
+                self.message.emit(mod.camera_text(self._camera), True)
+                return False
+        checklist = dict(checklist)
+        checklist["objects"] = [o for o in checklist.get("objects", []) if o in dict(OBJECTS)]
+        checklist["own_objects"] = [o.strip() for o in checklist.get("own_objects", []) if str(o).strip()]
+        try:
+            self._session = mod.Session(self.store.base, self.store.profile(), checklist, lighting, SCRIPT_PATH,
+                                        on_status=lambda s: self._statusArrived.emit(dict(s)), auto=auto,
+                                        quick=quick, **self._session_options)
+        except Exception as e:
+            self.message.emit(f"Couldn't set up the session: {e}", True)
+            return False
+        self._session_id = ""
+        self._status = {"state": "starting"}
+        self.statusChanged.emit()
+        session = self._session
+
+        def run():
+            try:
+                session.start()
+            except Exception as e:
+                self._statusArrived.emit({"state": "error", "error": str(e)})
+        self._thread(run)
+        return True
+
+    def _on_status(self, status):
+        self._status = status
+        if status.get("camera") and status.get("camera") is not self._camera:
+            self._camera = status["camera"]   # the session's own check (at its start, or after no hands)
+            self.cameraChanged.emit()
+        if self._session is not None and not self._session_id:
+            self._session_id = os.path.basename(str(getattr(self._session, "session_dir", "") or ""))
+        self.statusChanged.emit()
+        if status.get("state") in ("done", "stopped", "error"):
+            self.sessionsChanged.emit()
+
+    def _control(self, name):
+        if self._session is None:
+            return
+        try:
+            getattr(self._session, name)()
+        except Exception as e:
+            self.message.emit(f"{name}: {e}", True)
+
+    @Slot()
+    def nextStep(self):
+        if self.sessionActive and self._status.get("waiting"):
+            self._control("next_step")
+
+    @Slot()
+    def redo(self):
+        if self.sessionActive and self._status.get("can_redo"):
+            self._control("redo")
+
+    @Slot()
+    def togglePause(self):
+        if self._status.get("state") == "paused":
+            self._control("resume")
+        elif self.sessionActive:
+            self._control("pause")
+
+    @Slot()
+    def skipSection(self):
+        if self.sessionActive:
+            self._control("skip")
+
+    @Slot()
+    def stopSession(self):
+        """Stop: the take in progress is kept, as far as it got. It can block while the
+        recording is written out, so it runs off this thread."""
+        if self.sessionActive:
+            session = self._session
+            self._thread(lambda: session.stop())
+
+    def shutdown(self):
+        """The window closes: end a running session (blocking, so its files are complete)."""
+        if self.sessionActive:
+            try:
+                self._session.stop()
+            except Exception:
+                pass
+        if self._export_cancel:
+            self._export_cancel.set()  # and wait, so export can remove its half-written copy
+            self._export_thread.join(15)
+        self.cancelLogin()
+        if self._upload_proc:
+            self.cancelUpload()
+            self._upload_thread.join(10)
+        if self._awake and self._session_mod:
+            try:
+                self._session_mod.stop_unit(AWAKE_UNIT)
+            except Exception:
+                pass
+        if self._camd_started and self._session_mod:
+            try:
+                self._session_mod.stop_unit(self._session_mod.CAMD_UNIT)
+            except Exception:
+                pass
+
+    # --- review
+    @Property("QVariantList", notify=sessionsChanged)
+    def sessions(self):
+        out = []
+        for s in self.store.sessions():
+            s["label"] = session_label(s["id"])
+            s["sizeText"] = takes.human_bytes(s["bytes"])
+            s["exportText"] = takes.human_bytes(s["export_bytes"]) if s["exported"] else ""
+            s["lightingText"] = LIGHTING_TEXT.get(s["lighting"], "")
+            s["active"] = self.sessionActive and s["id"] == self._session_id
+            s["statusText"] = {"recording": "" if s["active"] else "interrupted", "error": "ended with an error",
+                               "stopped": "stopped early"}.get(s["status"], "")
+            out.append(s)
+        return out
+
+    @Slot()
+    def refreshSessions(self):
+        self.sessionsChanged.emit()
+        self.diskChanged.emit()
+
+    @Slot(str, result="QVariantList")
+    def takeList(self, session):
+        try:
+            rows = self.store.takes(session)
+        except ValueError:
+            return []
+        for t in rows:
+            t["durationText"] = f"{int(t['duration_s'] // 60)}:{int(t['duration_s'] % 60):02d}"
+            t["sizeText"] = takes.human_bytes(t["bytes"])
+            t.pop("ranges")
+        return rows
+
+    @Slot(str, str, result="QVariantMap")
+    def takeInfo(self, session, take):
+        """For the viewer: {count, title, cams, ranges: [[first, last] set indexes]}."""
+        try:
+            index = takes.take_index(self.store.take_dir(session, take))
+            ranges = self.store.ranges(session, take)
+        except ValueError:
+            return {"count": 0, "title": take, "cams": [], "ranges": []}
+        marks = []
+        for a, b in ranges:
+            inside = [i for i in range(len(index)) if a <= index.time_ns(i) <= b]
+            marks.append([inside[0], inside[-1]] if inside else [-1, -1])
+        return {"count": len(index), "title": self.store.take_meta(session, take).get("title") or take,
+                "cams": [c["name"] for c in index.cams], "ranges": marks}
+
+    @Slot(str, str, int, result=str)
+    def setTime(self, session, take, i):
+        """Set i's time from the take's first set, m:ss.s."""
+        try:
+            index = takes.take_index(self.store.take_dir(session, take))
+            t = (index.time_ns(i) - index.time_ns(0)) / 1e9
+        except (ValueError, IndexError):
+            return ""
+        return f"{int(t // 60)}:{t % 60:04.1f}"
+
+    def _active_guard(self, session):
+        if self.sessionActive and session == self._session_id:
+            self.message.emit("This session is still recording: stop it first", True)
+            return True
+        return False
+
+    @Slot(str, str, int, int)
+    def deleteRange(self, session, take, first, last):
+        """Leave sets first..last (indexes, either order) out of the export."""
+        if self._active_guard(session):
+            return
+        index = takes.take_index(self.store.take_dir(session, take))
+        first, last = sorted((max(0, first), min(len(index) - 1, last)))
+        if first > last:
+            return
+        self.store.delete_range(session, take, index.time_ns(first), index.time_ns(last))
+        self.message.emit(f"Sets {first + 1} to {last + 1} won't be exported", False)
+        self.sessionsChanged.emit()
+
+    @Slot(str, str, int)
+    def restoreRange(self, session, take, k):
+        self.store.restore_range(session, take, k)
+        self.message.emit("Range restored", False)
+        self.sessionsChanged.emit()
+
+    @Slot(str, str)
+    def deleteTake(self, session, take):
+        if self._active_guard(session):
+            return
+        try:
+            self.store.delete_take(session, take)
+            self.message.emit(f"Deleted {take}", False)
+        except (OSError, ValueError) as e:
+            self.message.emit(f"Couldn't delete {take}: {e}", True)
+        self.refreshSessions()
+
+    @Slot(str)
+    def deleteSession(self, session):
+        if self._active_guard(session):
+            return
+        try:
+            self.store.delete_session(session)
+            self.message.emit(f"Deleted the session of {session_label(session)}", False)
+        except (OSError, ValueError) as e:
+            self.message.emit(f"Couldn't delete the session: {e}", True)
+        self.refreshSessions()
+
+    # --- export
+    @Slot(result=bool)
+    def headsetWorn(self):
+        return headset_worn()
+
+    @Property(bool, constant=True)
+    def zstdFound(self):
+        return takes.find_zstd() is not None
+
+    @Property(bool, notify=exportChanged)
+    def exporting(self):
+        return self._export_cancel is not None
+
+    @Property(float, notify=exportChanged)
+    def exportFraction(self):
+        return self._export_fraction
+
+    @Property(str, notify=exportChanged)
+    def exportText(self):
+        return self._export_text
+
+    @Property(str, notify=exportChanged)
+    def exportSessionId(self):
+        return self._export_session
+
+    def _stay_awake(self, why, on):
+        """Hold off sleep while an export or upload runs, so the headset can be taken off and
+        left plugged in: a host unit running systemd-inhibit, started with the first reason
+        and stopped with the last."""
+        mod = self._runner()
+        if not mod or self._hub_dry_run:
+            return
+
+        def run():
+            with self._awake_lock:
+                had = bool(self._awake)
+                (self._awake.add if on else self._awake.discard)(why)
+                try:
+                    if self._awake and not had:
+                        mod.start_unit(AWAKE_UNIT, "keeps the Frame awake while exporting or uploading",
+                                       ["systemd-inhibit", "--what=sleep:idle", "--mode=block",
+                                        "--who=Frametop Hand Recorder", "--why=Exporting or uploading hand recordings",
+                                        "sleep", "infinity"])
+                    elif had and not self._awake:
+                        mod.stop_unit(AWAKE_UNIT)
+                except Exception as e:
+                    print(f"keeping the Frame awake: {e}", file=sys.stderr, flush=True)
+        self._thread(run)
+
+    @Slot(str, bool)
+    def exportSession(self, session, keep_notes):
+        if self.exporting or self._active_guard(session):
+            return
+        cancel = threading.Event()
+        self._export_cancel = cancel
+        self._export_session = session
+        self._export_fraction = 0.0
+        self._export_text = "Starting"
+        self.exportChanged.emit()
+        self._stay_awake("export", True)
+
+        def run():
+            try:
+                path = self.store.export(session, progress=lambda f, text: self._exportProgress.emit(f, text),
+                                         cancel=cancel, keep_notes=keep_notes)
+                self._exportFinished.emit(path, "")
+            except takes.Cancelled:
+                self._exportFinished.emit("", "cancelled")
+            except Exception as e:
+                self._exportFinished.emit("", str(e) or type(e).__name__)
+        self._export_thread = self._thread(run)
+
+    @Slot()
+    def cancelExport(self):
+        if self._export_cancel:
+            self._export_cancel.set()
+            self._export_text = "Cancelling"
+            self.exportChanged.emit()
+
+    def _on_export_progress(self, fraction, text):
+        if self._export_cancel and not self._export_cancel.is_set():
+            self._export_fraction, self._export_text = fraction, text
+            self.exportChanged.emit()
+
+    def _on_export_finished(self, path, error):
+        self._export_cancel = None
+        self._stay_awake("export", False)
+        if error == "cancelled":
+            self._export_text = "Cancelled: nothing was kept"
+        elif error:
+            self._export_text = "Failed: " + error
+            self.message.emit("Export failed: " + error, True)
+        else:
+            self._export_fraction = 1.0
+            self._export_text = f"Exported to {path} ({takes.human_bytes(takes.tree_bytes(path))})"
+            self.message.emit("Export ready", False)
+        self.exportChanged.emit()
+        self.refreshSessions()
+
+    @Slot(str)
+    def deleteExport(self, session):
+        try:
+            self.store.delete_export(session)
+            self.message.emit("Export deleted; the session stays", False)
+        except (OSError, ValueError) as e:
+            self.message.emit(f"Couldn't delete the export: {e}", True)
+        self.refreshSessions()
+
+    @Property(str, constant=True)
+    def exportsDir(self):
+        return self.store.exports_dir
+
+    # --- upload
+    @Property(str, constant=True)
+    def dataset(self):
+        try:
+            return hub.dataset_id()
+        except hub.HubError:
+            return os.environ.get(hub.DATASET_ENV, HF_DATASET)
+
+    @Property(str, constant=True)
+    def datasetUrl(self):
+        return hub.dataset_url(self.dataset)
+
+    @Property(bool, constant=True)
+    def hubDryRun(self):
+        return self._hub_dry_run
+
+    @Property(bool, constant=True)
+    def uploadAllowed(self):
+        """Real uploads may start: the texts aren't drafts, or FT_HANDREC_ALLOW_UPLOAD=1."""
+        return hub.upload_allowed()
+
+    @Property(bool, constant=True)
+    def allowUploadSet(self):
+        return os.environ.get(hub.ALLOW_ENV) == "1"
+
+    def _hub_argv(self, *args):
+        return [sys.executable, HUB_PATH, "--base", self.store.base, *args]
+
+    # The login: hub.py whoami in a child process (it asks huggingface.co)
+    @Property("QVariantMap", notify=loginChanged)
+    def login(self):
+        """{"state": unknown|checking|ok|none|read|error|missing|dry|starting|waiting, "name", "role",
+        "text", "link"}; while waiting, "url" and "code" (the browser login's)."""
+        return self._login
+
+    @Slot()
+    def checkLogin(self):
+        if self._hub_dry_run or self._login_busy:
+            return
+        self._login_busy = True
+        self._login = {"state": "checking", "text": "Checking your Hugging Face login"}
+        self.loginChanged.emit()
+        argv = self._hub_argv("whoami", "--json")
+
+        def run():
+            try:
+                r = subprocess.run(argv, capture_output=True, text=True, timeout=60)
+                result = self._last_json(r.stdout) or {"error": {"kind": "hub", "text": (r.stderr.strip().splitlines()
+                                                                                          or ["hub.py failed"])[-1]}}
+            except (OSError, subprocess.TimeoutExpired) as e:
+                result = {"error": {"kind": "network", "text": f"The login check didn't finish: {e}"}}
+            self._loginArrived.emit(result)
+        self._thread(run)
+
+    @staticmethod
+    def _last_json(text):
+        for line in reversed(text.strip().splitlines()):
+            try:
+                obj = json.loads(line)
+            except ValueError:
+                continue
+            if isinstance(obj, dict):
+                return obj
+        return None
+
+    def _on_login(self, result):
+        self._login_busy = False
+        self._login_proc = None
+        if result.get("cancelled"):
+            self._login = {"state": "unknown"}
+            self.checkLogin()   # whatever was saved before is still there
+            return
+        if "done" in result:
+            who = result["done"]
+            role = who.get("role", "")
+            if role == "read":
+                self._login = {"state": "read", "name": who.get("name", ""), "role": role, "link": hub.TOKENS_URL,
+                               "text": f"Logged in as {who.get('name', '')}, but with a read-only token, which "
+                                       "can't upload. Log in again."}
+            else:
+                self._login = {"state": "ok", "name": who.get("name", ""), "role": role,
+                               "text": f"Logged in as {who.get('name', '')}"}
+        else:
+            e = result.get("error") or {}
+            state = {"login": "none", "missing": "missing"}.get(e.get("kind"), "error")
+            self._login = {"state": state, "text": e.get("text", "The login check failed"), "link": e.get("link", "")}
+        self.loginChanged.emit()
+
+    # The browser login: hub.py login --json in a child process. It gets a link and a short code;
+    # the link opens in the browser, the person types the code there (Hugging Face doesn't fill it
+    # in, 2026-10-03) and approves, and hub.py saves the token. The token never reaches this process.
+    @Slot()
+    def logIn(self):
+        if self._hub_dry_run or self._login_proc or self._login_busy:
+            return
+        try:
+            proc = subprocess.Popen(self._hub_argv("login", "--json"), stdin=subprocess.DEVNULL,
+                                    stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, bufsize=1)
+        except OSError as e:
+            self._on_login({"error": {"kind": "hub", "text": f"Couldn't start the login: {e}"}})
+            return
+        self._login_proc = proc
+        self._login_cancelled = False
+        self._login_busy = True
+        self._login = {"state": "starting", "text": "Getting a login link from Hugging Face"}
+        self.loginChanged.emit()
+
+        def run():
+            last = {}
+            for line in proc.stdout:
+                try:
+                    obj = json.loads(line)
+                except ValueError:
+                    continue
+                if isinstance(obj, dict):
+                    if "done" in obj or "error" in obj:
+                        last = obj
+                    else:
+                        self._loginLine.emit(obj)
+            err = proc.stderr.read()
+            proc.wait()
+            proc.stdout.close()
+            proc.stderr.close()
+            if self._login_cancelled:
+                last = {"cancelled": True}
+            elif not last:
+                tail = (err.strip().splitlines() or [f"exit status {proc.returncode}"])[-1]
+                last = {"error": {"kind": "hub", "text": f"The login stopped: {tail}"}}
+            self._loginArrived.emit(last)
+        self._thread(run)
+
+    @Slot()
+    def cancelLogin(self):
+        if self._login_proc and self._login_proc.poll() is None:
+            self._login_cancelled = True
+            self._login_proc.terminate()
+
+    def _on_login_line(self, obj):
+        if obj.get("phase") == "code" and obj.get("url"):
+            self._login = {"state": "waiting", "url": obj["url"], "code": obj.get("code", ""),
+                           "expires_in": obj.get("expires_in", 0), "text": obj.get("text", "")}
+            self.loginChanged.emit()
+            QDesktopServices.openUrl(QUrl(obj["url"]))
+
+    # The upload: hub.py upload --json in a child process; its lines say how it goes
+    @Property(bool, notify=uploadChanged)
+    def uploading(self):
+        return self._upload_proc is not None
+
+    @Property("QVariantMap", notify=uploadChanged)
+    def upload(self):
+        """{"session", "phase", "text", "fraction" (-1: unknown), "log", "result": {...}, "error": {...}}."""
+        return self._upload
+
+    @Slot(str, result="QVariantMap")
+    def uploadInfo(self, session):
+        """{"previous": the last upload of this same export or {}, "uploads": how many in all}."""
+        try:
+            export = self.store.export_dir(session)
+            before = hub.previous_upload(self.store, session, hub.export_sha(export))
+            count = len(hub.uploads(self.store, session))
+        except (OSError, ValueError):
+            return {"previous": {}, "uploads": 0}
+        return {"previous": before or {}, "uploads": count}
+
+    @Slot(str, bool)
+    def startUpload(self, session, again):
+        if self.uploading or self.exporting or self._active_guard(session):
+            return
+        if not self._hub_dry_run and not hub.upload_allowed():
+            self.message.emit("Contributions aren't open yet", True)
+            return
+        argv = self._hub_argv("upload", session, "--json")
+        if self._hub_dry_run:
+            argv.append("--dry-run")
+        if again:
+            argv.append("--again")
+        try:
+            proc = subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                                    text=True, bufsize=1)
+        except OSError as e:
+            self.message.emit(f"Couldn't start the upload: {e}", True)
+            return
+        self._upload_proc = proc
+        self._upload_cancelled = False
+        self._upload = {"session": session, "phase": "check", "text": "Starting", "fraction": 0.0, "log": "",
+                        "result": {}, "error": {}, "pr_url": ""}
+        self.uploadChanged.emit()
+        self._stay_awake("upload", True)
+
+        def run():
+            last = {}
+            for line in proc.stdout:
+                try:
+                    obj = json.loads(line)
+                except ValueError:
+                    continue
+                if isinstance(obj, dict):
+                    if "done" in obj or "error" in obj:
+                        last = obj
+                    else:
+                        self._uploadLine.emit(obj)
+            err = proc.stderr.read()
+            proc.wait()
+            proc.stdout.close()
+            proc.stderr.close()
+            if not last:
+                tail = (err.strip().splitlines() or [f"exit status {proc.returncode}"])[-1]
+                last = {"error": {"kind": "cancelled" if self._upload_cancelled else "hub",
+                                  "text": "Cancelled" if self._upload_cancelled else f"The upload stopped: {tail}"}}
+            self._uploadFinished.emit(last)
+        self._upload_thread = self._thread(run)
+
+    @Slot()
+    def cancelUpload(self):
+        if self._upload_proc and self._upload_proc.poll() is None:
+            self._upload_cancelled = True
+            self._upload_proc.terminate()
+            self._upload = dict(self._upload, text="Cancelling")
+            self.uploadChanged.emit()
+
+    def _on_upload_line(self, obj):
+        up = dict(self._upload)
+        if "log" in obj:
+            up["log"] = (up.get("log", "") + obj["log"] + "\n")[-20000:]
+        if "phase" in obj:
+            f = obj.get("fraction")
+            up.update(phase=obj["phase"], text=obj.get("text", ""), fraction=-1.0 if f is None else float(f))
+        if obj.get("pr_url"):
+            up["pr_url"] = obj["pr_url"]   # the pull request is open: the files are on their way
+        self._upload = up
+        self.uploadChanged.emit()
+
+    def _on_upload_finished(self, last):
+        self._upload_proc = None
+        self._stay_awake("upload", False)
+        up = dict(self._upload)
+        if "done" in last:
+            result = last["done"]
+            up.update(result=result, error={}, phase="done", fraction=1.0,
+                      text="Dry run: nothing was uploaded" if result.get("dry_run") else "Uploaded")
+            if not result.get("dry_run"):
+                self.message.emit("Uploaded: the pull request is open", False)
+        else:
+            e = last.get("error") or {}
+            cancelled = e.get("kind") == "cancelled"
+            up.update(error=e, result={}, phase="failed", fraction=0.0,
+                      text=("Cancelled. Its pull request stays open: press Upload again to finish it there."
+                            if up.get("pr_url") else "Cancelled") if cancelled else e.get("text", ""))
+            if not cancelled:
+                self.message.emit("Upload failed", True)
+        self._upload = up
+        self.uploadChanged.emit()
+        self.sessionsChanged.emit()
+
+    @Slot(str, result=str)
+    def uploadText(self, session):
+        """UPLOAD.md with this export's path and size filled in."""
+        try:
+            path = self.store.export_dir(session)
+        except ValueError:
+            return ""
+        values = {"EXPORT_PATH": path, "EXPORT_SIZE": takes.human_bytes(takes.tree_bytes(path)),
+                  "CONTRIBUTOR": self.contributor or "CONTRIBUTOR", "SESSION": session, "DATASET": self.dataset}
+        text = read_text(UPLOAD_PATH) or "UPLOAD.md is missing."
+        if hub.is_draft(UPLOAD_PATH):
+            text = text.split("\n", 1)[-1]   # the page's banner says it already
+        return re.sub(r"@([A-Z_]+)@", lambda m: values.get(m.group(1), m.group(0)), text)
+
+    @Slot(QColor)
+    def setLinkColor(self, color):
+        palette = QGuiApplication.palette()
+        palette.setColor(QPalette.Link, color)
+        QGuiApplication.setPalette(palette)
+
+    @Slot(str)
+    def copy(self, text):
+        QGuiApplication.clipboard().setText(text)
+        self.message.emit("Copied", False)
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Frametop Hand Recorder")
+    ap.add_argument("--base", default=takes.DEFAULT_BASE, help="where profile.json, sessions/ and exports/ go")
+    ap.add_argument("--page", default="", help="open on this page: welcome, checklist, session, review, export, upload")
+    ap.add_argument("--dry-run", action="store_true",
+                    help="test: sessions start no processes and print the panel's commands")
+    ap.add_argument("--speed", type=float, default=1.0, help="test, with --dry-run: run sessions this much faster")
+    ap.add_argument("--poses", help="test: the pose pictures' folder (default hands/rec/poses)")
+    ap.add_argument("--no-headset-button", action="store_true",
+                    help="sessions don't read the headset's button (Next, pause, resume)")
+    ap.add_argument("--hub-dry-run", action="store_true",
+                    help="test: Upload checks the export and says what it would send, with no network calls")
+    ap.add_argument("--ignore-cameras", action="store_true",
+                    help="start sessions even if the camera check (hands/camcheck.py) finds the upper cameras off")
+    a, qt_args = ap.parse_known_args()
+    app = QGuiApplication([sys.argv[0]] + qt_args)
+    app.setApplicationName("ft-handrec")
+    app.setApplicationDisplayName("Frametop Hand Recorder")
+    app.setDesktopFileName("ft-handrec")
+    if not QIcon.themeName():
+        QIcon.setThemeName("breeze")
+    QQuickStyle.setStyle("org.kde.desktop")
+    store = takes.Store(a.base)
+    engine = QQmlApplicationEngine()
+    engine.addImageProvider("frames", FrameProvider(store))
+    options = {"dry_run": True, "speed": a.speed} if a.dry_run else {}
+    if a.poses:
+        options["poses_dir"] = a.poses
+    if a.no_headset_button:
+        options["button"] = False
+    if a.ignore_cameras:
+        options["check_cameras"] = False
+    backend = Backend(store, options, hub_dry_run=a.hub_dry_run, ignore_cameras=a.ignore_cameras)
+    app.aboutToQuit.connect(backend.shutdown)
+    engine.rootContext().setContextProperty("backend", backend)
+    engine.rootContext().setContextProperty("startPage", a.page)
+    engine.load(QUrl.fromLocalFile(os.path.join(HERE, "main.qml")))
+    if not engine.rootObjects():
+        sys.exit(1)
+
+    # SIGTERM and Ctrl+C quit as closing does, so a running session still stops cleanly. Python
+    # runs signal handlers between bytecodes: the timer gives it some while Qt waits.
+    def on_signal(*_):
+        engine.rootObjects()[0].setProperty("quitting", True)
+        app.quit()
+    signal.signal(signal.SIGTERM, on_signal)
+    signal.signal(signal.SIGINT, on_signal)
+    tick = QTimer(interval=500, timeout=lambda: None)
+    tick.start()
+    sys.exit(app.exec())
+
+
+if __name__ == "__main__":
+    main()
diff --git a/hands/rec/hub.py b/hands/rec/hub.py
new file mode 100755
index 0000000..f1abff2
--- /dev/null
+++ b/hands/rec/hub.py
@@ -0,0 +1,468 @@
+#!/usr/bin/env python3
+"""Upload a hand recorder export to the hand dataset on Hugging Face (DESIGN.md "Upload").
+
+The window runs this as a child process (so Cancel can end it, and huggingface_hub stays out
+of the window's process); it also runs from the command line. It uses huggingface_hub (in the
+dev container: python3-huggingface-hub, from setup/dev-container.sh) with the login that
+`hub.py login` (the window's Log in) or `hf auth login` saved. Nobody types a token anywhere.
+
+`login` is huggingface_hub's browser login (OAuth device code, as `hf auth login` does): it gets a
+link and a short code, the person enters the code in their browser and approves, and the token goes
+straight from Hugging Face into huggingface_hub's token file. This process saves it; it never
+prints it, and the window never sees it.
+
+An upload:
+  1. checks the export with validate.py, and stops on errors;
+  2. stops if this export (same SHA256SUMS) was uploaded before, unless --again;
+  3. stops while CONSENT.md or UPLOAD.md is a draft, unless FT_HANDREC_ALLOW_UPLOAD=1;
+  4. checks the login (whoami: a read-only token can't open a pull request) and access to the
+     dataset (auth_check: a gated dataset's terms must be accepted first);
+  5. opens the pull request first (a draft, empty), so its link can be shown while the files go,
+     and records it under "uploads" in session.json with "status": "started";
+  6. upload_folder(..., revision="refs/pr/N") to contributions/<contributor>/<session>; a retry of
+     the same export goes on in the same pull request while it's still open;
+  7. marks the record {"repo", "pr_url", "pr_num", "uploaded", "export_sha", "status": "done"}.
+--dry-run does all of it except the network calls (4 to 6) and recording (5, 7), and says what
+it would upload.
+
+The dataset is HF_DATASET; FT_HANDREC_DATASET overrides it (a test repo, for rehearsals).
+
+usage: hub.py [--base DIR] whoami [--json]
+       hub.py [--base DIR] login [--json]
+       hub.py [--base DIR] upload SESSION [--dry-run] [--again] [--json]
+With --json, each line of output is one JSON object: {"phase", "text", "fraction"} as it goes,
+with {"phase": "opened", "pr_url"} once the pull request exists, then {"done": {...}} or
+{"error": {"kind", "text", "link", "errors"}}. login says {"phase": "code", "url", "code",
+"expires_in"} once it has the link, then {"done": {"name", "role"}}. Exit status 0: done.
+"""
+import argparse
+import datetime
+import hashlib
+import json
+import os
+import re
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+import takes  # noqa: E402  (next to this file)
+
+# The dataset contributions go to (DESIGN.md "Licensing and consent").
+HF_DATASET = "DeeJanuz/frametop-hands"
+DATASET_ENV = "FT_HANDREC_DATASET"
+ALLOW_ENV = "FT_HANDREC_ALLOW_UPLOAD"
+CONSENT_PATH = os.path.join(HERE, "CONSENT.md")
+UPLOAD_PATH = os.path.join(HERE, "UPLOAD.md")
+REPO_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*$")
+TOKENS_URL = "https://huggingface.co/settings/tokens"
+# Quiet huggingface_hub: no progress bars on stderr, no telemetry or update hints.
+HF_ENV = {"HF_HUB_DISABLE_PROGRESS_BARS": "1", "HF_HUB_DISABLE_TELEMETRY": "1", "HF_HUB_DISABLE_UPDATE_CHECK": "1"}
+
+
+class HubError(Exception):
+    """What went wrong, for people: kind (below), text, a link to open, validation errors.
+    Kinds: missing (no huggingface_hub), login, read-token, terms, not-found, permission,
+    network, hub, invalid, duplicate, closed, no-export."""
+
+    def __init__(self, kind, text, link="", errors=None, extra=None):
+        super().__init__(text)
+        self.kind, self.text, self.link = kind, text, link
+        self.errors = errors or []
+        self.extra = extra or {}
+
+    def as_dict(self):
+        return dict(self.extra, kind=self.kind, text=self.text, link=self.link, errors=self.errors)
+
+
+def dataset_id():
+    """HF_DATASET, or FT_HANDREC_DATASET when set."""
+    repo = os.environ.get(DATASET_ENV, "").strip() or HF_DATASET
+    if not REPO_RE.match(repo):
+        raise HubError("not-found", f"{DATASET_ENV}={repo!r} isn't a dataset id like owner/name")
+    return repo
+
+
+def dataset_url(repo=None):
+    return "https://huggingface.co/datasets/" + (repo or dataset_id())
+
+
+def is_draft(path):
+    try:
+        with open(path, encoding="utf-8") as f:
+            return "DRAFT" in f.readline()
+    except OSError:
+        return False
+
+
+def texts_draft():
+    return is_draft(CONSENT_PATH) or is_draft(UPLOAD_PATH)
+
+
+def upload_allowed():
+    """Real uploads: once the texts aren't drafts, or for the maintainer's rehearsal against a
+    test repo (FT_HANDREC_ALLOW_UPLOAD=1)."""
+    return not texts_draft() or os.environ.get(ALLOW_ENV) == "1"
+
+
+def now_iso():
+    return datetime.datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+# ---------------------------------------------------------------- records in session.json
+
+def export_sha(export_dir):
+    """The export's identity: the SHA256 of its SHA256SUMS ("" if there's none)."""
+    try:
+        with open(os.path.join(export_dir, "SHA256SUMS"), "rb") as f:
+            return hashlib.sha256(f.read()).hexdigest()
+    except OSError:
+        return ""
+
+
+def uploads(store, session):
+    meta = takes.read_json(os.path.join(store.session_dir(session), "session.json"))
+    return [u for u in meta.get("uploads") or [] if isinstance(u, dict)]
+
+
+def previous_upload(store, session, sha):
+    """The latest finished upload of this same export, or None. (Records from before
+    2026-10-03 have no status: they were written only when an upload finished.)"""
+    same = [u for u in uploads(store, session) if sha and u.get("export_sha") == sha
+            and u.get("status", "done") == "done"]
+    return same[-1] if same else None
+
+
+def unfinished_upload(store, session, sha, repo):
+    """The latest upload of this same export to repo that opened its pull request and didn't
+    finish, or None."""
+    same = [u for u in uploads(store, session) if sha and u.get("export_sha") == sha and u.get("repo") == repo
+            and u.get("status") == "started" and u.get("pr_num")]
+    return same[-1] if same else None
+
+
+def record_upload(store, session, record):
+    """Add record to session.json's "uploads". The file keeps its time: an upload doesn't
+    change the recordings, so the export mustn't count as out of date because of it
+    (takes.Store.sessions compares times)."""
+    path = os.path.join(store.session_dir(session), "session.json")
+    try:
+        st = os.stat(path)
+    except OSError:
+        st = None
+    meta = takes.read_json(path)
+    records = meta.setdefault("uploads", [])
+    same = [i for i, u in enumerate(records) if isinstance(u, dict) and record.get("pr_num")
+            and u.get("pr_num") == record["pr_num"] and u.get("repo") == record.get("repo")]
+    if same:
+        records[same[-1]] = record   # the same pull request: started, then done
+    else:
+        records.append(record)
+    takes.write_json(path, meta)
+    if st:
+        os.utime(path, ns=(st.st_atime_ns, st.st_mtime_ns))
+
+
+# ---------------------------------------------------------------- the pull request's text
+
+def describe(summary, report, sha, nbytes):
+    """(commit message, commit description) from validate's summary of the manifest."""
+    s = summary
+    objects = ", ".join(s.get("objects") or []) or "none"
+    if s.get("own_objects"):
+        objects += f" (+{s['own_objects']} of their own)"
+    message = f"Hands: session {s.get('session')} from {s.get('contributor')}"
+    lines = ["Contribution to the Frametop hand dataset, uploaded from the hand recorder.", "",
+             f"- Session: {s.get('session')}",
+             f"- Contributor: {s.get('contributor')}",
+             f"- Takes: {s.get('takes')} ({s.get('minutes')} minutes, {s.get('sets')} frame sets)",
+             f"- Lighting: {s.get('lighting') or 'not given'}",
+             f"- Objects: {objects}",
+             f"- Controllers: {s.get('controllers') or 'not given'}",
+             f"- Consent version: {s.get('consent_version')}",
+             f"- Tool: {s.get('tool')}",
+             f"- Size: {takes.human_bytes(nbytes)}",
+             f"- SHA256 of SHA256SUMS: {sha}", "",
+             "Checked with hands/rec/validate.py: no errors" + (f", {len(report.warnings)} warnings:"
+                                                                 if report.warnings else ".")]
+    lines += [f"- {w}" for w in report.warnings]
+    return message, "\n".join(lines) + "\n"
+
+
+# ---------------------------------------------------------------- talking to the Hub
+
+def _hf():
+    os.environ.update({k: v for k, v in HF_ENV.items() if k not in os.environ})
+    try:
+        import huggingface_hub
+    except ImportError:
+        raise HubError("missing", "huggingface_hub isn't installed in the dev container: run setup/dev-container.sh "
+                                  "(or: pip install --user huggingface_hub)") from None
+    return huggingface_hub
+
+
+def explain(e, repo):
+    """A huggingface_hub (or network) exception as a HubError."""
+    if isinstance(e, HubError):
+        return e
+    try:
+        from huggingface_hub import errors as hf
+    except ImportError:
+        hf = None
+    url = dataset_url(repo)
+    if hf is not None:
+        if isinstance(e, hf.LocalTokenNotFoundError):
+            return HubError("login", "You're not logged in to Hugging Face. Press Log in.")
+        if isinstance(e, hf.GatedRepoError):
+            return HubError("terms", f"Accept the dataset's terms first: open {url}, read them and accept them, "
+                                     "then try again.", url)
+        if isinstance(e, hf.RepositoryNotFoundError):
+            return HubError("not-found", f"The dataset {repo} wasn't found, or it's private and your account has "
+                                         "no access to it.", url)
+        if isinstance(e, hf.HfHubHTTPError):
+            status = getattr(getattr(e, "response", None), "status_code", None)
+            first = str(e).strip().splitlines()[0] if str(e).strip() else type(e).__name__
+            if status == 401:
+                return HubError("login", "Hugging Face didn't accept your login (it may have expired or been "
+                                         "revoked). Log in again.")
+            if status == 403:
+                return HubError("permission", "Your login isn't allowed to open a pull request. Log in again, "
+                                              "and allow everything the Hugging Face page asks for.")
+            return HubError("hub", f"Hugging Face refused the upload ({status or 'no status'}): {first}")
+    try:
+        import httpx
+        net = (httpx.TransportError, OSError)
+    except ImportError:
+        net = (OSError,)
+    if isinstance(e, net):
+        return HubError("network", f"Couldn't reach huggingface.co ({type(e).__name__}: {e}). Check the network "
+                                   "and try again: files already sent usually aren't sent twice.")
+    return HubError("hub", f"{type(e).__name__}: {e}")
+
+
+def whoami():
+    """{"name", "role"} for the saved login; HubError if there's none or it doesn't work.
+    role: "write", "read", "fineGrained" or ""."""
+    hf = _hf()
+    try:
+        info = hf.HfApi().whoami()
+    except Exception as e:
+        raise explain(e, dataset_id()) from None
+    token = ((info.get("auth") or {}).get("accessToken") or {})
+    return {"name": info.get("name", ""), "role": token.get("role", "")}
+
+
+def login(progress=None):
+    """The browser login: progress("code", text, url=, code=, expires_in=) once the link is ready,
+    then wait (up to the code's expiry: 5 minutes on 2026-10-03) for the person to approve it, and save
+    the token. Returns whoami(). Uses huggingface_hub's own device code helpers (1.x)."""
+    tell = progress or (lambda phase, text, **extra: None)
+    _hf()
+    try:
+        from huggingface_hub._login import _save_oauth_token
+        from huggingface_hub.errors import DeviceCodeError
+        from huggingface_hub.utils._oauth_device import poll_device_token, request_device_code
+    except ImportError:
+        raise HubError("missing", "This huggingface_hub has no browser login: update the dev container "
+                                  "(setup/dev-container.sh).") from None
+    try:
+        info = request_device_code()
+        tell("code", "Approve the login in your browser", url=info["verification_uri_complete"],
+             code=info["user_code"], expires_in=info["expires_in"])
+        _save_oauth_token(poll_device_token(info))
+    except DeviceCodeError as e:
+        raise HubError("login", f"The login didn't go through: {e}. Press Log in to try again.") from None
+    except Exception as e:
+        raise explain(e, dataset_id()) from None
+    return whoami()
+
+
+def upload(store, session, dry_run=False, again=False, progress=None, log=None):
+    """Upload exports/<session> (the steps in this file's docstring). progress(phase, text,
+    fraction or None); log(text) for the dry run's account. Returns the result; raises HubError."""
+    tell = progress or (lambda phase, text, fraction=None, **extra: None)
+    say = log or (lambda text: None)
+    import validate
+    repo = dataset_id()
+    try:
+        export = store.export_dir(session)
+    except ValueError as e:
+        raise HubError("no-export", str(e)) from None
+    if not os.path.isfile(os.path.join(export, "manifest.json")):
+        raise HubError("no-export", f"No export of session {session}: export it first")
+
+    tell("check", "Checking the export", 0.0)
+    report = validate.validate(export, progress=lambda f, text: tell("check", text, f))
+    if not report.ok:
+        raise HubError("invalid", f"The export has {len(report.errors)} problems, so it can't be uploaded. Export "
+                                  "the session again; if that doesn't help, report it.", errors=report.errors)
+    summary = report.summary
+    contributor = summary.get("contributor", "")
+    sha = export_sha(export)
+    before = previous_upload(store, session, sha)
+    if before and not again:
+        raise HubError("duplicate", f"This export was uploaded already, on {before.get('uploaded', '?')}: "
+                                    f"{before.get('pr_url', '')}", before.get("pr_url", ""), extra={"previous": before})
+    if not dry_run and not upload_allowed():
+        raise HubError("closed", "Contributions aren't open yet: the texts are drafts waiting for a legal review. "
+                                 f"(For a rehearsal against a test repo: {ALLOW_ENV}=1.)")
+    path_in_repo = f"contributions/{contributor}/{session}"
+    message, description = describe(summary, report, sha, report.bytes)
+    files = []
+    for root, _, names in os.walk(export):
+        files += [os.path.relpath(os.path.join(root, n), export) for n in names]
+    plan = {"repo": repo, "repo_type": "dataset", "folder_path": export, "path_in_repo": path_in_repo,
+            "create_pr": True, "commit_message": message, "commit_description": description,
+            "files": len(files), "bytes": report.bytes, "warnings": report.warnings}
+
+    if dry_run:
+        say(f"dry run: would check the login (whoami) and access to {repo} (auth_check)")
+        say(f"dry run: would upload_folder {len(files)} files, {takes.human_bytes(report.bytes)}, "
+            f"from {export} to datasets/{repo}/{path_in_repo}, as a pull request")
+        for rel in sorted(files):
+            say(f"  {rel}  {takes.human_bytes(os.path.getsize(os.path.join(export, rel)))}")
+        say(f"dry run: commit message: {message}")
+        say("dry run: commit description:\n" + description.rstrip())
+        record = {"repo": repo, "pr_url": "", "uploaded": now_iso(), "export_sha": sha, "status": "done"}
+        say(f"dry run: would record in session.json's uploads: {json.dumps(record)}")
+        tell("done", "Dry run: nothing was uploaded", 1.0)
+        return dict(plan, dry_run=True, pr_url="", record=record)
+
+    hf = _hf()
+    api = hf.HfApi()
+    tell("login", "Checking your Hugging Face login", None)
+    try:
+        who = api.whoami()
+    except Exception as e:
+        raise explain(e, repo) from None
+    role = ((who.get("auth") or {}).get("accessToken") or {}).get("role", "")
+    if role == "read":
+        raise HubError("read-token", "Your saved login is a read-only token, so it can't open a pull request. "
+                                     "Log in again.")
+    tell("access", f"Checking access to {repo}", None)
+    try:
+        api.auth_check(repo, repo_type="dataset")
+    except Exception as e:
+        raise explain(e, repo) from None
+    # The pull request first, so its link shows while the files go (and the person can plug the
+    # headset in and leave it). A retry of this export goes on in its pull request if it's open.
+    tell("open", "Opening your pull request", None)
+    pr = None
+    before = unfinished_upload(store, session, sha, repo)
+    if before:
+        try:
+            d = api.get_discussion_details(repo, int(before["pr_num"]), repo_type="dataset")
+            if d.is_pull_request and d.status in ("draft", "open"):
+                pr = d
+        except Exception:
+            pr = None
+    if pr is None:
+        try:
+            pr = api.create_pull_request(repo, message, description=description, repo_type="dataset")
+        except Exception as e:
+            raise explain(e, repo) from None
+    pr_url = getattr(pr, "url", "") or f"{dataset_url(repo)}/discussions/{pr.num}"
+    record = {"repo": repo, "pr_url": pr_url, "pr_num": pr.num, "started": now_iso(), "export_sha": sha,
+              "status": "started"}
+    record_upload(store, session, record)
+    tell("opened", f"Pull request #{pr.num} is open. Uploading {len(files)} files ({takes.human_bytes(report.bytes)})",
+         None, pr_url=pr_url)
+    try:
+        api.upload_folder(repo_id=repo, repo_type="dataset", folder_path=export, path_in_repo=path_in_repo,
+                          revision=f"refs/pr/{pr.num}", commit_message=message, commit_description=description)
+    except Exception as e:
+        raise explain(e, repo) from None
+    try:   # a pull request opened through the API stays a draft until it's marked open
+        if api.get_discussion_details(repo, pr.num, repo_type="dataset").status == "draft":
+            api.change_discussion_status(repo, pr.num, "open", repo_type="dataset")
+    except Exception:
+        pass   # the maintainer can open it
+    record = dict(record, uploaded=now_iso(), status="done")
+    record_upload(store, session, record)
+    tell("done", "Uploaded", 1.0)
+    return dict(plan, dry_run=False, pr_url=pr_url, pr_num=pr.num, user=who.get("name", ""), record=record)
+
+
+# ---------------------------------------------------------------- the command line
+
+def main():
+    ap = argparse.ArgumentParser(description="Upload a hand recorder export to the hand dataset on Hugging Face.")
+    ap.add_argument("--base", default=takes.DEFAULT_BASE)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    w = sub.add_parser("whoami", help="show the saved Hugging Face login")
+    w.add_argument("--json", action="store_true")
+    li = sub.add_parser("login", help="log in to Hugging Face in the browser")
+    li.add_argument("--json", action="store_true")
+    u = sub.add_parser("upload", help="upload exports/SESSION as a pull request")
+    u.add_argument("session")
+    u.add_argument("--dry-run", action="store_true", help="no network: say what would be uploaded")
+    u.add_argument("--again", action="store_true", help="upload even if this export was uploaded before")
+    u.add_argument("--json", action="store_true", help="JSON lines, for the window")
+    a = ap.parse_args()
+
+    def emit(obj):
+        print(json.dumps(obj), flush=True)
+
+    try:
+        if a.cmd == "whoami":
+            who = whoami()
+            if a.json:
+                emit({"done": who})
+            else:
+                print(f"logged in as {who['name']} (token role: {who['role'] or 'unknown'})")
+            return 0
+        if a.cmd == "login":
+            def code(phase, text, **extra):
+                if a.json:
+                    emit(dict(extra, phase=phase, text=text))
+                else:
+                    print(f"Open {extra['url']} and approve the code {extra['code']}. Waiting...", flush=True)
+            who = login(code)
+            if a.json:
+                emit({"done": who})
+            else:
+                print(f"logged in as {who['name']}")
+            return 0
+        if a.json:
+            def progress(phase, text, fraction=None, **extra):
+                emit(dict(extra, phase=phase, text=text, fraction=fraction))
+
+            def log(text):
+                emit({"log": text})
+        else:
+            last = {}
+
+            def progress(phase, text, fraction=None, **extra):
+                if extra.get("pr_url"):
+                    print(f"pull request: {extra['pr_url']}", flush=True)
+                line = text if fraction is None else f"{fraction * 100:5.1f}% {text}"
+                if (phase, text) != last.get("key") or fraction in (0.0, 1.0):
+                    print(line, file=sys.stderr, flush=True)
+                last["key"] = (phase, text)
+
+            def log(text):
+                print(text, flush=True)
+        if hasattr(os, "setpriority"):
+            try:
+                os.setpriority(os.PRIO_PROCESS, 0, 19)   # validation reads and hashes everything: stay out of VR's way
+            except OSError:
+                pass
+        result = upload(takes.Store(a.base), a.session, dry_run=a.dry_run, again=a.again, progress=progress, log=log)
+        if a.json:
+            emit({"done": result})
+        elif result["dry_run"]:
+            print(f"dry run done: {result['files']} files would go to datasets/{result['repo']}/{result['path_in_repo']}")
+        else:
+            print(f"uploaded: {result['pr_url']}")
+        return 0
+    except HubError as e:
+        if a.json:
+            emit({"error": e.as_dict()})
+        else:
+            print(f"error ({e.kind}): {e.text}", file=sys.stderr)
+            for line in e.errors:
+                print(f"  {line}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/hands/rec/install.sh b/hands/rec/install.sh
new file mode 100755
index 0000000..92a1c0d
--- /dev/null
+++ b/hands/rec/install.sh
@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Install the hand recorder on a Frame that has Frametop (get.sh --experimental): bring the dev
+# container's packages up to date, build hand tracking's camera broker and tracker (hands/build.sh:
+# the first build fetches and builds ncnn, a few minutes) and the headset panel (hands/rec/build.sh),
+# give ft-camd its capabilities (hands/run.sh caps: asks for the password, once per build), and add
+# "Frametop Hand Recorder" to the app menu (for Frametop's desktop: it isn't tested from SteamVR's
+# "Launch a program", which runs apps outside it; the standalone recorder is for that).
+# It doesn't turn on Frametop's live hand tracking (that's hands/run.sh install, still deferred).
+# Usage: hands/rec/install.sh            install or update
+#        hands/rec/install.sh uninstall  remove the menu entry (recordings stay where they are)
+set -euo pipefail
+root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
+. "$root/scripts/_env.sh"
+entry='~/.local/share/applications/frametop-handrec.desktop'
+
+case ${1:-install} in
+  install)
+    echo "== 1/4 dev container packages"
+    "$root/setup/dev-container.sh"
+    echo "== 2/4 hand tracking: ft-camd and ft-hands"
+    "$root/hands/build.sh"
+    echo "== 3/4 the headset panel: ft-handpanel"
+    "$root/hands/rec/build.sh"
+    echo "== 4/4 ft-camd's capabilities (asks for your password) and the menu entry"
+    "$root/hands/run.sh" caps
+    fill_template "$root/hands/rec/ft-handrec.desktop" |
+      on_frame "mkdir -p ~/.local/share/applications && cat > $entry"
+    echo
+    echo "Installed. On Frametop's desktop, open \"Frametop Hand Recorder\" from the app menu."
+    echo "Recordings go to ~/.local/share/frametop/hands/contrib."
+    ;;
+  uninstall)
+    on_frame "rm -f $entry"
+    echo "Removed the menu entry. Your recordings are still in ~/.local/share/frametop/hands/contrib:"
+    echo "delete that folder to remove them."
+    ;;
+  *) echo "usage: $0 [install|uninstall]" >&2; exit 2 ;;
+esac
diff --git a/hands/rec/main.qml b/hands/rec/main.qml
new file mode 100644
index 0000000..2e891e9
--- /dev/null
+++ b/hands/rec/main.qml
@@ -0,0 +1,1846 @@
+// Frametop Hand Recorder (Kirigami). Backend: ft_handrec.py ("backend"); frame sets come from
+// its image provider (image://frames/...).
+import QtQuick
+import QtQuick.Controls as Controls
+import QtQuick.Layouts
+import org.kde.kirigami as Kirigami
+
+Kirigami.ApplicationWindow {
+    id: root
+    title: "Frametop Hand Recorder"
+    width: Kirigami.Units.gridUnit * 50
+    height: Kirigami.Units.gridUnit * 36
+
+    // The session chosen on the Export page, for the Upload page.
+    property string chosenSession: ""
+
+    globalDrawer: Kirigami.GlobalDrawer {
+        isMenu: false
+        modal: false
+        collapsible: true
+        collapsed: root.width < Kirigami.Units.gridUnit * 34
+        actions: [
+            Kirigami.Action { text: "Welcome"; icon.name: "help-about"; onTriggered: root.show(welcomePage) },
+            Kirigami.Action {
+                text: "Before you start"; icon.name: "view-task"; enabled: !backend.needsConsent
+                onTriggered: root.show(checklistPage)
+            },
+            Kirigami.Action {
+                text: "Session"; icon.name: "media-record"; enabled: !backend.needsConsent
+                onTriggered: root.show(sessionPage)
+            },
+            Kirigami.Action { text: "Review"; icon.name: "view-preview"; onTriggered: root.show(reviewPage) },
+            Kirigami.Action {
+                text: "Export"; icon.name: "document-export"; enabled: !backend.needsConsent
+                onTriggered: root.show(exportPage)
+            },
+            Kirigami.Action {
+                text: "Upload"; icon.name: "cloud-upload"; enabled: !backend.needsConsent
+                onTriggered: root.show(uploadPage)
+            }
+        ]
+    }
+
+    // The texts wait for a legal review; until then nobody should contribute.
+    component DraftBanner: Kirigami.InlineMessage {
+        visible: backend.textsDraft
+        position: Kirigami.InlineMessage.Position.Header
+        type: Kirigami.MessageType.Warning
+        text: "Contributions aren't open yet. These texts are drafts waiting for a legal review: you can "
+              + "record and review, but please don't upload anything until this message is gone."
+    }
+
+    // Read-only Markdown (CONSENT.md, UPLOAD.md), selectable for copying.
+    component MarkdownText: Controls.TextArea {
+        id: markdownText
+        property string markdown
+        // Links get the application palette's colour when the text is parsed, and Kirigami's theme
+        // doesn't set that palette: set it, then parse again (the theme resolves after creation).
+        readonly property color linkColor: Kirigami.Theme.linkColor
+        function parse() {
+            backend.setLinkColor(linkColor)
+            text = markdown
+        }
+        onLinkColorChanged: parse()
+        onMarkdownChanged: parse()
+        Component.onCompleted: parse()
+        textFormat: TextEdit.MarkdownText
+        readOnly: true
+        selectByMouse: true
+        wrapMode: Text.Wrap
+        background: null
+        padding: 0
+        onLinkActivated: link => Qt.openUrlExternally(link)
+    }
+
+    function plural(n, word) {
+        return n + " " + word + (n === 1 ? "" : "s")
+    }
+
+    function show(page) {
+        pageStack.clear()
+        pageStack.push(page)
+    }
+
+    // --page welcome|checklist|session|review|export|upload opens the app on that page; the
+    // Welcome page comes first until the consent is agreed to.
+    pageStack.initialPage: backend.needsConsent && startPage !== "review" ? welcomePage
+        : (({ welcome: welcomePage, checklist: checklistPage, session: sessionPage, review: reviewPage,
+              export: exportPage, upload: uploadPage })[startPage] || checklistPage)
+
+    Connections {
+        target: backend
+        function onMessage(text, isError) {
+            root.showPassiveNotification(text, isError ? "long" : "short")
+        }
+    }
+
+    // Asks before something is deleted for good: ask(title, text, function).
+    Kirigami.PromptDialog {
+        id: confirm
+        property var action: null
+        standardButtons: Controls.Dialog.Ok | Controls.Dialog.Cancel
+        onAccepted: if (action) action()
+        function ask(title, text, fn) {
+            confirm.title = title
+            confirm.subtitle = text
+            confirm.action = fn
+            confirm.open()
+        }
+    }
+
+    // Restart SteamVR (the camera check's fix). What it does to Frametop, read from the code
+    // (hands/README.md, "Camera check"): ft-screens quits when SteamVR does, which ends the
+    // desktop; its unit doesn't restart, and stopping it ends what was started in it.
+    function askRestartSteamVR() {
+        confirm.ask("Restart SteamVR?",
+                    "SteamVR starts its cameras again, and with them the colour camera module. This closes every "
+                    + "VR app. It also closes the Frametop desktop with all its windows, this one too: Frametop's "
+                    + "screens don't come back by themselves. Save your work first; programs started from the "
+                    + "desktop, such as terminals and what runs in them, stop too.\n\nOnce SteamVR is back, start "
+                    + "the desktop again (Desktop in the library) and open the Hand recorder: it checks the cameras "
+                    + "again. If they're still off, restart the headset.",
+                    () => backend.restartSteamVR())
+    }
+
+    // The camera check's problem, with its fix (a header message on the checklist and session pages).
+    component CameraMessage: Kirigami.InlineMessage {
+        position: Kirigami.InlineMessage.Position.Header
+        type: backend.restartingSteamVR ? Kirigami.MessageType.Information : Kirigami.MessageType.Error
+        text: backend.restartingSteamVR ? "Restarting SteamVR, then checking the cameras again…" : backend.cameraText
+        actions: [
+            Kirigami.Action {
+                text: "Restart SteamVR…"
+                icon.name: "system-reboot"
+                enabled: !backend.restartingSteamVR && !backend.sessionActive
+                onTriggered: root.askRestartSteamVR()
+            },
+            Kirigami.Action {
+                text: "Check again"
+                icon.name: "view-refresh"
+                enabled: !backend.cameraBusy
+                onTriggered: backend.checkCameras()
+            }
+        ]
+    }
+
+    // Closing during a session asks first. Quitting closes the window again (Qt 6), so the
+    // answer is remembered; the backend stops the session as the app quits.
+    property bool quitting: false
+    onClosing: close => {
+        if (backend.sessionActive && !quitting) {
+            close.accepted = false
+            confirm.ask("Stop the session?", "A session is recording. Closing stops it; what's recorded so far is kept.",
+                        () => { root.quitting = true; Qt.quit() })
+        } else if (backend.uploading && !quitting) {
+            close.accepted = false
+            confirm.ask("Cancel the upload?", "An upload is running. Closing cancels it; you can start it again later.",
+                        () => { root.quitting = true; Qt.quit() })
+        }
+    }
+
+    // ---------------------------------------------------------------- Welcome
+    Component {
+        id: welcomePage
+        Kirigami.ScrollablePage {
+            title: "Welcome"
+            header: DraftBanner { }
+
+            ColumnLayout {
+                spacing: Kirigami.Units.largeSpacing
+
+                MarkdownText {
+                    Layout.fillWidth: true
+                    markdown: backend.consentText
+                }
+
+                Kirigami.Separator { Layout.fillWidth: true }
+
+                Kirigami.InlineMessage {
+                    Layout.fillWidth: true
+                    visible: !backend.needsConsent
+                    type: Kirigami.MessageType.Positive
+                    text: "You agreed to this text (" + backend.consentAccepted + "). Your contributor id is "
+                          + backend.contributor + ": keep it if you might want to withdraw later."
+                }
+                Controls.Button {
+                    visible: !backend.needsConsent
+                    text: "Copy contributor id"
+                    icon.name: "edit-copy"
+                    onClicked: backend.copy(backend.contributor)
+                }
+                Kirigami.InlineMessage {
+                    Layout.fillWidth: true
+                    visible: backend.needsConsent && backend.contributor !== ""
+                    type: Kirigami.MessageType.Information
+                    text: "This text changed since you last agreed to it. Please read it again; your contributor id stays the same."
+                }
+
+                Controls.CheckBox {
+                    id: adult
+                    visible: backend.needsConsent
+                    text: "I'm 18 or older"
+                }
+                Controls.CheckBox {
+                    id: region
+                    visible: backend.needsConsent
+                    text: "I don't live in Illinois, Texas or Washington (USA)"
+                }
+                Controls.CheckBox {
+                    id: agree
+                    visible: backend.needsConsent
+                    text: "I agree to the text above"
+                }
+                RowLayout {
+                    visible: backend.needsConsent
+                    Controls.Label { text: "Handedness (optional):" }
+                    Controls.ComboBox {
+                        id: handed
+                        model: backend.handednessChoices
+                        textRole: "text"
+                        valueRole: "value"
+                        Component.onCompleted: currentIndex = Math.max(0, indexOfValue(backend.handedness))
+                    }
+                }
+                Controls.Button {
+                    visible: backend.needsConsent
+                    enabled: adult.checked && region.checked && agree.checked
+                    text: "Agree and continue"
+                    icon.name: "go-next"
+                    onClicked: {
+                        backend.acceptConsent(adult.checked, region.checked, agree.checked, handed.currentValue)
+                        if (!backend.needsConsent)
+                            root.show(checklistPage)
+                    }
+                }
+                Controls.Button {
+                    visible: !backend.needsConsent
+                    text: "Continue"
+                    icon.name: "go-next"
+                    onClicked: root.show(checklistPage)
+                }
+            }
+        }
+    }
+
+    // ---------------------------------------------------------------- Before you start
+    Component {
+        id: checklistPage
+        Kirigami.ScrollablePage {
+            id: checklist
+            title: "Before you start"
+            readonly property bool privacyOk: privacy1.checked && privacy2.checked && privacy3.checked
+            readonly property bool ready: privacyOk && backend.diskOk
+                                          && backend.runnerError === "" && !backend.sessionActive
+
+            function answers() {
+                const objects = []
+                for (let i = 0; i < objectBoxes.count; ++i) {
+                    const box = objectBoxes.itemAt(i)
+                    if (box.checked)
+                        objects.push(box.value)
+                }
+                return {
+                    objects: objects,
+                    own_objects: ownObjects.text.split(",").map(s => s.trim()).filter(s => s !== ""),
+                    controllers: straps.checked ? "straps" : "none",
+                    sleeves: sleeves.currentValue,
+                    rings: rings.checked,
+                    watch: watch.checked,
+                    notes: notes.text,
+                    privacy: privacyOk
+                }
+            }
+
+            header: ColumnLayout {
+                spacing: 0
+                DraftBanner { Layout.fillWidth: true }
+                Kirigami.InlineMessage {
+                    Layout.fillWidth: true
+                    visible: backend.runnerError !== ""
+                    position: Kirigami.InlineMessage.Position.Header
+                    type: Kirigami.MessageType.Error
+                    text: backend.runnerError
+                }
+                Kirigami.InlineMessage {
+                    Layout.fillWidth: true
+                    visible: backend.sessionActive
+                    position: Kirigami.InlineMessage.Position.Header
+                    type: Kirigami.MessageType.Information
+                    text: "A session is running."
+                    actions: [ Kirigami.Action { text: "Go to it"; onTriggered: root.show(sessionPage) } ]
+                }
+                CameraMessage {
+                    Layout.fillWidth: true
+                    visible: !backend.sessionActive && (backend.cameraText !== "" || backend.restartingSteamVR)
+                }
+            }
+            Component.onCompleted: backend.checkCameras()
+
+            Kirigami.FormLayout {
+                Kirigami.Separator { Kirigami.FormData.isSection: true; Kirigami.FormData.label: "Within reach" }
+                Controls.Label {
+                    Kirigami.FormData.label: ""
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    wrapMode: Text.Wrap
+                    text: "Put these on the desk or table in front of you. Untick what you don't have; "
+                          + "the session skips those."
+                }
+                Repeater {
+                    id: objectBoxes
+                    model: backend.objects
+                    Controls.CheckBox {
+                        required property var modelData
+                        required property int index
+                        readonly property string value: modelData.value
+                        Kirigami.FormData.label: index === 0 ? "Objects:" : ""
+                        text: modelData.text
+                        checked: true
+                    }
+                }
+                Controls.TextField {
+                    id: ownObjects
+                    Kirigami.FormData.label: "Your own:"
+                    Layout.preferredWidth: Kirigami.Units.gridUnit * 20
+                    placeholderText: "other things you use, separated by commas"
+                }
+
+                Kirigami.Separator { Kirigami.FormData.isSection: true; Kirigami.FormData.label: "Controllers" }
+                ColumnLayout {
+                    Kirigami.FormData.label: "Ergonomic Kit straps:"
+                    Controls.RadioButton { id: straps; text: "Yes, I have the controllers with the straps" }
+                    Controls.RadioButton { text: "No"; checked: true }
+                }
+                Controls.Label {
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    wrapMode: Text.Wrap
+                    opacity: 0.7
+                    text: "With the straps, the controllers stay on your hands while your fingers move freely. "
+                          + "The controllers' tracking then says exactly where your hands are, which teaches the "
+                          + "model how far away a hand is. Without them, the two controller sections are skipped."
+                }
+
+                Kirigami.Separator { Kirigami.FormData.isSection: true; Kirigami.FormData.label: "Light" }
+                Controls.Label {
+                    Kirigami.FormData.label: "The cameras see:"
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    wrapMode: Text.Wrap
+                    text: backend.lightingMeasured || "Not measured yet"
+                }
+                Controls.ComboBox {
+                    id: lighting
+                    Kirigami.FormData.label: "Lighting this round:"
+                    model: backend.lightingChoices
+                    textRole: "text"
+                    valueRole: "value"
+                    currentIndex: 0
+                    onActivated: backend.checkLighting(currentValue)
+                    Component.onCompleted: backend.checkLighting(currentValue)
+                }
+                Controls.Label {
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    wrapMode: Text.Wrap
+                    opacity: 0.7
+                    text: "Each round in a different light helps the most: dim, a normal room, daylight. The cameras "
+                          + "tell daylight from indoor light themselves; to say dim or a normal room, pick it here."
+                }
+                Kirigami.InlineMessage {
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    Layout.fillWidth: true
+                    visible: backend.lightingNote !== ""
+                    Layout.preferredHeight: visible ? implicitHeight : 0
+                    type: Kirigami.MessageType.Warning
+                    text: backend.lightingNote
+                }
+                Controls.Button {
+                    visible: backend.lightingNote !== "" || backend.lightingMeasured === ""
+                    text: "Measure the light again"
+                    icon.name: "view-refresh"
+                    onClicked: backend.checkLighting(lighting.currentValue)
+                }
+
+                Kirigami.Separator { Kirigami.FormData.isSection: true; Kirigami.FormData.label: "You" }
+                Controls.ComboBox {
+                    id: sleeves
+                    Kirigami.FormData.label: "Sleeves:"
+                    model: backend.sleeveChoices
+                    textRole: "text"
+                    valueRole: "value"
+                }
+                Controls.CheckBox { id: rings; Kirigami.FormData.label: "Wearing:"; text: "Rings" }
+                Controls.CheckBox { id: watch; text: "A watch or bracelet" }
+                Controls.Label {
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    wrapMode: Text.Wrap
+                    opacity: 0.7
+                    text: "Wear what you normally do: the dataset needs hands with and without them. This only notes it."
+                }
+                Controls.TextField {
+                    id: notes
+                    Kirigami.FormData.label: "Notes (optional):"
+                    Layout.preferredWidth: Kirigami.Units.gridUnit * 20
+                    placeholderText: "anything that helps, e.g. a bandage on a finger"
+                }
+
+                Kirigami.Separator { Kirigami.FormData.isSection: true; Kirigami.FormData.label: "Privacy" }
+                Controls.CheckBox {
+                    id: privacy1
+                    Kirigami.FormData.label: "I've checked:"
+                    text: "I'm facing away from other people, mirrors and windows"
+                }
+                Controls.CheckBox {
+                    id: privacy2
+                    text: "No papers, photos, screens or other private things are in view"
+                }
+                Controls.CheckBox {
+                    id: privacy3
+                    text: "Nobody else's face or hands will be in view"
+                }
+
+                Kirigami.Separator { Kirigami.FormData.isSection: true; Kirigami.FormData.label: "Space" }
+                Controls.Label {
+                    Kirigami.FormData.label: "Free space:"
+                    text: backend.freeText + " (a round takes about 10 GB)"
+                }
+                Kirigami.InlineMessage {
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    Layout.fillWidth: true
+                    visible: !backend.diskOk
+                    type: Kirigami.MessageType.Error
+                    text: "Not enough free space for a round. Export and delete earlier sessions (Review), "
+                          + "or free up space, first."
+                }
+
+                Kirigami.Separator { Kirigami.FormData.isSection: true; Kirigami.FormData.label: "Cameras" }
+                RowLayout {
+                    Kirigami.FormData.label: "Tracking cameras:"
+                    Controls.Label {
+                        Layout.maximumWidth: Kirigami.Units.gridUnit * 20
+                        wrapMode: Text.Wrap
+                        text: backend.camerasIgnored ? "Not checked (--ignore-cameras)"
+                              : backend.cameraState === "ok" ? "All four are running."
+                              : backend.cameraState === "degraded" ? "Not all running: see the message at the top."
+                              : backend.cameraState === "unknown" ? "Couldn't tell (" + backend.cameraSummary.replace(/^unknown: /, "")
+                                                                    + "). The session checks again when it starts."
+                              : "Checking…"
+                    }
+                    Controls.ToolButton {
+                        visible: backend.cameraEvidence !== ""
+                        icon.name: "documentinfo"
+                        text: "Details"
+                        checkable: true
+                        id: cameraDetails
+                        display: Controls.AbstractButton.IconOnly
+                        Controls.ToolTip.text: "What the check looked at"
+                        Controls.ToolTip.visible: hovered
+                    }
+                    Controls.ToolButton {
+                        icon.name: "view-refresh"
+                        text: "Check again"
+                        display: Controls.AbstractButton.IconOnly
+                        enabled: !backend.cameraBusy
+                        onClicked: backend.checkCameras()
+                        Controls.ToolTip.text: text
+                        Controls.ToolTip.visible: hovered
+                    }
+                }
+                Controls.Label {
+                    visible: cameraDetails.checked && backend.cameraEvidence !== ""
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 34
+                    wrapMode: Text.WrapAnywhere
+                    font: Kirigami.Theme.smallFont
+                    opacity: 0.7
+                    textFormat: Text.PlainText
+                    text: backend.cameraSummary + "\n" + backend.cameraEvidence
+                }
+
+                Kirigami.Separator { Kirigami.FormData.isSection: true; Kirigami.FormData.label: "What will happen" }
+                Controls.Label {
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    wrapMode: Text.Wrap
+                    text: "Press Start, then put the headset on. A panel in the headset shows each step: a picture "
+                          + "of the hand pose, where to hold your hands, and what to do. The sections: hand poses, "
+                          + "gestures, typing and the mouse, your objects, touching a dot, and moves with the "
+                          + "controllers on and off. Each section is recorded as one take. In the pose steps your "
+                          + "hands keep moving while a row of pictures lights up one shape after another: follow it.\n\n"
+                          + "Each step waits until you're ready: press the button on the right side of the headset, "
+                          + "or Space or Next in this window. A 3-2-1 "
+                          + "countdown follows, then hold the pose until the bar runs out. Nothing is recorded while "
+                          + "a step waits. The headset button also pauses and resumes a recording. In this window P "
+                          + "pauses, R records the last step again, S skips a section and Esc stops.\n\n"
+                          + "Nothing leaves the headset. Afterwards you watch the takes in Review, delete anything "
+                          + "you don't want to share, and only then export."
+                }
+                ColumnLayout {
+                    Kirigami.FormData.label: "Round:"
+                    Controls.RadioButton {
+                        id: fullRound
+                        text: "Full session"
+                        checked: !backend.hasFullSession
+                    }
+                    Controls.RadioButton {
+                        id: quickRound
+                        text: "Quick round (about 3 min): hand size, poses, the dot, no hands"
+                        checked: backend.hasFullSession
+                    }
+                }
+                Kirigami.InlineMessage {
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    Layout.fillWidth: true
+                    visible: backend.hasFullSession
+                    Layout.preferredHeight: visible ? implicitHeight : 0
+                    type: Kirigami.MessageType.Information
+                    text: "You've recorded a full session already. A quick round in a different light (dim, "
+                          + "daylight) adds the most now."
+                }
+                Controls.CheckBox {
+                    id: autoAdvance
+                    Kirigami.FormData.label: "Pace:"
+                    text: "Advance by itself (no Next between steps)"
+                }
+                Controls.Label {
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    wrapMode: Text.Wrap
+                    opacity: 0.7
+                    text: (autoAdvance.checked
+                           ? "Each step shows for a few seconds and the next follows by itself. Quicker if you "
+                             + "know the steps already. "
+                           : "") + "Length: " + backend.planText(checklist.answers(), autoAdvance.checked, quickRound.checked) + "."
+                }
+                Controls.Button {
+                    text: "Start"
+                    icon.name: "media-record"
+                    enabled: checklist.ready && !backend.camerasBlockStart && !backend.restartingSteamVR
+                    onClicked: {
+                        if (backend.startSession(checklist.answers(), lighting.currentValue, autoAdvance.checked,
+                                                 quickRound.checked))
+                            root.show(sessionPage)
+                    }
+                }
+                Controls.Label {
+                    visible: (!checklist.ready || backend.camerasBlockStart) && !backend.sessionActive
+                    opacity: 0.7
+                    text: !checklist.privacyOk ? "Tick the three privacy checks to start."
+                          : backend.camerasBlockStart ? "The headset's cameras aren't all running: see the message at the top." : ""
+                }
+            }
+        }
+    }
+
+    // ---------------------------------------------------------------- Session
+    Component {
+        id: sessionPage
+        Kirigami.Page {
+            id: sessionView
+            title: "Session"
+            readonly property var st: backend.status
+            readonly property string state: st.state || ""
+            readonly property bool waiting: !!st.waiting
+            readonly property bool stepMode: st.mode !== "auto"
+            readonly property var stateText: ({
+                starting: "Starting…", intro: "Get ready", ready: "Get ready", countdown: "Starting",
+                running: "Recording", paused: "Paused", between: "Between sections", done: "Done",
+                stopped: "Stopped", error: "Error", nohands: "No hands seen"
+            })
+
+            // The keys while the window has focus (the panel in the headset lists them too).
+            Shortcut {
+                sequence: "Space"
+                enabled: backend.sessionActive
+                onActivated: backend.nextStep()
+            }
+            Shortcut {
+                sequence: "P"
+                enabled: backend.sessionActive
+                onActivated: backend.togglePause()
+            }
+            Shortcut {
+                sequence: "R"
+                enabled: backend.sessionActive
+                onActivated: backend.redo()
+            }
+            Shortcut {
+                sequence: "S"
+                enabled: backend.sessionActive
+                onActivated: backend.skipSection()
+            }
+            Shortcut {
+                sequence: "Esc"
+                enabled: backend.sessionActive
+                onActivated: backend.stopSession()
+            }
+
+            // A hand chip like the panel's: seen (green), lost (orange) or hidden.
+            component HandChip: Controls.Label {
+                property var seen
+                visible: seen === true || seen === false || seen === "seen" || seen === "lost"
+                readonly property bool ok: seen === true || seen === "seen"
+                padding: Kirigami.Units.smallSpacing
+                leftPadding: Kirigami.Units.largeSpacing
+                rightPadding: Kirigami.Units.largeSpacing
+                color: "white"
+                background: Rectangle {
+                    radius: height / 2
+                    color: parent.ok ? Kirigami.Theme.positiveTextColor : Kirigami.Theme.neutralTextColor
+                }
+            }
+
+            // The pose picture as the panel shows it: a right hand as drawn, a left hand flipped,
+            // both hands as a flipped copy beside it (DESIGN.md "The pose pictures").
+            component PosePicture: Row {
+                property string path
+                property string mode
+                property real side: Kirigami.Units.gridUnit * 9
+                spacing: Kirigami.Units.smallSpacing
+                visible: path !== ""
+                Image {
+                    visible: parent.mode === "both"
+                    width: visible ? parent.side * 0.75 : 0
+                    height: width
+                    source: parent.path ? "file://" + parent.path : ""
+                    fillMode: Image.PreserveAspectFit
+                    mirror: true
+                    smooth: true
+                    mipmap: true
+                }
+                Image {
+                    width: parent.mode === "both" ? parent.side * 0.75 : parent.side
+                    height: width
+                    source: parent.path ? "file://" + parent.path : ""
+                    fillMode: Image.PreserveAspectFit
+                    mirror: parent.mode === "mirror"
+                    smooth: true
+                    mipmap: true
+                }
+            }
+
+            // Where to hold the hands: a front view (left, centre, right, up, down; the push
+            // sections' chest, desk and eye) and how far out (near, mid, far), as on the panel.
+            component WhereDiagram: RowLayout {
+                id: where
+                property string position
+                property string distance
+                readonly property var cell: ({ centre: [1, 1], center: [1, 1], chest: [1, 1], left: [0, 1],
+                                               right: [2, 1], up: [1, 0], eye: [1, 0], down: [1, 2],
+                                               desk: [1, 2] })[position] || null
+                readonly property int step: ["near", "mid", "far"].indexOf(distance)
+                readonly property real unit: Kirigami.Units.gridUnit * 1.1
+                readonly property color accent: "#4cd9ff"
+                spacing: Kirigami.Units.gridUnit
+                visible: cell !== null || step >= 0
+                ColumnLayout {
+                    visible: where.cell !== null
+                    Grid {
+                        Layout.alignment: Qt.AlignHCenter
+                        columns: 3
+                        spacing: 2
+                        Repeater {
+                            model: 9
+                            Rectangle {
+                                required property int index
+                                width: where.unit * 1.33
+                                height: where.unit
+                                radius: 3
+                                readonly property bool on: where.cell !== null && index === where.cell[1] * 3 + where.cell[0]
+                                color: on ? where.accent
+                                          : Qt.rgba(Kirigami.Theme.textColor.r, Kirigami.Theme.textColor.g,
+                                                    Kirigami.Theme.textColor.b, 0.12)
+                            }
+                        }
+                    }
+                    Controls.Label {
+                        Layout.alignment: Qt.AlignHCenter
+                        font: Kirigami.Theme.smallFont
+                        text: ({ left: "To your left", right: "To your right", up: "Up high", down: "Down low",
+                                 chest: "Chest height", desk: "Desk height", eye: "Eye level" })[where.position]
+                              || "In front"
+                    }
+                }
+                ColumnLayout {
+                    visible: where.step >= 0
+                    Row {
+                        Layout.alignment: Qt.AlignHCenter
+                        spacing: where.unit * 0.6
+                        height: where.unit * 1.2
+                        // the head, seen from the side, then the arm's reach
+                        Rectangle {
+                            width: where.unit
+                            height: width
+                            radius: width / 2
+                            anchors.verticalCenter: parent.verticalCenter
+                            color: Qt.rgba(Kirigami.Theme.textColor.r, Kirigami.Theme.textColor.g,
+                                           Kirigami.Theme.textColor.b, 0.6)
+                        }
+                        Repeater {
+                            model: 3
+                            Rectangle {
+                                required property int index
+                                readonly property bool on: index === where.step
+                                width: on ? where.unit * 0.8 : where.unit * 0.35
+                                height: width
+                                radius: width / 2
+                                anchors.verticalCenter: parent.verticalCenter
+                                color: on ? where.accent : Qt.rgba(Kirigami.Theme.textColor.r, Kirigami.Theme.textColor.g,
+                                                                   Kirigami.Theme.textColor.b, 0.35)
+                            }
+                        }
+                    }
+                    Controls.Label {
+                        Layout.alignment: Qt.AlignHCenter
+                        font: Kirigami.Theme.smallFont
+                        text: ["Close: a hand's length", "Halfway out", "Arm stretched out"][Math.max(0, where.step)]
+                    }
+                }
+            }
+
+            header: ColumnLayout {
+                spacing: 0
+                Kirigami.InlineMessage {
+                    Layout.fillWidth: true
+                    visible: backend.runnerError !== "" || (sessionView.state === "error" && sessionView.st.error !== backend.cameraText)
+                    position: Kirigami.InlineMessage.Position.Header
+                    type: Kirigami.MessageType.Error
+                    text: backend.runnerError || ("The session stopped with an error: " + (sessionView.st.error || "unknown"))
+                }
+                // The camera check stopped the session (at its start, or after a step with no hands).
+                CameraMessage {
+                    Layout.fillWidth: true
+                    visible: (!backend.sessionActive && sessionView.state !== "" && backend.cameraText !== "")
+                             || backend.restartingSteamVR
+                }
+            }
+
+            Kirigami.PlaceholderMessage {
+                anchors.centerIn: parent
+                width: parent.width - Kirigami.Units.gridUnit * 4
+                visible: sessionView.state === ""
+                icon.name: "media-record"
+                text: "No session yet"
+                explanation: "Go through Before you start, then press Start there."
+                helpfulAction: Kirigami.Action {
+                    text: "Before you start"; icon.name: "view-task"
+                    onTriggered: root.show(checklistPage)
+                }
+            }
+
+            ColumnLayout {
+                anchors.fill: parent
+                anchors.margins: Kirigami.Units.gridUnit
+                visible: sessionView.state !== ""
+                spacing: Kirigami.Units.largeSpacing
+
+                RowLayout {
+                    Layout.fillWidth: true
+                    Kirigami.Heading {
+                        level: 1
+                        text: sessionView.stateText[sessionView.state] || sessionView.state
+                    }
+                    Item { Layout.fillWidth: true }
+                    Controls.Label {
+                        visible: !!sessionView.st.take && sessionView.state !== "paused"
+                                 && (sessionView.state === "countdown" || sessionView.state === "running"
+                                     || !sessionView.stepMode)
+                        text: "● Recording"
+                        color: Kirigami.Theme.negativeTextColor
+                    }
+                }
+                Controls.Label {
+                    visible: (sessionView.st.section_index || 0) > 0
+                    text: "Section " + sessionView.st.section_index + " of " + sessionView.st.section_count
+                          + (sessionView.st.title ? ": " + sessionView.st.title : "")
+                          + ((sessionView.st.step_index || 0) > 0 && sessionView.stepMode
+                             ? " · step " + sessionView.st.step_index + " of " + sessionView.st.step_count : "")
+                    font.bold: true
+                }
+
+                RowLayout {
+                    Layout.fillWidth: true
+                    spacing: Kirigami.Units.gridUnit * 1.5
+
+                    ColumnLayout {
+                        visible: !!sessionView.st.image || !!sessionView.st.position || !!sessionView.st.distance
+                        spacing: Kirigami.Units.largeSpacing
+                        PosePicture {
+                            Layout.alignment: Qt.AlignHCenter
+                            path: sessionView.st.image || ""
+                            mode: sessionView.st.image_mode || ""
+                        }
+                        Controls.Label {
+                            Layout.alignment: Qt.AlignHCenter
+                            Layout.maximumWidth: Kirigami.Units.gridUnit * 14
+                            visible: !!sessionView.st.image && !!sessionView.st.caption
+                            wrapMode: Text.Wrap
+                            horizontalAlignment: Text.AlignHCenter
+                            opacity: 0.7
+                            font: Kirigami.Theme.smallFont
+                            text: sessionView.st.caption || ""
+                        }
+                        WhereDiagram {
+                            id: where
+                            Layout.alignment: Qt.AlignHCenter
+                            position: sessionView.st.position || ""
+                            distance: sessionView.st.distance || ""
+                        }
+                    }
+
+                    ColumnLayout {
+                        Layout.fillWidth: true
+                        spacing: Kirigami.Units.largeSpacing
+                        Controls.Label {
+                            Layout.fillWidth: true
+                            visible: !!sessionView.st.prompt
+                            wrapMode: Text.Wrap
+                            font.pointSize: Kirigami.Theme.defaultFont.pointSize * 1.4
+                            text: sessionView.st.prompt || ""
+                        }
+                        // A sweep's row of pictures, the lit one framed, as on the panel
+                        Row {
+                            visible: (sessionView.st.strip || []).length > 0
+                            spacing: Kirigami.Units.largeSpacing
+                            Repeater {
+                                model: sessionView.st.strip || []
+                                Column {
+                                    required property var modelData
+                                    required property int index
+                                    readonly property bool lit: index === sessionView.st.cue
+                                    spacing: Kirigami.Units.smallSpacing
+                                    Rectangle {
+                                        width: Kirigami.Units.gridUnit * 5.5
+                                        height: width
+                                        radius: Kirigami.Units.smallSpacing * 2
+                                        color: Qt.rgba(Kirigami.Theme.textColor.r, Kirigami.Theme.textColor.g,
+                                                       Kirigami.Theme.textColor.b, 0.06)
+                                        border.width: parent.lit ? 3 : 0
+                                        border.color: "#4cd9ff"
+                                        Image {
+                                            anchors.fill: parent
+                                            anchors.margins: 4
+                                            source: modelData.image ? "file://" + modelData.image : ""
+                                            fillMode: Image.PreserveAspectFit
+                                            mirror: modelData.mode === "mirror"
+                                            opacity: parent.parent.lit ? 1 : 0.4
+                                            smooth: true
+                                            mipmap: true
+                                        }
+                                    }
+                                    Controls.Label {
+                                        anchors.horizontalCenter: parent.horizontalCenter
+                                        text: modelData.label || ""
+                                        color: parent.lit ? "#4cd9ff" : Kirigami.Theme.textColor
+                                        opacity: parent.lit ? 1 : 0.6
+                                    }
+                                }
+                            }
+                        }
+                        // The countdown's 3, 2, 1, then the hold's word, big
+                        Controls.Label {
+                            visible: !!sessionView.st.big && sessionView.state !== "paused"
+                            text: sessionView.st.big || ""
+                            font.pointSize: Kirigami.Theme.defaultFont.pointSize * 4
+                            font.bold: true
+                            color: Kirigami.Theme.highlightColor
+                        }
+                        Controls.Label {
+                            visible: !sessionView.waiting && sessionView.state !== "countdown"
+                                     && sessionView.state !== "ready" && sessionView.st.seconds_left !== undefined
+                                     && sessionView.st.seconds_left !== null && sessionView.st.seconds_left > 0
+                            text: Math.ceil(sessionView.st.seconds_left || 0) + " s left"
+                            opacity: 0.7
+                        }
+                        Controls.Button {
+                            visible: sessionView.waiting && sessionView.state !== "paused"
+                            focusPolicy: Qt.NoFocus
+                            text: sessionView.state === "nohands" ? "Try again" : "Next"
+                            icon.name: sessionView.state === "nohands" ? "edit-undo" : "go-next"
+                            font.pointSize: Kirigami.Theme.defaultFont.pointSize * 1.5
+                            Layout.preferredWidth: Kirigami.Units.gridUnit * 10
+                            Layout.preferredHeight: Kirigami.Units.gridUnit * 3
+                            onClicked: backend.nextStep()
+                        }
+                        Controls.Label {
+                            visible: sessionView.waiting && sessionView.state !== "paused"
+                            opacity: 0.7
+                            text: sessionView.state === "nohands"
+                                  ? "Try again starts the same step (Space or the headset button do too). Stop ends the session, "
+                                    + "keeping what's recorded."
+                                  : (sessionView.st.ready_text || "Ready? Press Space or click Next")
+                                    + ". A 3-2-1 countdown starts the recording."
+                            wrapMode: Text.Wrap
+                            Layout.fillWidth: true
+                        }
+                    }
+                }
+
+                Kirigami.InlineMessage {
+                    Layout.fillWidth: true
+                    visible: !!sessionView.st.note
+                    // (A hidden InlineMessage keeps its height in a layout.)
+                    Layout.preferredHeight: visible ? implicitHeight : 0
+                    type: Kirigami.MessageType.Warning
+                    text: sessionView.st.note || ""
+                }
+                RowLayout {
+                    spacing: Kirigami.Units.largeSpacing
+                    HandChip { text: "Left hand"; seen: sessionView.st.hands ? sessionView.st.hands.left : undefined }
+                    HandChip { text: "Right hand"; seen: sessionView.st.hands ? sessionView.st.hands.right : undefined }
+                }
+                Controls.Label {
+                    visible: !!sessionView.st.take
+                    text: "Take " + (sessionView.st.take || "")
+                    opacity: 0.7
+                    font: Kirigami.Theme.smallFont
+                }
+
+                Item { Layout.fillHeight: true }
+
+                Controls.Label {
+                    Layout.fillWidth: true
+                    wrapMode: Text.Wrap
+                    opacity: 0.7
+                    text: "The instructions appear in the headset. "
+                          + (sessionView.st.button ? "The button on the right side of the headset: "
+                             + (sessionView.stepMode ? "next, " : "") + "pause or resume. " : "")
+                          + "While this window has focus: "
+                          + (sessionView.stepMode ? "Space: next · " : "")
+                          + "P: pause or resume · R: record the last step again · S: skip section · Esc: stop. "
+                          + "Stopping keeps what's recorded so far."
+                }
+                RowLayout {
+                    // No keyboard focus on the buttons, so Space always reaches the shortcut.
+                    Controls.Button {
+                        visible: !backend.sessionActive
+                        focusPolicy: Qt.NoFocus
+                        text: "New session…"
+                        icon.name: "media-record"
+                        onClicked: root.show(checklistPage)
+                    }
+                    Controls.Button {
+                        visible: backend.sessionActive
+                        focusPolicy: Qt.NoFocus
+                        text: sessionView.state === "paused" ? "Resume" : "Pause"
+                        icon.name: sessionView.state === "paused" ? "media-playback-start" : "media-playback-pause"
+                        onClicked: backend.togglePause()
+                    }
+                    Controls.Button {
+                        visible: backend.sessionActive
+                        enabled: !!sessionView.st.can_redo
+                        focusPolicy: Qt.NoFocus
+                        text: "Redo step"
+                        icon.name: "edit-undo"
+                        onClicked: backend.redo()
+                    }
+                    Controls.Button {
+                        visible: backend.sessionActive
+                        focusPolicy: Qt.NoFocus
+                        text: "Skip section"
+                        icon.name: "media-skip-forward"
+                        onClicked: backend.skipSection()
+                    }
+                    Controls.Button {
+                        visible: backend.sessionActive
+                        focusPolicy: Qt.NoFocus
+                        text: "Stop"
+                        icon.name: "media-playback-stop"
+                        onClicked: backend.stopSession()
+                    }
+                    Controls.Button {
+                        visible: !backend.sessionActive && backend.sessionId !== ""
+                        focusPolicy: Qt.NoFocus
+                        text: "Review this session"
+                        icon.name: "view-preview"
+                        onClicked: {
+                            root.show(reviewPage)
+                            pageStack.push(takesPage, { session: backend.sessionId })
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    // ---------------------------------------------------------------- Review
+    Component {
+        id: reviewPage
+        Kirigami.ScrollablePage {
+            title: "Review"
+            actions: [
+                Kirigami.Action { text: "Refresh"; icon.name: "view-refresh"; onTriggered: backend.refreshSessions() }
+            ]
+
+            ListView {
+                model: backend.sessions
+                spacing: Kirigami.Units.smallSpacing
+
+                Kirigami.PlaceholderMessage {
+                    anchors.centerIn: parent
+                    width: parent.width - Kirigami.Units.gridUnit * 4
+                    visible: parent.count === 0
+                    text: "No sessions yet"
+                    explanation: "Recorded sessions appear here, to watch and trim before you export them."
+                }
+
+                delegate: Controls.ItemDelegate {
+                    id: sessionRow
+                    required property var modelData
+                    width: ListView.view.width
+                    onClicked: pageStack.push(takesPage, { session: modelData.id })
+
+                    contentItem: RowLayout {
+                        spacing: Kirigami.Units.largeSpacing
+                        Kirigami.Icon {
+                            source: sessionRow.modelData.active ? "media-record" : "folder-videos"
+                            implicitWidth: Kirigami.Units.iconSizes.medium
+                            implicitHeight: implicitWidth
+                        }
+                        ColumnLayout {
+                            Layout.fillWidth: true
+                            spacing: 0
+                            Controls.Label {
+                                text: sessionRow.modelData.label + (sessionRow.modelData.active ? " (recording)" : "")
+                                      + (sessionRow.modelData.dry_run ? " (dry run)" : "")
+                                font.bold: true
+                            }
+                            Controls.Label {
+                                Layout.fillWidth: true
+                                elide: Text.ElideRight
+                                opacity: 0.7
+                                font: Kirigami.Theme.smallFont
+                                text: root.plural(sessionRow.modelData.takes, "take") + " · " + sessionRow.modelData.sizeText
+                                      + (sessionRow.modelData.statusText ? " · " + sessionRow.modelData.statusText : "")
+                                      + (sessionRow.modelData.lightingText ? " · " + sessionRow.modelData.lightingText : "")
+                                      + (sessionRow.modelData.export_stale ? " · changed since its export"
+                                         : sessionRow.modelData.exported ? " · exported (" + sessionRow.modelData.exportText + ")" : "")
+                            }
+                        }
+                        Controls.ToolButton {
+                            icon.name: "edit-delete"
+                            text: "Delete session"
+                            display: Controls.AbstractButton.IconOnly
+                            enabled: !sessionRow.modelData.active
+                            Controls.ToolTip.text: text
+                            Controls.ToolTip.visible: hovered
+                            onClicked: {
+                                const sid = sessionRow.modelData.id
+                                confirm.ask("Delete this session?",
+                                            "The session of " + sessionRow.modelData.label + " (" + root.plural(sessionRow.modelData.takes, "take")
+                                            + ", " + sessionRow.modelData.sizeText + ") and its export are deleted from the "
+                                            + "headset for good.",
+                                            () => { pageStack.pop(pageStack.items[0]); backend.deleteSession(sid) })
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    Component {
+        id: takesPage
+        Kirigami.ScrollablePage {
+            id: takesView
+            property string session: ""
+            property var rows: backend.takeList(session)
+            title: "Takes"
+
+            Connections {
+                target: backend
+                function onSessionsChanged() { takesView.rows = backend.takeList(takesView.session) }
+            }
+
+            ListView {
+                model: takesView.rows
+                spacing: Kirigami.Units.smallSpacing
+
+                Kirigami.PlaceholderMessage {
+                    anchors.centerIn: parent
+                    width: parent.width - Kirigami.Units.gridUnit * 4
+                    visible: parent.count === 0
+                    text: "No takes in this session"
+                }
+
+                delegate: Controls.ItemDelegate {
+                    id: takeRow
+                    required property var modelData
+                    width: ListView.view.width
+                    onClicked: pageStack.push(viewerPage, { session: takesView.session, take: modelData.id })
+
+                    contentItem: RowLayout {
+                        spacing: Kirigami.Units.largeSpacing
+                        Image {
+                            Layout.preferredWidth: Kirigami.Units.gridUnit * 5
+                            Layout.preferredHeight: Kirigami.Units.gridUnit * 4.5
+                            fillMode: Image.PreserveAspectFit
+                            asynchronous: true
+                            source: takeRow.modelData.sets > 0
+                                    ? "image://frames/thumb/" + takesView.session + "/" + takeRow.modelData.id : ""
+                        }
+                        ColumnLayout {
+                            Layout.fillWidth: true
+                            spacing: 0
+                            Controls.Label { text: takeRow.modelData.title; font.bold: true }
+                            Controls.Label {
+                                Layout.fillWidth: true
+                                elide: Text.ElideRight
+                                opacity: 0.7
+                                font: Kirigami.Theme.smallFont
+                                text: takeRow.modelData.status + " · " + takeRow.modelData.durationText + " · "
+                                      + takeRow.modelData.sets + " sets"
+                                      + (takeRow.modelData.deleted_sets ? " (" + takeRow.modelData.deleted_sets + " deleted)" : "")
+                                      + " · " + takeRow.modelData.sizeText
+                            }
+                        }
+                        Controls.ToolButton {
+                            icon.name: "edit-delete"
+                            text: "Delete take"
+                            display: Controls.AbstractButton.IconOnly
+                            Controls.ToolTip.text: text
+                            Controls.ToolTip.visible: hovered
+                            onClicked: {
+                                const take = takeRow.modelData.id
+                                confirm.ask("Delete this take?",
+                                            "\"" + takeRow.modelData.title + "\" (" + takeRow.modelData.durationText
+                                            + ") is deleted from the headset for good.",
+                                            () => { pageStack.pop(takesView); backend.deleteTake(takesView.session, take) })
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    Component {
+        id: viewerPage
+        Kirigami.Page {
+            id: viewer
+            property string session: ""
+            property string take: ""
+            property var info: backend.takeInfo(session, take)
+            property int index: 0
+            property int markStart: -1
+            property int markEnd: -1
+            title: info.title
+            readonly property bool deletedHere: isDeleted(index)
+
+            function step(n) {
+                index = Math.max(0, Math.min(info.count - 1, index + n))
+            }
+            function isDeleted(i) {
+                for (const r of info.ranges)
+                    if (i >= r[0] && i <= r[1] && r[0] >= 0)
+                        return true
+                return false
+            }
+            function deleteMarked() {
+                backend.deleteRange(session, take, markStart, markEnd)
+                markStart = markEnd = -1
+                info = backend.takeInfo(session, take)
+            }
+
+            Connections {
+                target: backend
+                function onSessionsChanged() { viewer.info = backend.takeInfo(viewer.session, viewer.take) }
+            }
+
+            // Keyboard stepping: arrows one set, Page Up/Down ten, Home/End, [ and ] mark a range,
+            // Delete deletes it.
+            Item {
+                id: keys
+                focus: true
+                Component.onCompleted: forceActiveFocus()
+                Keys.onPressed: event => {
+                    const k = event.key
+                    if (k === Qt.Key_Left) viewer.step(-1)
+                    else if (k === Qt.Key_Right) viewer.step(1)
+                    else if (k === Qt.Key_PageUp) viewer.step(-10)
+                    else if (k === Qt.Key_PageDown) viewer.step(10)
+                    else if (k === Qt.Key_Home) viewer.index = 0
+                    else if (k === Qt.Key_End) viewer.index = Math.max(0, viewer.info.count - 1)
+                    else if (k === Qt.Key_BracketLeft) viewer.markStart = viewer.index
+                    else if (k === Qt.Key_BracketRight) viewer.markEnd = viewer.index
+                    else if (k === Qt.Key_Delete && viewer.markStart >= 0 && viewer.markEnd >= 0) viewer.deleteMarked()
+                    else return
+                    event.accepted = true
+                }
+            }
+
+            Kirigami.PlaceholderMessage {
+                anchors.centerIn: parent
+                visible: viewer.info.count === 0
+                text: "This take has no frame sets"
+            }
+
+            ColumnLayout {
+                anchors.fill: parent
+                visible: viewer.info.count > 0
+                spacing: Kirigami.Units.smallSpacing
+
+                Image {
+                    id: frame
+                    Layout.fillWidth: true
+                    Layout.fillHeight: true
+                    fillMode: Image.PreserveAspectFit
+                    asynchronous: true
+                    cache: false
+                    retainWhileLoading: true
+                    source: viewer.info.count > 0
+                            ? "image://frames/set/" + viewer.session + "/" + viewer.take + "/" + viewer.index : ""
+                    MouseArea { anchors.fill: parent; onClicked: keys.forceActiveFocus() }
+
+                    Rectangle {
+                        visible: viewer.deletedHere
+                        x: (frame.width - frame.paintedWidth) / 2
+                        y: (frame.height - frame.paintedHeight) / 2
+                        width: frame.paintedWidth
+                        height: frame.paintedHeight
+                        color: Qt.rgba(0.8, 0, 0, 0.35)
+                        Controls.Label {
+                            anchors.centerIn: parent
+                            text: "Deleted: not exported"
+                            color: "white"
+                            font.bold: true
+                        }
+                    }
+                }
+
+                // The slider, with the deleted ranges (red) and the marked range (blue) under it.
+                Item {
+                    Layout.fillWidth: true
+                    implicitHeight: slider.implicitHeight
+                    Repeater {
+                        model: viewer.info.ranges
+                        Rectangle {
+                            required property var modelData
+                            visible: modelData[0] >= 0
+                            readonly property real unit: (slider.availableWidth) / Math.max(1, viewer.info.count - 1)
+                            x: slider.leftPadding + modelData[0] * unit - 2
+                            width: Math.max(4, (modelData[1] - modelData[0]) * unit + 4)
+                            y: slider.topPadding + slider.availableHeight / 2 + 4
+                            height: 4
+                            color: Kirigami.Theme.negativeTextColor
+                        }
+                    }
+                    Rectangle {
+                        visible: viewer.markStart >= 0
+                        readonly property int last: viewer.markEnd >= 0 ? viewer.markEnd : viewer.index
+                        readonly property real unit: (slider.availableWidth) / Math.max(1, viewer.info.count - 1)
+                        x: slider.leftPadding + Math.min(viewer.markStart, last) * unit - 2
+                        width: Math.abs(last - viewer.markStart) * unit + 4
+                        y: slider.topPadding + slider.availableHeight / 2 - 8
+                        height: 4
+                        color: Kirigami.Theme.highlightColor
+                    }
+                    Controls.Slider {
+                        id: slider
+                        anchors.left: parent.left
+                        anchors.right: parent.right
+                        focusPolicy: Qt.NoFocus
+                        from: 0
+                        to: Math.max(0, viewer.info.count - 1)
+                        stepSize: 1
+                        snapMode: Controls.Slider.SnapAlways
+                        value: viewer.index
+                        onMoved: viewer.index = Math.round(value)
+                    }
+                }
+
+                RowLayout {
+                    Layout.fillWidth: true
+                    Controls.Label {
+                        text: "Set " + (viewer.index + 1) + " of " + viewer.info.count + " · "
+                              + backend.setTime(viewer.session, viewer.take, viewer.index)
+                    }
+                    Item { Layout.fillWidth: true }
+                    Controls.Button {
+                        focusPolicy: Qt.NoFocus
+                        text: viewer.markStart >= 0 ? "Start: " + (viewer.markStart + 1) : "Mark start"
+                        icon.name: "go-first"
+                        onClicked: viewer.markStart = viewer.index
+                    }
+                    Controls.Button {
+                        focusPolicy: Qt.NoFocus
+                        text: viewer.markEnd >= 0 ? "End: " + (viewer.markEnd + 1) : "Mark end"
+                        icon.name: "go-last"
+                        onClicked: viewer.markEnd = viewer.index
+                    }
+                    Controls.Button {
+                        focusPolicy: Qt.NoFocus
+                        enabled: viewer.markStart >= 0 && viewer.markEnd >= 0
+                        text: "Delete range"
+                        icon.name: "edit-cut"
+                        onClicked: viewer.deleteMarked()
+                    }
+                    Controls.Button {
+                        focusPolicy: Qt.NoFocus
+                        visible: viewer.markStart >= 0 || viewer.markEnd >= 0
+                        text: "Clear marks"
+                        icon.name: "edit-clear"
+                        onClicked: viewer.markStart = viewer.markEnd = -1
+                    }
+                }
+
+                Flow {
+                    Layout.fillWidth: true
+                    spacing: Kirigami.Units.smallSpacing
+                    visible: viewer.info.ranges.length > 0
+                    Controls.Label { text: "Deleted:"; topPadding: Kirigami.Units.smallSpacing }
+                    Repeater {
+                        model: viewer.info.ranges
+                        Controls.Button {
+                            required property var modelData
+                            required property int index
+                            focusPolicy: Qt.NoFocus
+                            flat: true
+                            text: (modelData[0] < 0 ? "a range with no sets"
+                                   : "sets " + (modelData[0] + 1) + " to " + (modelData[1] + 1)) + ": restore"
+                            icon.name: "edit-undo"
+                            onClicked: backend.restoreRange(viewer.session, viewer.take, index)
+                        }
+                    }
+                }
+
+                Controls.Label {
+                    Layout.fillWidth: true
+                    wrapMode: Text.Wrap
+                    opacity: 0.7
+                    font: Kirigami.Theme.smallFont
+                    text: "← → step one set, Page Up/Down ten, Home/End. [ and ] mark a range's start and end, "
+                          + "Delete deletes it. Deleted sets stay on the headset until export, which leaves them out."
+                }
+            }
+        }
+    }
+
+    // ---------------------------------------------------------------- Export
+    Component {
+        id: exportPage
+        Kirigami.ScrollablePage {
+            id: exportView
+            title: "Export"
+            property bool worn: backend.headsetWorn()
+            readonly property var chosen: {
+                const list = backend.sessions
+                for (const s of list)
+                    if (s.id === sessionBox.currentValue)
+                        return s
+                return null
+            }
+
+            Timer {
+                interval: 5000
+                running: true
+                repeat: true
+                onTriggered: exportView.worn = backend.headsetWorn()
+            }
+
+            header: ColumnLayout {
+                spacing: 0
+                DraftBanner { Layout.fillWidth: true }
+                Kirigami.InlineMessage {
+                    Layout.fillWidth: true
+                    visible: exportView.worn && backend.exporting
+                    position: Kirigami.InlineMessage.Position.Header
+                    type: Kirigami.MessageType.Information
+                    text: "Exporting keeps the processor busy for a few minutes, so VR may stutter a little until "
+                          + "it's done. You can keep using the headset meanwhile."
+                }
+                Kirigami.InlineMessage {
+                    Layout.fillWidth: true
+                    visible: !backend.zstdFound
+                    position: Kirigami.InlineMessage.Position.Header
+                    type: Kirigami.MessageType.Error
+                    text: "zstd isn't installed in the dev container, so nothing can be exported. Run setup/dev-container.sh."
+                }
+            }
+
+            Kirigami.FormLayout {
+                Controls.ComboBox {
+                    id: sessionBox
+                    Kirigami.FormData.label: "Session:"
+                    model: backend.sessions
+                    textRole: "label"
+                    valueRole: "id"
+                    enabled: !backend.exporting
+                    Component.onCompleted: {
+                        const i = indexOfValue(root.chosenSession)
+                        currentIndex = i >= 0 ? i : (count > 0 ? 0 : -1)
+                    }
+                    onActivated: root.chosenSession = currentValue
+                }
+                Controls.Label {
+                    Kirigami.FormData.label: "Recorded:"
+                    visible: exportView.chosen !== null
+                    text: exportView.chosen ? root.plural(exportView.chosen.takes, "take") + ", " + exportView.chosen.sizeText : ""
+                }
+                Controls.Label {
+                    Kirigami.FormData.label: "Export:"
+                    visible: exportView.chosen !== null
+                    text: !exportView.chosen ? ""
+                          : exportView.chosen.export_stale ? "changed since it was exported: export it again"
+                          : exportView.chosen.exported ? "ready, " + exportView.chosen.exportText : "not exported yet"
+                }
+                RowLayout {
+                    Controls.Button {
+                        text: backend.exporting ? "Exporting…"
+                              : exportView.chosen && exportView.chosen.exported ? "Export again" : "Export"
+                        icon.name: "document-export"
+                        enabled: exportView.chosen !== null && !backend.exporting && backend.zstdFound
+                                 && !exportView.chosen.active
+                        onClicked: backend.exportSession(exportView.chosen.id, false)
+                    }
+                    // Shows the moment Export is pressed: the first progress can take a few seconds.
+                    Controls.BusyIndicator {
+                        visible: backend.exporting
+                        running: visible
+                        implicitWidth: Kirigami.Units.gridUnit * 1.5
+                        implicitHeight: implicitWidth
+                    }
+                    Controls.Button {
+                        visible: backend.exporting
+                        text: "Cancel"
+                        icon.name: "dialog-cancel"
+                        onClicked: backend.cancelExport()
+                    }
+                }
+                // Drawn here: the desktop style's ProgressBar paints nothing without a QApplication.
+                Rectangle {
+                    Kirigami.FormData.label: "Progress:"
+                    Layout.preferredWidth: Kirigami.Units.gridUnit * 20
+                    implicitHeight: Kirigami.Units.smallSpacing * 2
+                    visible: backend.exporting
+                    radius: height / 2
+                    color: Qt.rgba(Kirigami.Theme.textColor.r, Kirigami.Theme.textColor.g, Kirigami.Theme.textColor.b, 0.15)
+                    Rectangle {
+                        width: parent.width * Math.max(0, Math.min(1, backend.exportFraction))
+                        height: parent.height
+                        radius: parent.radius
+                        color: Kirigami.Theme.highlightColor
+                    }
+                }
+                Controls.Label {
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    visible: backend.exportText !== "" && (backend.exporting || backend.exportSessionId === sessionBox.currentValue)
+                    wrapMode: Text.WrapAnywhere
+                    text: backend.exportText
+                }
+                RowLayout {
+                    visible: exportView.chosen !== null && exportView.chosen.exported && !backend.exporting
+                    Controls.Button {
+                        text: "Upload"
+                        icon.name: "go-next"
+                        onClicked: root.show(uploadPage)
+                    }
+                    Controls.Button {
+                        text: "Delete export"
+                        icon.name: "edit-delete"
+                        onClicked: {
+                            const sid = exportView.chosen.id
+                            confirm.ask("Delete this export?", "The export is deleted; the session's recordings stay.",
+                                        () => backend.deleteExport(sid))
+                        }
+                    }
+                }
+            }
+
+            footer: Controls.Label {
+                padding: Kirigami.Units.largeSpacing
+                wrapMode: Text.Wrap
+                opacity: 0.7
+                text: "Export leaves out the ranges you deleted, compresses the rest and adds a manifest and "
+                      + "checksums, in " + backend.exportsDir + ". It runs at the lowest priority "
+                      + "and takes a few minutes per round; the headset stays awake until it's done. Nothing is "
+                      + "uploaded until you press Upload on the Upload page."
+            }
+        }
+    }
+
+    // ---------------------------------------------------------------- Upload
+    Component {
+        id: uploadPage
+        Kirigami.ScrollablePage {
+            id: uploadView
+            title: "Upload"
+            readonly property var exported: backend.sessions.filter(s => s.exported)
+            readonly property string session: exportBox.currentIndex >= 0 ? exportBox.currentValue || "" : ""
+            readonly property var chosen: exportBox.currentIndex >= 0 && exportBox.currentIndex < exported.length
+                                          ? exported[exportBox.currentIndex] : null
+            readonly property var up: backend.upload
+            readonly property var upError: up.error || ({})
+            readonly property var upResult: up.result || ({})
+            // The upload shown is this export's (the window keeps the last one's result).
+            readonly property bool mine: up.session === session
+            property var info: ({ previous: {}, uploads: 0 })
+            readonly property bool loggedIn: backend.login.state === "ok"
+            // Why Upload is off, or "" when it can go.
+            readonly property string blocked: {
+                if (session === "") return "Choose an export"
+                if (chosen && chosen.export_stale) return "Export the session again first"
+                if (backend.exporting) return "Wait for the export to finish"
+                if (backend.uploading) return ""
+                if (backend.hubDryRun) return ""
+                if (!backend.uploadAllowed) return "Contributions aren't open yet"
+                if (!loggedIn) return "Log in first (step 2)"
+                return ""
+            }
+
+            function refreshInfo() { info = backend.uploadInfo(session) }
+            onSessionChanged: refreshInfo()
+            Connections {
+                target: backend
+                function onSessionsChanged() { uploadView.refreshInfo() }
+            }
+            Component.onCompleted: {
+                refreshInfo()
+                if (backend.login.state === "unknown") backend.checkLogin()
+            }
+
+            function startUpload() {
+                if (info.previous && info.previous.export_sha)
+                    confirm.ask("Upload this export again?",
+                                "It was uploaded on " + info.previous.uploaded + " (" + (info.previous.pr_url || "no link")
+                                + "). Uploading it again opens a second pull request.",
+                                () => backend.startUpload(uploadView.session, true))
+                else
+                    backend.startUpload(session, false)
+            }
+
+            header: ColumnLayout {
+                spacing: 0
+                DraftBanner { Layout.fillWidth: true }
+                Kirigami.InlineMessage {
+                    Layout.fillWidth: true
+                    visible: backend.hubDryRun
+                    position: Kirigami.InlineMessage.Position.Header
+                    type: Kirigami.MessageType.Information
+                    text: "Dry run (--hub-dry-run): Upload checks the export and lists what it would send. "
+                          + "Nothing goes over the network."
+                }
+                Kirigami.InlineMessage {
+                    Layout.fillWidth: true
+                    visible: backend.textsDraft && backend.allowUploadSet && !backend.hubDryRun
+                    position: Kirigami.InlineMessage.Position.Header
+                    type: Kirigami.MessageType.Warning
+                    text: "Rehearsal: FT_HANDREC_ALLOW_UPLOAD=1 allows uploads to " + backend.dataset
+                          + " while the texts are drafts."
+                }
+            }
+
+            ColumnLayout {
+                spacing: Kirigami.Units.largeSpacing
+
+                Kirigami.PlaceholderMessage {
+                    Layout.fillWidth: true
+                    visible: uploadView.exported.length === 0
+                    icon.name: "document-export"
+                    text: "Nothing exported yet"
+                    explanation: "Review a session, then export it. It can be uploaded from here."
+                    helpfulAction: Kirigami.Action {
+                        text: "Export"; icon.name: "document-export"
+                        onTriggered: root.show(exportPage)
+                    }
+                }
+
+                ColumnLayout {
+                    Layout.fillWidth: true
+                    visible: uploadView.exported.length > 0
+                    spacing: Kirigami.Units.largeSpacing
+
+                    Controls.Label {
+                        Layout.fillWidth: true
+                        wrapMode: Text.Wrap
+                        textFormat: Text.StyledText
+                        text: "Your export goes to <a href=\"" + backend.datasetUrl + "\">" + backend.dataset + "</a> as a "
+                              + "pull request from your own Hugging Face account. Nothing is published until the "
+                              + "maintainer has checked it."
+                        onLinkActivated: link => Qt.openUrlExternally(link)
+                    }
+
+                    // 1. The export
+                    Kirigami.Heading { level: 3; text: "1. Choose the export" }
+                    RowLayout {
+                        Layout.fillWidth: true
+                        Controls.ComboBox {
+                            id: exportBox
+                            Layout.fillWidth: true
+                            Layout.maximumWidth: Kirigami.Units.gridUnit * 22
+                            model: uploadView.exported
+                            textRole: "label"
+                            valueRole: "id"
+                            enabled: !backend.uploading
+                            Component.onCompleted: currentIndex = Math.max(0, indexOfValue(root.chosenSession))
+                            onActivated: root.chosenSession = currentValue
+                        }
+                        Controls.Label {
+                            opacity: 0.7
+                            text: uploadView.chosen ? uploadView.chosen.exportText : ""
+                        }
+                    }
+                    Kirigami.InlineMessage {
+                        Layout.fillWidth: true
+                        visible: uploadView.chosen !== null && uploadView.chosen.export_stale
+                        type: Kirigami.MessageType.Warning
+                        text: "This session changed since it was exported. Export it again so the upload has your latest deletions."
+                    }
+                    Kirigami.InlineMessage {
+                        Layout.fillWidth: true
+                        visible: uploadView.session !== "" && uploadView.info.previous.export_sha !== undefined
+                        type: Kirigami.MessageType.Information
+                        text: "This export was uploaded on " + (uploadView.info.previous.uploaded || "") + ": "
+                              + (uploadView.info.previous.pr_url || "") + ". There's no need to upload it again."
+                    }
+
+                    // 2. The login: Log in opens Hugging Face in the browser, where the person approves
+                    // it. The token goes from there to hub.py, never into this window.
+                    Kirigami.Heading { level: 3; text: "2. Log in to Hugging Face" }
+                    RowLayout {
+                        Layout.fillWidth: true
+                        visible: loginState !== "waiting"
+                        readonly property string loginState: backend.login.state
+                        Kirigami.Icon {
+                            visible: parent.loginState === "ok"
+                            source: "checkmark"
+                            implicitWidth: Kirigami.Units.iconSizes.small
+                            implicitHeight: implicitWidth
+                        }
+                        Controls.BusyIndicator {
+                            visible: ["checking", "starting", "unknown"].indexOf(parent.loginState) >= 0
+                            running: visible
+                            implicitWidth: Kirigami.Units.gridUnit * 1.5
+                            implicitHeight: implicitWidth
+                        }
+                        Controls.Label {
+                            Layout.fillWidth: true
+                            visible: parent.loginState !== "waiting"
+                            wrapMode: Text.Wrap
+                            text: parent.loginState === "dry" ? "Not needed for a dry run."
+                                  : parent.loginState === "unknown" ? "Checking your login"
+                                  : parent.loginState === "none"
+                                    ? "Press Log in. Hugging Face opens in your browser: sign in, or make a free "
+                                      + "account, then enter the code this page shows."
+                                  : backend.login.text || ""
+                        }
+                        Controls.Button {
+                            visible: ["none", "read", "error", "ok"].indexOf(parent.loginState) >= 0
+                            text: parent.loginState === "ok" ? "Use another account" : "Log in"
+                            icon.name: parent.loginState === "ok" ? "system-switch-user" : "im-user-online"
+                            flat: parent.loginState === "ok"
+                            enabled: !backend.uploading
+                            onClicked: backend.logIn()
+                        }
+                        Controls.Button {
+                            visible: parent.loginState === "error"
+                            text: "Check again"
+                            icon.name: "view-refresh"
+                            onClicked: backend.checkLogin()
+                        }
+                    }
+                    Kirigami.InlineMessage {
+                        Layout.fillWidth: true
+                        visible: backend.login.state === "waiting"
+                        type: Kirigami.MessageType.Information
+                        text: "Hugging Face is open in your browser (" + (backend.login.url || "") + "). Sign in, or "
+                              + "make a free account, enter the code below and approve the login. If it asks about "
+                              + "organizations, leave them unticked. The code works for "
+                              + Math.round((backend.login.expires_in || 300) / 60) + " minutes; this page carries on "
+                              + "by itself once you've approved."
+                        actions: [openLogin, copyLogin, cancelLogin]
+                        Kirigami.Action {
+                            id: openLogin
+                            text: "Open again"
+                            icon.name: "internet-services"
+                            onTriggered: Qt.openUrlExternally(backend.login.url)
+                        }
+                        Kirigami.Action {
+                            id: copyLogin
+                            text: "Copy code"
+                            icon.name: "edit-copy"
+                            onTriggered: backend.copy(backend.login.code)
+                        }
+                        Kirigami.Action {
+                            id: cancelLogin
+                            text: "Cancel"
+                            icon.name: "dialog-cancel"
+                            onTriggered: backend.cancelLogin()
+                        }
+                    }
+                    Controls.Label {
+                        visible: backend.login.state === "waiting"
+                        Layout.leftMargin: Kirigami.Units.gridUnit
+                        text: backend.login.code || ""
+                        font.family: "monospace"
+                        font.pointSize: Kirigami.Theme.defaultFont.pointSize * 2.5
+                        font.letterSpacing: 4
+                    }
+
+                    // 3. The upload
+                    Kirigami.Heading { level: 3; text: "3. Upload" }
+                    Controls.Label {
+                        Layout.fillWidth: true
+                        wrapMode: Text.Wrap
+                        textFormat: Text.StyledText
+                        text: "The first time, accept the dataset's terms on <a href=\"" + backend.datasetUrl
+                              + "\">its page</a>. Upload checks the export, opens your pull request, then sends the files."
+                        onLinkActivated: link => Qt.openUrlExternally(link)
+                    }
+                    RowLayout {
+                        Controls.Button {
+                            text: backend.uploading ? "Uploading…" : backend.hubDryRun ? "Upload (dry run)" : "Upload"
+                            icon.name: "cloud-upload"
+                            enabled: uploadView.blocked === "" && !backend.uploading
+                            onClicked: uploadView.startUpload()
+                        }
+                        Controls.BusyIndicator {
+                            visible: backend.uploading
+                            running: visible
+                            implicitWidth: Kirigami.Units.gridUnit * 1.5
+                            implicitHeight: implicitWidth
+                        }
+                        Controls.Button {
+                            visible: backend.uploading
+                            text: "Cancel"
+                            icon.name: "dialog-cancel"
+                            onClicked: backend.cancelUpload()
+                        }
+                        Controls.Label {
+                            visible: !backend.uploading && uploadView.blocked !== ""
+                            opacity: 0.7
+                            text: uploadView.blocked
+                        }
+                    }
+
+                    // Progress: a share while the export is checked, a sweeping bar while it's sent
+                    // (huggingface_hub doesn't report progress). Drawn here, as on the Export page.
+                    Rectangle {
+                        id: track
+                        Layout.preferredWidth: Kirigami.Units.gridUnit * 20
+                        implicitHeight: Kirigami.Units.smallSpacing * 2
+                        visible: backend.uploading
+                        radius: height / 2
+                        clip: true
+                        color: Qt.rgba(Kirigami.Theme.textColor.r, Kirigami.Theme.textColor.g, Kirigami.Theme.textColor.b, 0.15)
+                        readonly property bool unknown: uploadView.up.fraction === undefined || uploadView.up.fraction < 0
+                        Rectangle {
+                            id: fill
+                            height: parent.height
+                            radius: parent.radius
+                            color: Kirigami.Theme.highlightColor
+                            width: track.unknown ? parent.width / 4 : parent.width * Math.max(0, Math.min(1, uploadView.up.fraction))
+                            x: 0
+                            SequentialAnimation on x {
+                                running: track.visible && track.unknown
+                                loops: Animation.Infinite
+                                onRunningChanged: if (!running) fill.x = 0
+                                NumberAnimation { from: -fill.width; to: track.width; duration: 1600 }
+                            }
+                        }
+                    }
+                    Controls.Label {
+                        Layout.fillWidth: true
+                        visible: uploadView.mine && (uploadView.up.text || "") !== ""
+                                 && (backend.uploading || uploadView.up.phase === "failed" && uploadView.upError.kind === "cancelled")
+                        wrapMode: Text.Wrap
+                        text: uploadView.up.text || ""
+                    }
+
+                    // The pull request is open and the files are on their way: time to plug in.
+                    Kirigami.InlineMessage {
+                        Layout.fillWidth: true
+                        visible: backend.uploading && uploadView.mine && (uploadView.up.pr_url || "") !== ""
+                        type: Kirigami.MessageType.Positive
+                        text: "Your pull request is open: " + (uploadView.up.pr_url || "") + ". The files are uploading "
+                              + "to it now, which can take a while. Plug in the headset and leave it plugged in until "
+                              + "this page says Uploaded. You can take the headset off: it stays awake until the upload "
+                              + "is done. Keep the Hand Recorder open."
+                        actions: [openOpenedPr, copyOpenedPr]
+                        Kirigami.Action {
+                            id: openOpenedPr
+                            text: "Open"
+                            icon.name: "internet-services"
+                            onTriggered: Qt.openUrlExternally(uploadView.up.pr_url)
+                        }
+                        Kirigami.Action {
+                            id: copyOpenedPr
+                            text: "Copy link"
+                            icon.name: "edit-copy"
+                            onTriggered: backend.copy(uploadView.up.pr_url)
+                        }
+                    }
+                    Kirigami.InlineMessage {
+                        Layout.fillWidth: true
+                        visible: !backend.uploading && uploadView.mine && uploadView.up.phase === "done"
+                        type: Kirigami.MessageType.Positive
+                        text: uploadView.upResult.dry_run
+                              ? "Dry run: the export passed its checks. It would go to " + uploadView.upResult.repo + "/"
+                                + uploadView.upResult.path_in_repo + " (" + uploadView.upResult.files + " files). Nothing was sent."
+                              : "Uploaded. Your pull request: " + (uploadView.upResult.pr_url || "")
+                                + ". The maintainer reviews it before it joins the dataset."
+                        actions: uploadView.upResult.pr_url ? [openPr, copyPr] : []
+                        Kirigami.Action {
+                            id: openPr
+                            text: "Open"
+                            icon.name: "internet-services"
+                            onTriggered: Qt.openUrlExternally(uploadView.upResult.pr_url)
+                        }
+                        Kirigami.Action {
+                            id: copyPr
+                            text: "Copy link"
+                            icon.name: "edit-copy"
+                            onTriggered: backend.copy(uploadView.upResult.pr_url)
+                        }
+                    }
+                    Kirigami.InlineMessage {
+                        Layout.fillWidth: true
+                        visible: !backend.uploading && uploadView.mine && uploadView.up.phase === "failed"
+                                 && uploadView.upError.kind !== "cancelled"
+                        type: Kirigami.MessageType.Error
+                        text: (uploadView.upError.text || "")
+                              + ((uploadView.upError.errors || []).length ? "\n\n• " + uploadView.upError.errors.join("\n• ") : "")
+                        actions: uploadView.upError.link ? [openErrorLink] : []
+                        Kirigami.Action {
+                            id: openErrorLink
+                            text: "Open"
+                            icon.name: "internet-services"
+                            onTriggered: Qt.openUrlExternally(uploadView.upError.link)
+                        }
+                    }
+                    Controls.TextArea {
+                        Layout.fillWidth: true
+                        visible: uploadView.mine && (uploadView.up.log || "") !== ""
+                        readOnly: true
+                        selectByMouse: true
+                        wrapMode: Text.WrapAnywhere
+                        font.family: "monospace"
+                        text: uploadView.up.log || ""
+                    }
+
+                    Kirigami.Separator { Layout.fillWidth: true; visible: uploadView.session !== "" }
+                    MarkdownText {
+                        Layout.fillWidth: true
+                        visible: uploadView.session !== ""
+                        markdown: backend.uploadText(uploadView.session)
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/hands/rec/panel/ft-handpanel.cpp b/hands/rec/panel/ft-handpanel.cpp
new file mode 100644
index 0000000..c0ff392
--- /dev/null
+++ b/hands/rec/panel/ft-handpanel.cpp
@@ -0,0 +1,1284 @@
+// ft-handpanel: the hand recorder's headset panel (hands/rec/DESIGN.md). A SteamVR overlay
+// fixed to the headset that tells the person what to do with their hands while the cameras
+// record. It sits --distance ahead (1.2 m), centred UP_DEG above straight ahead, so the hands
+// stay clear below it, WIDTH_DEG across (4:3), dim and see-through like the gaze quick check.
+// It's drawn on the CPU and takes no input: the session runner (hands/rec/session.py) drives it.
+//
+// It also does the two jobs that need SteamVR's poses: the "touch the dot" target, a second
+// overlay (frametop.handpanel.target) fixed in the room, and the pose log, the head and the
+// controllers 250 times a second into poses.jsonl, which goes with each take.
+//
+// Control socket: abstract unix datagram "@ft_handpanel" (--socket NAME); a sender with an
+// address gets "ok ..." or "error ...". UTF-8; "|" starts a new line in text:
+//   show / hide                  the panel (a "show" makes it visible with its first picture;
+//                                the target is separate: "target off" hides it)
+//   title <text>                 the big line at the top (empty to clear)
+//   step <text>                  a small line at the top right, e.g. "Section 3 of 11"
+//   text <text>                  the instruction: large, wrapped to the panel's width, centred
+//   note <text>                  an orange warning line under the instruction (empty to clear)
+//   countdown <0..1> | off       a thin bar along the bottom: the share of the prompt's time left
+//   hands <left> <right>         the "Left hand" and "Right hand" chips: seen (green), lost
+//                                (orange) or off (hidden)
+//   bar <target 0..1> <current 0..1|-1> [<near label>|<far label>] / bar off
+//                                the near/far bar: a track with a ring at the target and a dot
+//                                at the hand's position (-1: not seen). The labels are split at
+//                                "|", or else at the first space (default "Near" and "Far")
+//   paused on|off                "Paused" over the picture
+//   image <path> [mirror|both] / image off
+//                                the pose picture (a PNG, square, RGBA, a right hand as the wearer
+//                                sees it) in a column on the left, the text moving right: mirror
+//                                flips it (a left hand), both shows a flipped copy on its left
+//   where <position|-> <distance|-> / where off
+//                                a small diagram under the picture: where to hold the hands, a
+//                                front view (centre, left, right, up, down; or the bar's chest,
+//                                desk, eye), and how far out (near, mid, far)
+//   action <text>                a cyan line under the instruction: "Ready? Press Space ..."
+//   big <text>                   large, under the instruction: the countdown's 3, 2, 1, then "Hold"
+//   keys <text>                  a small faint line along the bottom: the window's keys
+//   rec on|off                   a red "Rec" dot by the step line while recording
+//   strip <cue> <path>|<mode>|<label>;... / strip off
+//                                a sweep's row of pose pictures under the text (path "-": none,
+//                                mode "-" or "mirror"), each with its label; the one at index
+//                                cue (from 0; -1: none) lit, framed in cyan, the others dim. The
+//                                where-to diagram, if any, goes at the row's right end. It takes
+//                                the place of the left column (image is ignored meanwhile)
+//   target <x> <y> <z> [show|hold <0..1>|done] / target off
+//                                the touch target, about 2 cm across. The point is in the head
+//                                frame (metres, +x right, +y up, -z forward). The first command
+//                                with a new point places it in the room with the headset's pose
+//                                at that moment, facing the headset, and it stays there; the
+//                                same point again changes only the state. hold draws a ring
+//                                filling to the share given, done turns it green. "target off"
+//                                hides it and forgets the point. Reply: "ok <room x> <y> <z>"
+//                                (standing universe)
+//   poses start <path> / poses stop
+//                                log poses, appending to path (poses.jsonl, DESIGN.md) at
+//                                250 Hz until stopped. "poses stop" replies "ok <samples>"
+//   devices                      "ok hmd <r> left <r|-> right <r|->": ETrackingResult now
+//                                (- for no device in that role)
+//   head                         "ok <12 floats>": the headset's pose now (standing universe,
+//                                row-major 3x4)
+//   ping                         "ok shown" or "ok hidden"
+//
+// Each picture goes into the next of three shared buffers (linear DMA-BUFs SteamVR imported
+// once), and the overlay switches to it, as gaze/panel/ft-gazepanel.cpp does: SetOverlayRaw
+// flickered and lagged there, so it's only the fallback. The target has its own three small
+// buffers. Pictures are drawn only when a command changed something.
+//
+// The pose log runs on a thread of its own, so a slow picture or command never delays a
+// sample. OpenVR's client isn't documented as thread-safe, so both threads take g_vr around
+// every OpenVR call.
+//
+// Options: --watch-stdin (quit when stdin closes: the session runs it), --socket NAME,
+// --distance METRES, --no-vr. --no-vr is for testing without a headset: no SteamVR at all; each
+// picture's text goes to stdout instead (and with --dump DIR, the pictures to DIR/panel.pam
+// and DIR/target.pam), "poses start" writes nothing, "devices" and "head" reply with an error,
+// and "target" places the point as if the headset were at the room's origin.
+// Runs in the dev container (hands/rec/build.sh builds it into hands/rec/build).
+#include <openvr.h>
+
+#define STB_TRUETYPE_IMPLEMENTATION
+#include "stb_truetype.h"
+#define STB_IMAGE_IMPLEMENTATION
+#define STBI_ONLY_PNG
+#define STBI_NO_HDR
+#define STBI_NO_LINEAR
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wunused-function"  // helpers only other formats use
+#include "stb_image.h"
+#pragma GCC diagnostic pop
+
+#include <drm_fourcc.h>
+#include <fcntl.h>
+#include <gbm.h>
+#include <poll.h>
+#include <sys/socket.h>
+#include <sys/un.h>
+#include <time.h>
+#include <unistd.h>
+
+#include <algorithm>
+#include <atomic>
+#include <cerrno>
+#include <chrono>
+#include <cmath>
+#include <csignal>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <map>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+namespace {
+
+constexpr double kWidthDeg = 36;  // WIDTH_DEG: the panel's width (4:3)
+constexpr double kUpDeg = 12;     // UP_DEG: the panel's centre above straight ahead
+constexpr int kW = 1024, kH = 768;
+constexpr double kPxPerDeg = kW / kWidthDeg;
+constexpr int kTargetPx = 128;
+constexpr double kTargetM = 0.03;      // the target overlay's width: the dot and its ring
+constexpr double kTargetDotM = 0.02;   // the dot itself
+constexpr int64_t kPosePeriodNs = 4'000'000;  // 250 Hz
+std::atomic<bool> g_stop{false};
+std::mutex g_vr;  // around every OpenVR call: the main thread and the pose log's thread make them
+
+int64_t NowNs() {
+    timespec ts;
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+    return int64_t(ts.tv_sec) * 1'000'000'000 + ts.tv_nsec;
+}
+
+// ---------------------------------------------------------------- text (as ft-gazepanel)
+
+stbtt_fontinfo g_font;
+std::vector<unsigned char> g_fontData;
+bool g_fontOk = false;
+struct Glyph {
+    std::vector<unsigned char> bitmap;
+    int w = 0, h = 0, xoff = 0, yoff = 0, advance = 0;
+};
+std::map<std::pair<uint32_t, int>, Glyph> g_glyphs;
+
+void LoadFont() {
+    std::string path;
+    if (FILE *p = popen("fc-match -f '%{file}' 'Noto Sans' 2>/dev/null", "r")) {
+        char buf[512];
+        if (std::fgets(buf, sizeof buf, p)) path = buf;
+        pclose(p);
+    }
+    if (path.empty()) path = "/usr/share/fonts/google-noto-vf/NotoSans[wght].ttf";
+    if (FILE *f = std::fopen(path.c_str(), "rb")) {
+        std::fseek(f, 0, SEEK_END);
+        g_fontData.resize(size_t(std::ftell(f)));
+        std::fseek(f, 0, SEEK_SET);
+        g_fontOk = std::fread(g_fontData.data(), 1, g_fontData.size(), f) == g_fontData.size() &&
+                   stbtt_InitFont(&g_font, g_fontData.data(), stbtt_GetFontOffsetForIndex(g_fontData.data(), 0));
+        std::fclose(f);
+    }
+    if (!g_fontOk) std::fprintf(stderr, "ft-handpanel: no font (%s); no text\n", path.c_str());
+}
+
+const Glyph &GetGlyph(uint32_t cp, int size) {
+    auto [it, fresh] = g_glyphs.try_emplace({cp, size});
+    Glyph &g = it->second;
+    if (fresh) {
+        const float scale = stbtt_ScaleForPixelHeight(&g_font, float(size));
+        unsigned char *b = stbtt_GetCodepointBitmap(&g_font, 0, scale, int(cp), &g.w, &g.h, &g.xoff, &g.yoff);
+        if (b) g.bitmap.assign(b, b + size_t(g.w) * g.h), stbtt_FreeBitmap(b, nullptr);
+        int adv, lsb;
+        stbtt_GetCodepointHMetrics(&g_font, int(cp), &adv, &lsb);
+        g.advance = int(std::lround(adv * scale));
+    }
+    return g;
+}
+
+std::vector<uint32_t> Codepoints(const std::string &s) {
+    std::vector<uint32_t> out;
+    for (const unsigned char *p = (const unsigned char *)s.c_str(); *p;) {
+        uint32_t c = *p++;
+        int more = c >= 0xF0 ? 3 : c >= 0xE0 ? 2 : c >= 0xC0 ? 1 : 0;
+        if (more) c &= 0x3Fu >> more;
+        for (; more && (*p & 0xC0) == 0x80; --more) c = c << 6 | (*p++ & 0x3F);
+        out.push_back(c);
+    }
+    return out;
+}
+
+int TextWidth(const std::string &s, int size) {
+    if (!g_fontOk) return 0;
+    int width = 0;
+    for (uint32_t cp : Codepoints(s)) width += GetGlyph(cp, size).advance;
+    return width;
+}
+
+// s as lines no wider than width: "|" starts a new line, and lines break between words. A
+// word wider than the panel gets a line of its own and runs over.
+std::vector<std::string> Wrap(const std::string &s, int size, int width) {
+    std::vector<std::string> out;
+    if (s.empty()) return out;
+    for (size_t at = 0; at <= s.size();) {
+        const size_t bar = std::min(s.find('|', at), s.size());
+        const std::string para = s.substr(at, bar - at);
+        std::string line;
+        for (size_t w = 0; w < para.size();) {
+            const size_t space = std::min(para.find(' ', w), para.size());
+            const std::string word = para.substr(w, space - w);
+            w = space + 1;
+            if (word.empty()) continue;
+            const std::string longer = line.empty() ? word : line + " " + word;
+            if (line.empty() || TextWidth(longer, size) <= width) {
+                line = longer;
+            } else {
+                out.push_back(line);
+                line = word;
+            }
+        }
+        out.push_back(line);
+        at = bar + 1;
+    }
+    return out;
+}
+
+// ---------------------------------------------------------------- the pictures
+
+struct Picture {
+    int w, h;
+    std::vector<uint8_t> px;  // R, G, B, A (straight alpha)
+};
+
+void Blend(Picture &p, int x, int y, double r, double g, double b, double a) {
+    if (x < 0 || y < 0 || x >= p.w || y >= p.h || a <= 0) return;
+    uint8_t *q = &p.px[(size_t(y) * p.w + x) * 4];
+    a = std::min(a, 1.0);
+    q[0] = uint8_t(std::lround(q[0] + (r * 255 - q[0]) * a));
+    q[1] = uint8_t(std::lround(q[1] + (g * 255 - q[1]) * a));
+    q[2] = uint8_t(std::lround(q[2] + (b * 255 - q[2]) * a));
+    q[3] = uint8_t(std::lround(q[3] + (255 - q[3]) * a));
+}
+
+// A filled disc, or (inner > 0) a ring from inner to outer radius, anti-aliased; with sweep < 1,
+// only that share of the ring, clockwise from the top.
+void Disc(Picture &p, double cx, double cy, double outer, double inner, double r, double g, double b, double a,
+          double sweep = 1) {
+    const int x0 = int(cx - outer - 1), x1 = int(cx + outer + 1), y0 = int(cy - outer - 1), y1 = int(cy + outer + 1);
+    for (int y = y0; y <= y1; ++y)
+        for (int x = x0; x <= x1; ++x) {
+            const double dx = x + 0.5 - cx, dy = y + 0.5 - cy, d = std::hypot(dx, dy);
+            double cover = std::clamp(outer - d + 0.5, 0.0, 1.0);
+            if (inner > 0) cover = std::min(cover, std::clamp(d - inner + 0.5, 0.0, 1.0));
+            if (sweep < 1) {
+                double ang = std::atan2(dx, -dy) / (2 * M_PI);  // 0 at the top, clockwise
+                if (ang < 0) ang += 1;
+                if (ang > sweep) continue;
+            }
+            Blend(p, x, y, r, g, b, a * cover);
+        }
+}
+
+void Rect(Picture &p, int x0, int y0, int x1, int y1, double r, double g, double b, double a) {
+    for (int y = std::max(y0, 0); y < std::min(y1, p.h); ++y)
+        for (int x = std::max(x0, 0); x < std::min(x1, p.w); ++x) Blend(p, x, y, r, g, b, a);
+}
+
+// A rectangle with rounded corners of radius rad, anti-aliased: the panel itself, the chips.
+void RoundRect(Picture &p, int x0, int y0, int x1, int y1, double rad, double r, double g, double b, double a) {
+    for (int y = std::max(y0, 0); y < std::min(y1, p.h); ++y)
+        for (int x = std::max(x0, 0); x < std::min(x1, p.w); ++x) {
+            const double dx = std::max({x0 + rad - x - 0.5, x + 0.5 - (x1 - rad), 0.0});
+            const double dy = std::max({y0 + rad - y - 0.5, y + 0.5 - (y1 - rad), 0.0});
+            Blend(p, x, y, r, g, b, a * std::clamp(rad - std::hypot(dx, dy) + 0.5, 0.0, 1.0));
+        }
+}
+
+enum Align { kLeft, kCentre, kRight };
+
+// Text vertically centred on cy; x is its left end, middle or right end.
+void Text(Picture &p, const std::string &s, int size, int x, int cy, double r, double g, double b, Align align = kCentre) {
+    if (!g_fontOk || s.empty()) return;
+    const auto cps = Codepoints(s);
+    int width = 0;
+    for (uint32_t cp : cps) width += GetGlyph(cp, size).advance;
+    int ascent, descent, gap;
+    stbtt_GetFontVMetrics(&g_font, &ascent, &descent, &gap);
+    const float scale = stbtt_ScaleForPixelHeight(&g_font, float(size));
+    if (align == kCentre) x -= width / 2;
+    else if (align == kRight) x -= width;
+    const int baseline = cy + int(std::lround((ascent + descent) * scale / 2));
+    for (uint32_t cp : cps) {
+        const Glyph &gl = GetGlyph(cp, size);
+        for (int gy = 0; gy < gl.h; ++gy)
+            for (int gx = 0; gx < gl.w; ++gx)
+                Blend(p, x + gl.xoff + gx, baseline + gl.yoff + gy, r, g, b, gl.bitmap[size_t(gy) * gl.w + gx] / 255.0);
+        x += gl.advance;
+    }
+}
+
+void Text(Picture &p, const std::string &s, int size, int x, int cy, double lum, Align align = kCentre) {
+    Text(p, s, size, x, cy, lum, lum, lum, align);
+}
+
+// A pose picture as loaded (straight alpha), and scaled copies of it as drawn.
+struct Image {
+    std::string path;
+    Picture src{0, 0, {}};
+    std::map<std::pair<int, bool>, Picture> scaled;  // (side, mirrored) -> picture
+};
+
+// A PNG into img; false (and img empty) if it can't be read.
+bool LoadImage(Image &img, const std::string &path) {
+    img = Image{};
+    int w = 0, h = 0, n = 0;
+    unsigned char *px = stbi_load(path.c_str(), &w, &h, &n, 4);
+    if (!px) return false;
+    img.path = path;
+    img.src = Picture{w, h, std::vector<uint8_t>(px, px + size_t(w) * h * 4)};
+    stbi_image_free(px);
+    return true;
+}
+
+// The picture fitted into a side x side square (centred, aspect kept), averaging the source
+// pixels each output pixel covers, weighted by alpha so transparent edges don't darken.
+const Picture &Scaled(Image &img, int side, bool mirror) {
+    auto [it, fresh] = img.scaled.try_emplace({side, mirror}, Picture{side, side, {}});
+    Picture &out = it->second;
+    if (!fresh) return out;
+    out.px.assign(size_t(side) * side * 4, 0);
+    const Picture &src = img.src;
+    const double scale = std::max(src.w, src.h) / double(side);  // source pixels per output pixel
+    const double ox = (side - src.w / scale) / 2, oy = (side - src.h / scale) / 2;
+    for (int y = 0; y < side; ++y)
+        for (int x = 0; x < side; ++x) {
+            const double sx0 = (x - ox) * scale, sy0 = (y - oy) * scale;
+            const int x0 = std::max(0, int(std::floor(sx0))), y0 = std::max(0, int(std::floor(sy0)));
+            const int x1 = std::min(src.w, int(std::ceil(sx0 + scale))), y1 = std::min(src.h, int(std::ceil(sy0 + scale)));
+            double r = 0, g = 0, b = 0, a = 0;
+            int count = 0;
+            for (int sy = y0; sy < y1; ++sy)
+                for (int sx = x0; sx < x1; ++sx) {
+                    const uint8_t *q = &src.px[(size_t(sy) * src.w + (mirror ? src.w - 1 - sx : sx)) * 4];
+                    const double qa = q[3] / 255.0;
+                    r += q[0] * qa, g += q[1] * qa, b += q[2] * qa, a += qa, ++count;
+                }
+            if (!count || a <= 0) continue;
+            uint8_t *o = &out.px[(size_t(y) * side + x) * 4];
+            o[0] = uint8_t(std::lround(r / a)), o[1] = uint8_t(std::lround(g / a)), o[2] = uint8_t(std::lround(b / a));
+            o[3] = uint8_t(std::lround(255 * a / count));
+        }
+    return out;
+}
+
+void DrawPicture(Picture &dst, const Picture &src, int x0, int y0, double opacity = 1) {
+    for (int y = 0; y < src.h; ++y)
+        for (int x = 0; x < src.w; ++x) {
+            const uint8_t *q = &src.px[(size_t(y) * src.w + x) * 4];
+            if (q[3]) Blend(dst, x0 + x, y0 + y, q[0] / 255.0, q[1] / 255.0, q[2] / 255.0, opacity * q[3] / 255.0);
+        }
+}
+
+// A sweep's strip: its pictures, loaded once each (a strip changes only its lit one as it goes).
+struct StripItem {
+    std::string path, mode, label;
+};
+std::map<std::string, Image> g_stripImages;  // path -> picture (empty if it can't be read)
+
+Image &StripImage(const std::string &path) {
+    auto [it, fresh] = g_stripImages.try_emplace(path);
+    if (fresh && !LoadImage(it->second, path))
+        std::fprintf(stderr, "ft-handpanel: can't read %s: %s\n", path.c_str(), stbi_failure_reason());
+    return it->second;
+}
+
+// The where-to diagram's cells: a front view, 3 x 3, (column, row) from the top left.
+bool WhereCell(const std::string &pos, int &col, int &row) {
+    col = 1, row = 1;
+    if (pos == "left") col = 0;
+    else if (pos == "right") col = 2;
+    else if (pos == "up" || pos == "eye") row = 0;
+    else if (pos == "down" || pos == "desk") row = 2;
+    else if (pos != "centre" && pos != "center" && pos != "chest") return false;
+    return true;
+}
+
+const char *WhereLabel(const std::string &pos) {
+    if (pos == "left") return "To your left";
+    if (pos == "right") return "To your right";
+    if (pos == "up") return "Up high";
+    if (pos == "down") return "Down low";
+    if (pos == "chest") return "Chest height";
+    if (pos == "desk") return "Desk height";
+    if (pos == "eye") return "Eye level";
+    return "In front";
+}
+
+int DistanceStep(const std::string &dist) { return dist == "near" ? 0 : dist == "mid" ? 1 : dist == "far" ? 2 : -1; }
+
+const char *DistanceLabel(int k) { return k == 0 ? "Close" : k == 1 ? "Halfway out" : "Arm out"; }
+
+constexpr double kCyan[3] = {0.3, 0.85, 1.0};
+
+// The diagram in x0..x0+w, y0..y0+h: the front view on the left, the distance on the right
+// (or either alone, centred), each with its caption under it.
+void DrawWhere(Picture &pic, int x0, int y0, int w, int h, const std::string &pos, const std::string &dist) {
+    const double ppd = kPxPerDeg;
+    int col, row;
+    const bool grid = WhereCell(pos, col, row);
+    const int step = DistanceStep(dist);
+    const int parts = int(grid) + int(step >= 0);
+    if (!parts) return;
+    const int capSize = int(ppd * 0.75), capH = int(capSize * 1.6), partW = w / parts;
+    const int boxH = h - capH;
+    int px = x0;
+    if (grid) {
+        const int gw = std::min(partW - int(ppd * 0.6), boxH * 4 / 3), gh = gw * 3 / 4;
+        const int gx = px + (partW - gw) / 2, gy = y0 + (boxH - gh) / 2;
+        RoundRect(pic, gx, gy, gx + gw, gy + gh, ppd * 0.3, 1, 1, 1, 0.08);
+        for (int k = 1; k < 3; ++k) {
+            Rect(pic, gx + gw * k / 3 - 1, gy + 3, gx + gw * k / 3 + 1, gy + gh - 3, 1, 1, 1, 0.18);
+            Rect(pic, gx + 3, gy + gh * k / 3 - 1, gx + gw - 3, gy + gh * k / 3 + 1, 1, 1, 1, 0.18);
+        }
+        const int pad = std::max(3, int(ppd * 0.12));
+        RoundRect(pic, gx + gw * col / 3 + pad, gy + gh * row / 3 + pad, gx + gw * (col + 1) / 3 - pad,
+                  gy + gh * (row + 1) / 3 - pad, ppd * 0.18, kCyan[0], kCyan[1], kCyan[2], 0.9);
+        Text(pic, WhereLabel(pos), capSize, px + partW / 2, y0 + boxH + capH / 2, 0.85);
+        px += partW;
+    }
+    if (step >= 0) {
+        // Seen from the side: the head on the left, the arm's reach to the right, three marks.
+        const int cy = y0 + boxH / 2, head = int(ppd * 0.55);
+        const int hx = px + int(ppd * 0.4) + head, ax0 = hx + head + int(ppd * 0.3), ax1 = px + partW - int(ppd * 0.5);
+        Disc(pic, hx, cy, head, 0, 1, 1, 1, 0.75);
+        RoundRect(pic, hx + head / 3, cy - head / 2, hx + head + int(ppd * 0.2), cy + head / 3, 3, 0.25, 0.25, 0.28, 1);
+        Rect(pic, ax0, cy - 1, ax1, cy + 1, 1, 1, 1, 0.3);
+        for (int k = 0; k < 3; ++k) {
+            const double x = ax0 + (ax1 - ax0) * (k + 1) / 3.0;
+            if (k == step) Disc(pic, x, cy, ppd * 0.38, 0, kCyan[0], kCyan[1], kCyan[2], 0.95);
+            else Disc(pic, x, cy, ppd * 0.16, 0, 1, 1, 1, 0.45);
+        }
+        Text(pic, DistanceLabel(step), capSize, px + partW / 2, y0 + boxH + capH / 2, 0.85);
+    }
+}
+
+struct Panel {
+    Picture pic{kW, kH, {}};
+    std::string title, step, text, note, action, big, keys;
+    double countdown = -1;  // the share of the prompt's time left, or -1: off
+    std::string hands[2] = {"off", "off"};
+    bool barOn = false;
+    double barTarget = 0, barCurrent = -1;
+    std::string nearLabel = "Near", farLabel = "Far";
+    bool paused = false, rec = false;
+    Image image;                     // the pose picture, if image.path isn't empty
+    std::string imageMode;           // "", "mirror" or "both"
+    std::string wherePos, whereDist; // the diagram's, "" for none
+    std::vector<StripItem> strip;    // a sweep's pictures, or none
+    int stripCue = -1;               // the lit one
+    // What the last Draw laid out, for --no-vr's printout.
+    std::vector<std::string> lines, noteLines;
+    double textDeg = 0;
+};
+
+void Draw(Panel &p) {
+    // The dim rounded panel, see-through so it's clear of what's behind (the quick check's look,
+    // with the same corner radius in degrees). It never changes, so it's drawn once.
+    static Picture back{kW, kH, {}};
+    if (back.px.empty()) {
+        back.px.assign(size_t(kW) * kH * 4, 0);
+        RoundRect(back, 0, 0, kW, kH, kPxPerDeg * 1.9, 0.06, 0.06, 0.07, 0.82);
+    }
+    Picture &pic = p.pic;
+    pic.px = back.px;
+    const double ppd = kPxPerDeg, faint = 0.75;
+    const int margin = int(ppd * 1.6), width = kW - 2 * margin;
+
+    // The title and the step share the top line, a red "Rec" by the step while recording; a
+    // faint rule under them.
+    int top = margin;
+    if (!p.title.empty() || !p.step.empty() || p.rec) {
+        const int titleSize = int(ppd * 1.6), stepSize = int(ppd * 0.9), cy = margin + titleSize / 2;
+        Text(pic, p.step, stepSize, kW - margin, cy, faint, kRight);
+        if (p.rec) {
+            const int rx = kW - margin - TextWidth(p.step, stepSize) - (p.step.empty() ? 0 : int(ppd * 0.8));
+            Text(pic, "Rec", stepSize, rx, cy, 1.0, 0.45, 0.4, kRight);
+            Disc(pic, rx - TextWidth("Rec", stepSize) - ppd * 0.45, cy, ppd * 0.25, 0, 0.95, 0.2, 0.15, 1);
+        }
+        Text(pic, p.title, titleSize, margin, cy, 1.0, kLeft);
+        top = cy + int(titleSize * 0.85);
+        Rect(pic, margin, top, kW - margin, top + 2, 1, 1, 1, 0.15);
+        top += int(ppd * 0.8);
+    }
+
+    // From the bottom up: the keys, the countdown, the chips, the near/far bar. The rest gets what's left.
+    int bottom = kH - margin, foot = kH - int(ppd * 0.9);
+    if (!p.keys.empty()) {
+        Text(pic, p.keys, int(ppd * 0.7), kW / 2, foot, 0.55);
+        foot -= int(ppd * 1.0);
+        bottom = std::min(bottom, foot - int(ppd * 0.4));
+    }
+    if (p.countdown >= 0) {
+        const int y = foot, th = std::max(4, int(ppd * 0.22));
+        Rect(pic, margin, y, kW - margin, y + th, 1, 1, 1, 0.15);
+        Rect(pic, margin, y, margin + int(std::lround(width * p.countdown)), y + th, kCyan[0], kCyan[1], kCyan[2], 0.95);
+        bottom = std::min(bottom, y - int(ppd * 0.6));
+    }
+    if (p.hands[0] != "off" || p.hands[1] != "off") {
+        const int ch = int(ppd * 1.25), size = int(ppd * 0.85), cy = bottom - ch / 2, gap = int(ppd * 0.6);
+        for (int k = 0; k < 2; ++k) {
+            if (p.hands[k] == "off") continue;
+            const char *label = k ? "Right hand" : "Left hand";
+            const int cw = TextWidth(label, size) + 2 * int(ppd * 0.8);
+            const int x0 = k ? kW / 2 + gap / 2 : kW / 2 - gap / 2 - cw;
+            if (p.hands[k] == "seen") RoundRect(pic, x0, cy - ch / 2, x0 + cw, cy + ch / 2, ch / 2.0, 0.2, 0.62, 0.32, 0.95);
+            else RoundRect(pic, x0, cy - ch / 2, x0 + cw, cy + ch / 2, ch / 2.0, 0.95, 0.5, 0.12, 0.95);
+            Text(pic, label, size, x0 + cw / 2, cy, 1.0);
+        }
+        bottom = cy - ch / 2 - int(ppd * 0.7);
+    }
+    if (p.barOn) {
+        // The ring is where the hand should be, the dot where it is: put the dot in the ring.
+        const int labelSize = int(ppd * 0.85), ly = bottom - labelSize / 2, ty = ly - int(ppd * 1.2);
+        const int x0 = margin + int(ppd), x1 = kW - margin - int(ppd), th = std::max(6, int(ppd * 0.3));
+        RoundRect(pic, x0, ty - th / 2, x1, ty + th / 2, th / 2.0, 1, 1, 1, 0.2);
+        Text(pic, p.nearLabel, labelSize, x0, ly, faint, kLeft);
+        Text(pic, p.farLabel, labelSize, x1, ly, faint, kRight);
+        const double ring = ppd * 0.65;
+        Disc(pic, x0 + (x1 - x0) * p.barTarget, ty, ring, ring - ppd * 0.14, 1, 1, 1, 0.95);
+        if (p.barCurrent >= 0) Disc(pic, x0 + (x1 - x0) * p.barCurrent, ty, ppd * 0.4, 0, kCyan[0], kCyan[1], kCyan[2], 0.95);
+        bottom = ty - int(ring) - int(ppd * 0.8);
+    }
+
+    // A sweep's strip: a row of pictures along the bottom of what's left, labels under them, the
+    // diagram at its right end; the text goes above it.
+    int textX0 = margin, textX1 = kW - margin;
+    int col, row;
+    const bool imageOn = !p.image.path.empty() && p.strip.empty();
+    const bool whereOn = WhereCell(p.wherePos, col, row) || DistanceStep(p.whereDist) >= 0;
+    if (!p.strip.empty()) {
+        const int n = int(p.strip.size()), gap = int(ppd * 0.6), whereW = whereOn ? int(ppd * 9) : 0;
+        const int labelSize = int(ppd * 0.85), labelH = int(labelSize * 1.6), frame = std::max(3, int(ppd * 0.14));
+        const int rowW = width - (whereOn ? whereW + gap : 0);
+        const int side = std::max(8, std::min({int(ppd * 6), (rowW - (n - 1) * gap) / n, (bottom - top) / 2 - labelH}));
+        const int y0 = bottom - side - labelH, totalW = n * side + (n - 1) * gap;
+        int x = margin + (rowW - totalW) / 2;
+        for (int k = 0; k < n; ++k, x += side + gap) {
+            const StripItem &it = p.strip[k];
+            const bool lit = k == p.stripCue;
+            RoundRect(pic, x - frame, y0 - frame, x + side + frame, y0 + side + frame, ppd * 0.5, kCyan[0], kCyan[1],
+                      kCyan[2], lit ? 0.95 : 0);
+            RoundRect(pic, x, y0, x + side, y0 + side, ppd * 0.4, 0.16, 0.16, 0.18, 1);
+            Image *img = it.path.empty() ? nullptr : &StripImage(it.path);
+            if (img && !img->path.empty()) DrawPicture(pic, Scaled(*img, side, it.mode == "mirror"), x, y0, lit ? 1.0 : 0.4);
+            if (lit) Text(pic, it.label, labelSize, x + side / 2, y0 + side + labelH / 2 + frame, kCyan[0], kCyan[1], kCyan[2]);
+            else Text(pic, it.label, labelSize, x + side / 2, y0 + side + labelH / 2 + frame, 0.6);
+        }
+        if (whereOn) DrawWhere(pic, kW - margin - whereW, y0 + (side + labelH - int(ppd * 4.4)) / 2, whereW, int(ppd * 4.4),
+                               p.wherePos, p.whereDist);
+        bottom = y0 - frame - int(ppd * 0.8);
+    } else if (imageOn || whereOn) {
+        const int colW = int(ppd * 14), gap = int(ppd * 0.6);
+        const int whereH = whereOn ? int(ppd * 4.4) : 0, between = imageOn && whereOn ? gap : 0;
+        const bool both = p.imageMode == "both";
+        const int side = imageOn ? std::max(0, std::min(both ? (colW - gap) / 2 : colW, bottom - top - whereH - between)) : 0;
+        int y = top + std::max(0, (bottom - top - side - between - whereH) / 2);
+        if (side > 0) {
+            const int pw = both ? 2 * side + gap : side, x = margin + (colW - pw) / 2;
+            RoundRect(pic, x - gap / 2, y - gap / 2, x + pw + gap / 2, y + side + gap / 2, ppd * 0.6, 1, 1, 1, 0.05);
+            if (both) {
+                DrawPicture(pic, Scaled(p.image, side, true), x, y);
+                DrawPicture(pic, Scaled(p.image, side, false), x + side + gap, y);
+            } else {
+                DrawPicture(pic, Scaled(p.image, side, p.imageMode == "mirror"), x, y);
+            }
+            y += side + between;
+        }
+        if (whereOn) DrawWhere(pic, margin, y, colW, whereH, p.wherePos, p.whereDist);
+        textX0 = margin + colW + int(ppd * 1.2);
+    }
+    const int textW = textX1 - textX0, textCx = (textX0 + textX1) / 2;
+
+    // The instruction, the note, the big countdown and the action line, centred together in
+    // the space between. A long instruction gets smaller, down to 1 degree a line, before it runs over.
+    const int noteSize = int(ppd * 1.1), noteLh = int(noteSize * 1.3), gapY = int(ppd * 0.6);
+    const int bigSize = int(ppd * 3.0), bigLh = int(bigSize * 1.1), actionSize = int(ppd * 1.05), actionLh = int(actionSize * 1.4);
+    p.noteLines = Wrap(p.note, noteSize, textW);
+    const std::vector<std::string> actionLines = Wrap(p.action, actionSize, textW);
+    int size = 0, lh = 0, block = 0;
+    for (p.textDeg = 1.4;; p.textDeg -= 0.1) {
+        size = int(ppd * p.textDeg), lh = int(size * 1.3);
+        p.lines = Wrap(p.text, size, textW);
+        block = int(p.lines.size()) * lh + (p.noteLines.empty() ? 0 : gapY + int(p.noteLines.size()) * noteLh) +
+                (p.big.empty() ? 0 : gapY + bigLh) + (actionLines.empty() ? 0 : gapY + int(actionLines.size()) * actionLh);
+        if (block <= bottom - top || p.textDeg < 1.05) break;
+    }
+    int y = top + std::max(0, (bottom - top - block) / 2);
+    bool first = true;
+    auto gapBefore = [&] { if (!first) y += gapY; first = false; };
+    if (!p.lines.empty()) {
+        first = false;
+        for (const std::string &line : p.lines) Text(pic, line, size, textCx, y + lh / 2, 1.0), y += lh;
+    }
+    if (!p.noteLines.empty()) {
+        gapBefore();
+        for (const std::string &line : p.noteLines) Text(pic, line, noteSize, textCx, y + noteLh / 2, 1.0, 0.62, 0.3), y += noteLh;
+    }
+    if (!p.big.empty()) {
+        gapBefore();
+        Text(pic, p.big, bigSize, textCx, y + bigLh / 2, kCyan[0], kCyan[1], kCyan[2]), y += bigLh;
+    }
+    if (!actionLines.empty()) {
+        gapBefore();
+        for (const std::string &line : actionLines)
+            Text(pic, line, actionSize, textCx, y + actionLh / 2, kCyan[0], kCyan[1], kCyan[2]), y += actionLh;
+    }
+
+    if (p.paused) {
+        // The picture stays faintly behind, so it's clear what resumes; the word sits on a
+        // solid pill, so the text behind doesn't run through it.
+        const int size = int(ppd * 2.4), pw = TextWidth("Paused", size) + 2 * int(ppd * 1.2), ph = int(size * 1.6);
+        RoundRect(pic, 0, 0, kW, kH, kPxPerDeg * 1.9, 0.02, 0.02, 0.03, 0.75);
+        RoundRect(pic, (kW - pw) / 2, (kH - ph) / 2, (kW + pw) / 2, (kH + ph) / 2, ph / 2.0, 0.12, 0.12, 0.14, 1);
+        Text(pic, "Paused", size, kW / 2, kH / 2, 1.0);
+    }
+}
+
+struct Target {
+    Picture pic{kTargetPx, kTargetPx, {}};
+    bool on = false, placed = false;
+    double head[3] = {0, 0, 0}, room[3] = {0, 0, 0};
+    std::string state = "show";
+    double progress = 0;
+};
+
+// The dot: lit from the upper left, so it reads as a small ball, with a dark outline so it
+// shows against a bright room. hold adds a ring around it filling clockwise; done turns it green.
+void DrawTarget(Target &t) {
+    Picture &pic = t.pic;
+    pic.px.assign(size_t(pic.w) * pic.h * 4, 0);
+    const double c = pic.w / 2.0, rad = pic.w * kTargetDotM / kTargetM / 2, outline = pic.w * 0.025;
+    const bool done = t.state == "done";
+    const double cr = done ? 0.3 : 1.0, cg = done ? 0.9 : 1.0, cb = done ? 0.4 : 1.0;
+    const double lx = -0.45, ly = -0.55, lz = std::sqrt(1 - lx * lx - ly * ly);
+    Disc(pic, c, c, rad + outline, 0, 0.05, 0.05, 0.06, 0.95);
+    for (int y = 0; y < pic.h; ++y)
+        for (int x = 0; x < pic.w; ++x) {
+            const double dx = (x + 0.5 - c) / rad, dy = (y + 0.5 - c) / rad, d2 = dx * dx + dy * dy;
+            const double cover = std::clamp((1 - std::sqrt(d2)) * rad + 0.5, 0.0, 1.0);
+            if (cover <= 0) continue;
+            const double nz = std::sqrt(std::max(0.0, 1 - d2));
+            const double shade = 0.55 + 0.45 * std::max(0.0, dx * lx + dy * ly + nz * lz);
+            Blend(pic, x, y, cr * shade, cg * shade, cb * shade, cover);
+        }
+    if (t.state == "hold") {
+        const double r0 = rad + outline + pic.w * 0.05, r1 = r0 + pic.w * 0.07;
+        Disc(pic, c, c, r1 + outline, r0 - outline, 0.05, 0.05, 0.06, 0.6);
+        Disc(pic, c, c, r1, r0, 1, 1, 1, 0.3);
+        Disc(pic, c, c, r1, r0, 0.3, 0.85, 1.0, 1, std::clamp(t.progress, 0.0, 1.0));
+    }
+}
+
+// --no-vr: a picture as a PAM file (RGBA, straight alpha) for checking the layout by eye.
+void Dump(const Picture &pic, const std::string &path) {
+    if (FILE *f = std::fopen(path.c_str(), "wb")) {
+        std::fprintf(f, "P7\nWIDTH %d\nHEIGHT %d\nDEPTH 4\nMAXVAL 255\nTUPLTYPE RGB_ALPHA\nENDHDR\n", pic.w, pic.h);
+        std::fwrite(pic.px.data(), 1, pic.px.size(), f);
+        std::fclose(f);
+    }
+}
+
+// --no-vr: the state the pictures show, as text.
+void Print(const Panel &p, const Target &t, bool visible, int number) {
+    std::printf("--- picture %d: panel %s\n", number, visible ? "shown" : "hidden");
+    std::printf("title: %s\nstep: %s\n", p.title.c_str(), p.step.c_str());
+    std::printf("text: %zu line(s), %.1f deg\n", p.lines.size(), p.textDeg);
+    for (const std::string &line : p.lines) std::printf("  | %s\n", line.c_str());
+    std::printf("note: %zu line(s)\n", p.noteLines.size());
+    for (const std::string &line : p.noteLines) std::printf("  | %s\n", line.c_str());
+    if (p.countdown >= 0) std::printf("countdown: %.2f\n", p.countdown);
+    else std::printf("countdown: off\n");
+    std::printf("hands: left %s, right %s\n", p.hands[0].c_str(), p.hands[1].c_str());
+    if (p.barOn)
+        std::printf("bar: target %.2f, current %.2f, near \"%s\", far \"%s\"\n", p.barTarget, p.barCurrent,
+                    p.nearLabel.c_str(), p.farLabel.c_str());
+    else std::printf("bar: off\n");
+    std::printf("paused: %s\n", p.paused ? "on" : "off");
+    std::printf("big: %s\naction: %s\nkeys: %s\nrec: %s\n", p.big.c_str(), p.action.c_str(), p.keys.c_str(),
+                p.rec ? "on" : "off");
+    if (!p.image.path.empty())
+        std::printf("image: %s %dx%d%s%s\n", p.image.path.c_str(), p.image.src.w, p.image.src.h,
+                    p.imageMode.empty() ? "" : " ", p.imageMode.c_str());
+    else std::printf("image: off\n");
+    if (!p.wherePos.empty() || !p.whereDist.empty())
+        std::printf("where: %s %s\n", p.wherePos.empty() ? "-" : p.wherePos.c_str(), p.whereDist.empty() ? "-" : p.whereDist.c_str());
+    else std::printf("where: off\n");
+    if (!p.strip.empty()) {
+        std::printf("strip: cue %d:", p.stripCue);
+        for (const StripItem &it : p.strip)
+            std::printf(" %s(%s%s)", it.label.c_str(), it.path.empty() ? "no picture" : it.path.c_str(),
+                        it.mode.empty() ? "" : (" " + it.mode).c_str());
+        std::printf("\n");
+    } else {
+        std::printf("strip: off\n");
+    }
+    if (t.on)
+        std::printf("target: %s %.2f, head %.3f %.3f %.3f, room %.3f %.3f %.3f\n", t.state.c_str(), t.progress, t.head[0],
+                    t.head[1], t.head[2], t.room[0], t.room[1], t.room[2]);
+    else std::printf("target: off\n");
+    std::fflush(stdout);
+}
+
+// ---------------------------------------------------------------- the buffers (see the top)
+
+struct Buffer {
+    gbm_bo *bo = nullptr;
+    int fd = -1;
+    vr::SharedTextureHandle_t handle = 0;
+};
+
+struct Buffers {
+    int w = 0, h = 0;
+    int drm = -1;
+    gbm_device *gbm = nullptr;
+    Buffer b[3];
+    int next = 0;
+    bool ok = false;
+
+    bool Make(int width, int height) {
+        w = width, h = height;
+        drm = open("/dev/dri/renderD128", O_RDWR | O_CLOEXEC);
+        if (drm >= 0) gbm = gbm_create_device(drm);
+        for (Buffer &x : b) {
+            // ABGR8888 is R, G, B, A in memory, like Picture::px.
+            if (gbm) x.bo = gbm_bo_create(gbm, w, h, GBM_FORMAT_ABGR8888, GBM_BO_USE_RENDERING | GBM_BO_USE_LINEAR);
+            if (!x.bo || (x.fd = gbm_bo_get_fd(x.bo)) < 0) break;
+            vr::DmabufAttributes_t a{};
+            a.unWidth = w, a.unHeight = h;
+            a.unDepth = a.unMipLevels = a.unArrayLayers = a.unSampleCount = 1;
+            a.unFormat = DRM_FORMAT_ABGR8888;
+            a.ulModifier = DRM_FORMAT_MOD_LINEAR;
+            a.unPlaneCount = 1;
+            a.plane[0].unOffset = gbm_bo_get_offset(x.bo, 0);
+            a.plane[0].unStride = gbm_bo_get_stride(x.bo);
+            a.plane[0].nFd = x.fd;
+            if (!vr::VRIPCResourceManager()->ImportDmabuf(vr::VRApplication_Overlay, &a, &x.handle)) x.handle = 0;
+            if (!x.handle) break;
+        }
+        ok = b[2].handle != 0;
+        if (!ok) {
+            std::fprintf(stderr, "ft-handpanel: no shared buffers; falling back to SetOverlayRaw (it flickers)\n");
+            Drop();
+        }
+        return ok;
+    }
+
+    void Drop() {
+        for (Buffer &x : b) {
+            if (x.handle) vr::VRIPCResourceManager()->UnrefResource(x.handle);
+            if (x.fd >= 0) close(x.fd);
+            if (x.bo) gbm_bo_destroy(x.bo);
+            x = Buffer{};
+        }
+        if (gbm) gbm_device_destroy(gbm);
+        if (drm >= 0) close(drm);
+        gbm = nullptr, drm = -1, ok = false;
+    }
+
+    // A picture to the overlay: into the next buffer, premultiplied (the overlay's flag says
+    // so), then the overlay switches to it. The copy runs outside g_vr, so the pose log waits
+    // only for the two calls at the end.
+    void Present(vr::IVROverlay *ov, vr::VROverlayHandle_t oh, const Picture &p) {
+        vr::EVROverlayError e;
+        if (!ok) {
+            std::lock_guard<std::mutex> lk(g_vr);
+            e = ov->SetOverlayRaw(oh, const_cast<uint8_t *>(p.px.data()), uint32_t(p.w), uint32_t(p.h), 4);
+        } else {
+            Buffer &x = b[next];
+            next = (next + 1) % 3;
+            uint32_t stride = 0;
+            void *mapping = nullptr;
+            auto *dst = static_cast<uint8_t *>(gbm_bo_map(x.bo, 0, 0, p.w, p.h, GBM_BO_TRANSFER_WRITE, &stride, &mapping));
+            if (!dst) {
+                std::fprintf(stderr, "ft-handpanel: can't map a buffer\n");
+                return;
+            }
+            for (int y = 0; y < p.h; ++y) {
+                const uint8_t *src = &p.px[size_t(y) * p.w * 4];
+                uint8_t *row = dst + size_t(y) * stride;
+                for (int i = 0; i < p.w * 4; i += 4) {
+                    const unsigned a = src[i + 3];
+                    row[i] = uint8_t(src[i] * a / 255), row[i + 1] = uint8_t(src[i + 1] * a / 255);
+                    row[i + 2] = uint8_t(src[i + 2] * a / 255), row[i + 3] = uint8_t(a);
+                }
+            }
+            gbm_bo_unmap(x.bo, mapping);
+            const vr::VRTextureBounds_t bounds{0, 0, float(p.w) / w, float(p.h) / h};
+            vr::Texture_t tex = {&x.handle, vr::TextureType_SharedTextureHandle, vr::ColorSpace_Gamma};
+            std::lock_guard<std::mutex> lk(g_vr);
+            ov->SetOverlayTextureBounds(oh, &bounds);
+            e = ov->SetOverlayTexture(oh, &tex);
+        }
+        if (e != vr::VROverlayError_None)
+            std::fprintf(stderr, "ft-handpanel: the picture didn't go to SteamVR: %s\n", ov->GetOverlayErrorNameFromEnum(e));
+    }
+};
+
+// ---------------------------------------------------------------- the pose log (poses.jsonl)
+
+// Non-finite numbers aren't JSON; SteamVR shouldn't send any, but one would spoil the file.
+void PutFloat(FILE *f, float v) { std::fprintf(f, "%.6g", std::isfinite(v) ? double(v) : 0.0); }
+
+void PutDevice(FILE *f, const char *name, const vr::TrackedDevicePose_t *pose) {
+    if (!pose || !pose->bDeviceIsConnected) {
+        std::fprintf(f, "\"%s\": null", name);
+        return;
+    }
+    std::fprintf(f, "\"%s\": {\"m\": [", name);
+    for (int i = 0; i < 12; ++i) {
+        if (i) std::fputs(", ", f);
+        PutFloat(f, pose->mDeviceToAbsoluteTracking.m[i / 4][i % 4]);
+    }
+    std::fprintf(f, "], \"r\": %d, \"ok\": %s}", int(pose->eTrackingResult), pose->bPoseIsValid ? "true" : "false");
+}
+
+// The thread is the only one touching the file while it runs; Start and Stop, on the main
+// thread, open and close it around the thread's life.
+struct PoseLog {
+    FILE *f = nullptr;
+    std::thread th;
+    std::atomic<bool> run{false};
+    std::atomic<long> samples{0};
+
+    bool Start(const std::string &path) {
+        Stop();
+        if (!(f = std::fopen(path.c_str(), "ae"))) return false;
+        std::setvbuf(f, nullptr, _IOFBF, 1 << 16);
+        samples = 0, run = true;
+        th = std::thread([this] { Run(); });
+        return true;
+    }
+
+    long Stop() {
+        if (!f) return 0;
+        run = false;
+        if (th.joinable()) th.join();
+        if (std::fflush(f) != 0 || std::ferror(f)) std::fprintf(stderr, "ft-handpanel: writing the pose log failed\n");
+        std::fclose(f);
+        f = nullptr;
+        return samples;
+    }
+
+    void Run() {
+        auto *sys = vr::VRSystem();
+        vr::TrackedDevicePose_t poses[vr::k_unMaxTrackedDeviceCount];
+        vr::TrackedDeviceIndex_t left = vr::k_unTrackedDeviceIndexInvalid, right = left;
+        int64_t next = NowNs(), lastFlush = next, lastRoles = next - 1'000'000'000;
+        while (run) {
+            int64_t before, after;
+            {
+                std::lock_guard<std::mutex> lk(g_vr);
+                // Roles change rarely (a controller turned on, hands swapped): four looks a second.
+                if (next - lastRoles >= 250'000'000) {
+                    left = sys->GetTrackedDeviceIndexForControllerRole(vr::TrackedControllerRole_LeftHand);
+                    right = sys->GetTrackedDeviceIndexForControllerRole(vr::TrackedControllerRole_RightHand);
+                    lastRoles = next;
+                }
+                before = NowNs();
+                sys->GetDeviceToAbsoluteTrackingPose(vr::TrackingUniverseStanding, 0, poses, vr::k_unMaxTrackedDeviceCount);
+                after = NowNs();
+            }
+            const int64_t t = before + (after - before) / 2;
+            std::fprintf(f, "{\"t\": %lld, ", (long long)t);
+            PutDevice(f, "hmd", &poses[vr::k_unTrackedDeviceIndex_Hmd]);
+            std::fputs(", ", f);
+            PutDevice(f, "left", left < vr::k_unMaxTrackedDeviceCount ? &poses[left] : nullptr);
+            std::fputs(", ", f);
+            PutDevice(f, "right", right < vr::k_unMaxTrackedDeviceCount ? &poses[right] : nullptr);
+            std::fputs("}\n", f);
+            ++samples;
+            if (t - lastFlush >= 1'000'000'000) std::fflush(f), lastFlush = t;
+            // On a fixed beat; after a stall (a suspended process, a slow OpenVR call), pick up
+            // from now rather than writing a burst of samples to catch up.
+            next += kPosePeriodNs;
+            const int64_t now = NowNs();
+            if (next < now - kPosePeriodNs) next = now;
+            const timespec ts{time_t(next / 1'000'000'000), long(next % 1'000'000'000)};
+            clock_nanosleep(CLOCK_MONOTONIC, TIMER_ABSTIME, &ts, nullptr);
+        }
+    }
+};
+
+// ---------------------------------------------------------------- placing the target
+
+// The headset's pose now, in the standing universe; false if SteamVR has none.
+bool HeadPose(vr::HmdMatrix34_t &m) {
+    vr::TrackedDevicePose_t pose{};
+    std::lock_guard<std::mutex> lk(g_vr);
+    vr::VRSystem()->GetDeviceToAbsoluteTrackingPose(vr::TrackingUniverseStanding, 0, &pose, 1);
+    m = pose.mDeviceToAbsoluteTracking;
+    return pose.bDeviceIsConnected && pose.bPoseIsValid;
+}
+
+// An overlay's transform at `at`, its face (+z) turned toward `eye`, upright in the room.
+vr::HmdMatrix34_t Facing(const double at[3], const double eye[3]) {
+    auto norm = [](double v[3]) {
+        const double n = std::sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
+        if (n < 1e-9) return false;
+        v[0] /= n, v[1] /= n, v[2] /= n;
+        return true;
+    };
+    double z[3] = {eye[0] - at[0], eye[1] - at[1], eye[2] - at[2]};
+    if (!norm(z)) z[0] = z[1] = 0, z[2] = 1;
+    double x[3] = {z[2], 0, -z[0]};  // up (0, 1, 0) x z
+    if (!norm(x)) x[0] = 1, x[1] = x[2] = 0;  // straight above or below: any upright x will do
+    const double y[3] = {z[1] * x[2] - z[2] * x[1], z[2] * x[0] - z[0] * x[2], z[0] * x[1] - z[1] * x[0]};
+    vr::HmdMatrix34_t m{};
+    for (int r = 0; r < 3; ++r)
+        m.m[r][0] = float(x[r]), m.m[r][1] = float(y[r]), m.m[r][2] = float(z[r]), m.m[r][3] = float(at[r]);
+    return m;
+}
+
+// The command word: buf starts with word, then a space or the end; rest is what follows.
+bool Is(const char *buf, const char *word, const char **rest = nullptr) {
+    const size_t n = std::strlen(word);
+    if (std::strncmp(buf, word, n) || (buf[n] && buf[n] != ' ')) return false;
+    if (rest) *rest = buf[n] ? buf + n + 1 : buf + n;
+    return true;
+}
+
+bool HandState(const std::string &s) { return s == "seen" || s == "lost" || s == "off"; }
+
+}  // namespace
+
+int main(int argc, char **argv) {
+    bool watchStdin = false, noVr = false;
+    std::string sockName = "ft_handpanel", dumpDir;
+    double distance = 1.2;
+    for (int i = 1; i < argc; ++i) {
+        if (!std::strcmp(argv[i], "--watch-stdin")) watchStdin = true;
+        else if (!std::strcmp(argv[i], "--no-vr")) noVr = true;
+        else if (!std::strcmp(argv[i], "--socket") && i + 1 < argc) sockName = argv[++i];
+        else if (!std::strcmp(argv[i], "--distance") && i + 1 < argc) distance = std::clamp(std::atof(argv[++i]), 0.5, 5.0);
+        else if (!std::strcmp(argv[i], "--dump") && i + 1 < argc) dumpDir = argv[++i];
+        else {
+            std::fprintf(stderr, "usage: %s [--watch-stdin] [--socket NAME] [--distance METRES] [--no-vr [--dump DIR]]\n",
+                         argv[0]);
+            return 2;
+        }
+    }
+    std::signal(SIGINT, [](int) { g_stop = true; });
+    std::signal(SIGTERM, [](int) { g_stop = true; });
+    if (watchStdin)
+        std::thread([] {
+            char c[256];
+            while (read(0, c, sizeof c) > 0) {
+            }
+            g_stop = true;
+        }).detach();
+
+    int sock = socket(AF_UNIX, SOCK_DGRAM | SOCK_CLOEXEC | SOCK_NONBLOCK, 0);
+    sockaddr_un addr{};
+    addr.sun_family = AF_UNIX;
+    std::memcpy(addr.sun_path + 1, sockName.data(), std::min(sockName.size(), sizeof addr.sun_path - 2));
+    if (bind(sock, reinterpret_cast<sockaddr *>(&addr), socklen_t(offsetof(sockaddr_un, sun_path) + 1 + sockName.size())) != 0) {
+        std::fprintf(stderr, "ft-handpanel: @%s is taken (another copy running?)\n", sockName.c_str());
+        return 1;
+    }
+
+    vr::IVROverlay *ov = nullptr;
+    vr::VROverlayHandle_t h = vr::k_ulOverlayHandleInvalid, th = vr::k_ulOverlayHandleInvalid;
+    Buffers buffers, targetBuffers;
+    if (!noVr) {
+        // As Frametop's other SteamVR clients: background first, so we never start vrserver.
+        vr::EVRInitError err = vr::VRInitError_None;
+        vr::VR_Init(&err, vr::VRApplication_Background);
+        if (err == vr::VRInitError_None) {
+            vr::VR_Shutdown();
+            vr::VR_Init(&err, vr::VRApplication_Overlay);
+        }
+        if (err != vr::VRInitError_None) {
+            std::fprintf(stderr, "ft-handpanel: SteamVR: %s\n", vr::VR_GetVRInitErrorAsEnglishDescription(err));
+            return 1;
+        }
+        ov = vr::VROverlay();
+        if (ov->CreateOverlay("frametop.handpanel", "Frametop hand recorder", &h) != vr::VROverlayError_None ||
+            ov->CreateOverlay("frametop.handpanel.target", "Frametop hand recorder target", &th) != vr::VROverlayError_None) {
+            std::fprintf(stderr, "ft-handpanel: can't create the overlays (another copy running?)\n");
+            return 1;
+        }
+        ov->SetOverlaySortOrder(h, 250);  // in front of Frametop's screens and the pointer's dot
+        ov->SetOverlaySortOrder(th, 250);
+        if (buffers.Make(kW, kH)) ov->SetOverlayFlag(h, vr::VROverlayFlags_IsPremultiplied, true);
+        if (targetBuffers.Make(kTargetPx, kTargetPx)) ov->SetOverlayFlag(th, vr::VROverlayFlags_IsPremultiplied, true);
+        // Fixed to the head: distance along a line UP_DEG above straight ahead, tilted back by
+        // as much so it faces the eyes square on.
+        const double up = kUpDeg * M_PI / 180;
+        vr::HmdMatrix34_t m{};
+        m.m[0][0] = 1;
+        m.m[1][1] = float(std::cos(up)), m.m[1][2] = float(-std::sin(up));
+        m.m[2][1] = float(std::sin(up)), m.m[2][2] = float(std::cos(up));
+        m.m[1][3] = float(distance * std::sin(up)), m.m[2][3] = float(-distance * std::cos(up));
+        ov->SetOverlayTransformTrackedDeviceRelative(h, vr::k_unTrackedDeviceIndex_Hmd, &m);
+        ov->SetOverlayWidthInMeters(h, float(2 * distance * std::tan(kWidthDeg * M_PI / 360)));
+        ov->SetOverlayWidthInMeters(th, float(kTargetM));
+    }
+    LoadFont();
+
+    Panel p;
+    Target t;
+    PoseLog poseLog;
+    bool visible = false, dirty = false, shown = false;  // shown: SteamVR shows it (after its first picture)
+    bool targetDirty = false, targetShown = false;
+    int pictures = 0;
+    std::fprintf(stderr, "ft-handpanel running: @%s, %.2f m%s\n", sockName.c_str(), distance, noVr ? ", no VR" : "");
+
+    while (!g_stop) {
+        pollfd pfd{sock, POLLIN, 0};
+        poll(&pfd, 1, 50);
+        char buf[4096];
+        sockaddr_un from{};
+        socklen_t fromLen = sizeof from;
+        ssize_t n;
+        while ((n = recvfrom(sock, buf, sizeof buf - 1, 0, reinterpret_cast<sockaddr *>(&from), &fromLen)) > 0) {
+            while (n > 0 && (buf[n - 1] == '\n' || buf[n - 1] == '\r')) --n;  // from echo or socat
+            buf[n] = 0;
+            std::string reply = "ok";
+            const char *rest = nullptr;
+            double a = 0, b = 0, c = 0;
+            int used = 0;
+            if (Is(buf, "show")) {
+                visible = dirty = true;  // shown with its first picture
+            } else if (Is(buf, "hide")) {
+                if (ov) {
+                    std::lock_guard<std::mutex> lk(g_vr);
+                    ov->HideOverlay(h);
+                }
+                if (noVr && visible) std::printf("--- panel hidden\n"), std::fflush(stdout);
+                visible = shown = false;
+            } else if (Is(buf, "title", &rest)) {
+                p.title = rest, dirty = true;
+            } else if (Is(buf, "step", &rest)) {
+                p.step = rest, dirty = true;
+            } else if (Is(buf, "text", &rest)) {
+                p.text = rest, dirty = true;
+            } else if (Is(buf, "note", &rest)) {
+                p.note = rest, dirty = true;
+            } else if (Is(buf, "countdown", &rest)) {
+                if (!std::strcmp(rest, "off")) p.countdown = -1, dirty = true;
+                else if (std::sscanf(rest, "%lf", &a) == 1) p.countdown = std::clamp(a, 0.0, 1.0), dirty = true;
+                else reply = "error usage: countdown <0..1>|off";
+            } else if (Is(buf, "hands", &rest)) {
+                char l[16] = "", r[16] = "";
+                if (std::sscanf(rest, "%15s %15s", l, r) == 2 && HandState(l) && HandState(r))
+                    p.hands[0] = l, p.hands[1] = r, dirty = true;
+                else reply = "error usage: hands seen|lost|off seen|lost|off";
+            } else if (Is(buf, "bar", &rest)) {
+                if (!std::strcmp(rest, "off")) {
+                    p.barOn = false, dirty = true;
+                } else if (std::sscanf(rest, "%lf %lf%n", &a, &b, &used) == 2) {
+                    p.barOn = true, p.barTarget = std::clamp(a, 0.0, 1.0), p.barCurrent = b < 0 ? -1 : std::min(b, 1.0);
+                    std::string labels = rest + used;
+                    labels.erase(0, std::min(labels.find_first_not_of(' '), labels.size()));
+                    if (!labels.empty()) {
+                        size_t cut = labels.find('|');
+                        if (cut == std::string::npos) cut = labels.find(' ');
+                        p.nearLabel = labels.substr(0, cut);
+                        p.farLabel = cut == std::string::npos ? "Far" : labels.substr(cut + 1);
+                    } else {
+                        p.nearLabel = "Near", p.farLabel = "Far";
+                    }
+                    dirty = true;
+                } else {
+                    reply = "error usage: bar <target 0..1> <current 0..1|-1> [near label] [far label] | bar off";
+                }
+            } else if (Is(buf, "paused", &rest)) {
+                if (!std::strcmp(rest, "on") || !std::strcmp(rest, "off")) p.paused = rest[1] == 'n', dirty = true;
+                else reply = "error usage: paused on|off";
+            } else if (Is(buf, "rec", &rest)) {
+                if (!std::strcmp(rest, "on") || !std::strcmp(rest, "off")) p.rec = rest[1] == 'n', dirty = true;
+                else reply = "error usage: rec on|off";
+            } else if (Is(buf, "action", &rest)) {
+                p.action = rest, dirty = true;
+            } else if (Is(buf, "big", &rest)) {
+                p.big = rest, dirty = true;
+            } else if (Is(buf, "keys", &rest)) {
+                p.keys = rest, dirty = true;
+            } else if (Is(buf, "image", &rest)) {
+                // image <path> [mirror|both]: the path may hold spaces, the mode is the last word
+                std::string path = rest, mode;
+                for (const char *m : {" mirror", " both"}) {
+                    const size_t n = std::strlen(m);
+                    if (path.size() > n && !path.compare(path.size() - n, n, m)) mode = m + 1, path.resize(path.size() - n);
+                }
+                if (path.empty()) {
+                    reply = "error usage: image <path> [mirror|both] | image off";
+                } else if (path == "off") {
+                    p.image = Image{}, p.imageMode.clear(), dirty = true;
+                } else if (path != p.image.path && !LoadImage(p.image, path)) {
+                    reply = "error can't read " + path + ": " + stbi_failure_reason();
+                    p.imageMode.clear(), dirty = true;  // no picture rather than the last one
+                } else {
+                    p.imageMode = mode, dirty = true;
+                }
+            } else if (Is(buf, "strip", &rest)) {
+                // strip <cue> <path>|<mode>|<label>;...
+                int cue = -1, used = 0;
+                if (!std::strcmp(rest, "off")) {
+                    p.strip.clear(), p.stripCue = -1, dirty = true;
+                } else if (std::sscanf(rest, "%d %n", &cue, &used) >= 1 && rest[used]) {
+                    std::vector<StripItem> items;
+                    std::string all = rest + used;
+                    for (size_t at = 0; at <= all.size();) {
+                        const size_t end = std::min(all.find(';', at), all.size());
+                        const std::string item = all.substr(at, end - at);
+                        at = end + 1;
+                        if (item.empty()) continue;
+                        const size_t a1 = item.find('|'), a2 = a1 == std::string::npos ? a1 : item.find('|', a1 + 1);
+                        StripItem it;
+                        it.path = item.substr(0, a1);
+                        if (a1 != std::string::npos) it.mode = item.substr(a1 + 1, a2 == std::string::npos ? a2 : a2 - a1 - 1);
+                        if (a2 != std::string::npos) it.label = item.substr(a2 + 1);
+                        if (it.path == "-") it.path.clear();
+                        if (it.mode == "-") it.mode.clear();
+                        items.push_back(it);
+                    }
+                    if (items.empty()) {
+                        reply = "error usage: strip <cue> <path>|<mode>|<label>;... | strip off";
+                    } else {
+                        for (const StripItem &it : items)
+                            if (!it.path.empty() && StripImage(it.path).path.empty()) reply = "error can't read " + it.path;
+                        p.strip = items, p.stripCue = cue, dirty = true;
+                    }
+                } else {
+                    reply = "error usage: strip <cue> <path>|<mode>|<label>;... | strip off";
+                }
+            } else if (Is(buf, "where", &rest)) {
+                char pos[16] = "", dist[16] = "";
+                if (!std::strcmp(rest, "off")) {
+                    p.wherePos.clear(), p.whereDist.clear(), dirty = true;
+                } else if (std::sscanf(rest, "%15s %15s", pos, dist) >= 1) {
+                    p.wherePos = std::strcmp(pos, "-") ? pos : "";
+                    p.whereDist = *dist && std::strcmp(dist, "-") ? dist : "";
+                    dirty = true;
+                } else {
+                    reply = "error usage: where <position|-> <distance|-> | where off";
+                }
+            } else if (Is(buf, "target", &rest)) {
+                char state[16] = "show";
+                double prog = 0;
+                const int got = std::sscanf(rest, "%lf %lf %lf %15s %lf", &a, &b, &c, state, &prog);
+                const std::string st = state;
+                if (!std::strcmp(rest, "off")) {
+                    if (ov && targetShown) {
+                        std::lock_guard<std::mutex> lk(g_vr);
+                        ov->HideOverlay(th);
+                    }
+                    if (noVr && t.on) targetDirty = true;
+                    t.on = t.placed = targetShown = false;
+                } else if (got < 3 || (st != "show" && st != "hold" && st != "done") || (st == "hold" && got < 5)) {
+                    reply = "error usage: target <x> <y> <z> [show|hold <0..1>|done] | target off";
+                } else {
+                    // A new point goes into the room where the head is now, and stays there.
+                    const bool same = t.placed && a == t.head[0] && b == t.head[1] && c == t.head[2];
+                    vr::HmdMatrix34_t m{};
+                    m.m[0][0] = m.m[1][1] = m.m[2][2] = 1;  // --no-vr: the head at the room's origin
+                    if (!same && !noVr && !HeadPose(m)) {
+                        reply = "error no head pose";
+                    } else {
+                        if (!same) {
+                            const double head[3] = {a, b, c}, eye[3] = {m.m[0][3], m.m[1][3], m.m[2][3]};
+                            for (int r = 0; r < 3; ++r) {
+                                t.head[r] = head[r];
+                                t.room[r] = m.m[r][0] * a + m.m[r][1] * b + m.m[r][2] * c + m.m[r][3];
+                            }
+                            if (ov) {
+                                const vr::HmdMatrix34_t at = Facing(t.room, eye);
+                                std::lock_guard<std::mutex> lk(g_vr);
+                                ov->SetOverlayTransformAbsolute(th, vr::TrackingUniverseStanding, &at);
+                            }
+                            t.placed = true;
+                        }
+                        t.on = true, t.state = st, t.progress = st == "hold" ? std::clamp(prog, 0.0, 1.0) : 0;
+                        targetDirty = true;
+                        char out[96];
+                        std::snprintf(out, sizeof out, "ok %.4f %.4f %.4f", t.room[0], t.room[1], t.room[2]);
+                        reply = out;
+                    }
+                }
+            } else if (Is(buf, "poses", &rest)) {
+                const char *path = nullptr;
+                if (Is(rest, "start", &path) && *path) {
+                    // --no-vr writes nothing: there are no poses.
+                    if (!noVr && !poseLog.Start(path)) reply = std::string("error can't open ") + path + ": " + std::strerror(errno);
+                } else if (Is(rest, "stop")) {
+                    reply = "ok " + std::to_string(poseLog.Stop());
+                } else {
+                    reply = "error usage: poses start <path> | poses stop";
+                }
+            } else if (Is(buf, "devices")) {
+                if (noVr) {
+                    reply = "error no VR (--no-vr)";
+                } else {
+                    vr::TrackedDevicePose_t poses[vr::k_unMaxTrackedDeviceCount];
+                    vr::TrackedDeviceIndex_t idx[3] = {vr::k_unTrackedDeviceIndex_Hmd, 0, 0};
+                    {
+                        std::lock_guard<std::mutex> lk(g_vr);
+                        auto *sys = vr::VRSystem();
+                        idx[1] = sys->GetTrackedDeviceIndexForControllerRole(vr::TrackedControllerRole_LeftHand);
+                        idx[2] = sys->GetTrackedDeviceIndexForControllerRole(vr::TrackedControllerRole_RightHand);
+                        sys->GetDeviceToAbsoluteTrackingPose(vr::TrackingUniverseStanding, 0, poses, vr::k_unMaxTrackedDeviceCount);
+                    }
+                    reply = "ok";
+                    const char *names[3] = {"hmd", "left", "right"};
+                    for (int k = 0; k < 3; ++k) {
+                        const bool there = idx[k] < vr::k_unMaxTrackedDeviceCount && poses[idx[k]].bDeviceIsConnected;
+                        reply += std::string(" ") + names[k] + " " + (there ? std::to_string(int(poses[idx[k]].eTrackingResult)) : "-");
+                    }
+                }
+            } else if (Is(buf, "head")) {
+                vr::HmdMatrix34_t m;
+                if (noVr) {
+                    reply = "error no VR (--no-vr)";
+                } else if (!HeadPose(m)) {
+                    reply = "error no head pose";
+                } else {
+                    char out[256];
+                    int len = std::snprintf(out, sizeof out, "ok");
+                    for (int i = 0; i < 12; ++i) len += std::snprintf(out + len, sizeof out - len, " %.6f", m.m[i / 4][i % 4]);
+                    reply = out;
+                }
+            } else if (Is(buf, "ping")) {
+                reply = visible ? "ok shown" : "ok hidden";
+            } else {
+                reply = "error unknown command";
+            }
+            if (fromLen > offsetof(sockaddr_un, sun_path))
+                sendto(sock, reply.data(), reply.size(), 0, reinterpret_cast<sockaddr *>(&from), fromLen);
+            fromLen = sizeof from;
+        }
+        if (!noVr) {
+            std::lock_guard<std::mutex> lk(g_vr);
+            vr::VREvent_t ev;
+            while (vr::VRSystem()->PollNextEvent(&ev, sizeof ev))
+                if (ev.eventType == vr::VREvent_Quit) {
+                    vr::VRSystem()->AcknowledgeQuit_Exiting();
+                    g_stop = true;
+                }
+        }
+        const bool panelNow = visible && dirty, targetNow = targetDirty;
+        if (panelNow) {
+            Draw(p);
+            if (ov) {
+                buffers.Present(ov, h, p.pic);
+                std::lock_guard<std::mutex> lk(g_vr);
+                if (!shown) ov->ShowOverlay(h), shown = true;
+            }
+            dirty = false;
+        }
+        if (targetNow) {
+            if (t.on) {
+                DrawTarget(t);
+                if (ov) {
+                    targetBuffers.Present(ov, th, t.pic);
+                    std::lock_guard<std::mutex> lk(g_vr);
+                    if (!targetShown) ov->ShowOverlay(th), targetShown = true;
+                }
+            }
+            targetDirty = false;
+        }
+        if (noVr && (panelNow || targetNow)) {
+            Print(p, t, visible, ++pictures);
+            if (!dumpDir.empty() && panelNow) Dump(p.pic, dumpDir + "/panel.pam");
+            if (!dumpDir.empty() && targetNow && t.on) Dump(t.pic, dumpDir + "/target.pam");
+        }
+    }
+    poseLog.Stop();
+    if (ov) {
+        ov->DestroyOverlay(h);
+        ov->DestroyOverlay(th);
+        buffers.Drop();
+        targetBuffers.Drop();
+        vr::VR_Shutdown();
+    }
+    return 0;
+}
diff --git a/hands/rec/poses/README.md b/hands/rec/poses/README.md
new file mode 100644
index 0000000..5050773
--- /dev/null
+++ b/hands/rec/poses/README.md
@@ -0,0 +1,52 @@
+# Pose images for the hand recorder
+
+Small pictures of each hand pose in `script.json`, shown on the headset panel next to the prompt text.
+
+- `<id>.png`: one image per pose, 512x512 RGBA with a transparent background. Made for a dark panel and still readable at about 250 px.
+- `poses.json`: maps each pose id to `{"file", "two_hands", "caption"}`.
+- `contact-sheet.png`: every image in a grid with its id, for review. The panel doesn't use it.
+- `make_poses.py`: the generator that makes all of the above.
+
+## How the images are drawn
+
+Every image shows a right hand as the wearer sees it from their own eyes. "Palm toward you" shows the palm, with its creases. "Back toward you" shows the back of the hand, with the nails and knuckles. Fingers point up unless the pose says otherwise.
+
+- **Left-hand prompts:** the panel mirrors the image horizontally.
+- **"Both" prompts:** the panel shows two copies, one of them mirrored.
+- **`two_hands: true`:** the image already shows the whole scene: both hands, or one hand with an object, as in `hold`. Show it once, without mirroring or copying. This applies to `cross`, `overlap`, `near-face`, `typing`, `lift`, `switch`, `hold`, `push`, `push-controller`, `touch-stick` and `touch-stick-desk`.
+- **`touch-stick`:** shows the left hand holding the controller while the right index touches its thumbstick. For prompts where the right hand holds the controller (`controllers: ["right"]`), mirror it.
+
+`push` and `push-controller` are side views: the wearer's head with a headset on, one arm out in front with the palm out, a ghost of the hand further out, and a straight double arrow from the headset outward, labelled "near" and "arm out". The labels use Pillow's built-in font.
+
+Other motion poses show the start pose, a faint blue "ghost" of the end pose, and orange arrows. Objects (keyboard, mouse, bottle, bar, controller, screen, head and headset) are plain grey shapes.
+
+Besides the pose ids in `script.json`, these extra ids exist for prompts that need a different picture:
+
+| id | for |
+| --- | --- |
+| `push` | the bar sections: push straight out from the headset and back, palms out |
+| `push-controller` | the same with controllers on |
+| `touch-stick-desk` | touching the thumbstick of a controller lying on the desk |
+| `no-hands` | the no-hands section: hands down, out of view |
+| `open-close` | already used by the bar sections |
+
+`count-5` is the same picture as `spread`.
+
+## Regenerating
+
+You need Python 3 with numpy and Pillow. The script uses about one core-minute per image at the default quality, so don't run it on the headset. Run it on a build machine:
+
+```sh
+python3 -m venv venv && venv/bin/pip install numpy pillow
+venv/bin/python make_poses.py --jobs 6              # all images, poses.json, contact sheet
+venv/bin/python make_poses.py --only fist,ok        # just some (poses.json is left alone)
+venv/bin/python make_poses.py --ss 1 --jobs 6       # rough and about 8x faster, for trying things
+```
+
+`--out DIR` writes somewhere other than this folder.
+
+Each pose is a short entry in the `POSES` table in `make_poses.py`: a caption, the `two_hands` flag, and a function that returns the scene. A scene is the camera, layers of hands and objects (a layer can be a faint ghost), and arrows. Hands are built from joint angles: flexion at each finger's three joints, sideways spread, and four thumb angles. A thumb can also be given a target point, such as "touch the index fingertip", and a small solver finds the angles. The presets near `FLAT`, `FIST` and `OK` are a good place to start a new pose.
+
+## License
+
+MIT, like the rest of the repository. The script draws everything itself. A hand made of a palm slab and tapered capsules is ray-marched as a signed distance field, then shaded and outlined. No photos, downloaded images, scanned or research hand models, or AI image generators are involved, so the images carry no other terms.
diff --git a/hands/rec/poses/bend.png b/hands/rec/poses/bend.png
new file mode 100644
index 0000000..6c12bef
Binary files /dev/null and b/hands/rec/poses/bend.png differ
diff --git a/hands/rec/poses/claw.png b/hands/rec/poses/claw.png
new file mode 100644
index 0000000..2e8b157
Binary files /dev/null and b/hands/rec/poses/claw.png differ
diff --git a/hands/rec/poses/contact-sheet.png b/hands/rec/poses/contact-sheet.png
new file mode 100644
index 0000000..1085d06
Binary files /dev/null and b/hands/rec/poses/contact-sheet.png differ
diff --git a/hands/rec/poses/count-1.png b/hands/rec/poses/count-1.png
new file mode 100644
index 0000000..cd583fc
Binary files /dev/null and b/hands/rec/poses/count-1.png differ
diff --git a/hands/rec/poses/count-2.png b/hands/rec/poses/count-2.png
new file mode 100644
index 0000000..cdc0a13
Binary files /dev/null and b/hands/rec/poses/count-2.png differ
diff --git a/hands/rec/poses/count-3.png b/hands/rec/poses/count-3.png
new file mode 100644
index 0000000..e28aa39
Binary files /dev/null and b/hands/rec/poses/count-3.png differ
diff --git a/hands/rec/poses/count-4.png b/hands/rec/poses/count-4.png
new file mode 100644
index 0000000..0b2f9f8
Binary files /dev/null and b/hands/rec/poses/count-4.png differ
diff --git a/hands/rec/poses/count-5.png b/hands/rec/poses/count-5.png
new file mode 100644
index 0000000..e56012a
Binary files /dev/null and b/hands/rec/poses/count-5.png differ
diff --git a/hands/rec/poses/cross.png b/hands/rec/poses/cross.png
new file mode 100644
index 0000000..b426c3d
Binary files /dev/null and b/hands/rec/poses/cross.png differ
diff --git a/hands/rec/poses/fist.png b/hands/rec/poses/fist.png
new file mode 100644
index 0000000..f2a85fc
Binary files /dev/null and b/hands/rec/poses/fist.png differ
diff --git a/hands/rec/poses/flat-back.png b/hands/rec/poses/flat-back.png
new file mode 100644
index 0000000..9a08f9c
Binary files /dev/null and b/hands/rec/poses/flat-back.png differ
diff --git a/hands/rec/poses/flat.png b/hands/rec/poses/flat.png
new file mode 100644
index 0000000..8a90a8a
Binary files /dev/null and b/hands/rec/poses/flat.png differ
diff --git a/hands/rec/poses/grab.png b/hands/rec/poses/grab.png
new file mode 100644
index 0000000..5bb95f2
Binary files /dev/null and b/hands/rec/poses/grab.png differ
diff --git a/hands/rec/poses/hold.png b/hands/rec/poses/hold.png
new file mode 100644
index 0000000..67ee2d3
Binary files /dev/null and b/hands/rec/poses/hold.png differ
diff --git a/hands/rec/poses/lift.png b/hands/rec/poses/lift.png
new file mode 100644
index 0000000..b508059
Binary files /dev/null and b/hands/rec/poses/lift.png differ
diff --git a/hands/rec/poses/make_poses.py b/hands/rec/poses/make_poses.py
new file mode 100644
index 0000000..8c2b485
--- /dev/null
+++ b/hands/rec/poses/make_poses.py
@@ -0,0 +1,1374 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 DeeJanuz
+"""Example pose images for the hand recorder's headset panel.
+
+Everything here is drawn by this script: a simple parametric hand (a palm
+slab and tapered capsules for the finger bones), posed with joint angles,
+ray-marched as a signed distance field with numpy, shaded and outlined.
+No outside images, hand models or image generators.
+
+    python3 make_poses.py                     # all poses into this folder
+    python3 make_poses.py --only fist,ok      # some of them
+    python3 make_poses.py --size 256 --ss 1   # quick, rough preview
+
+Writes <id>.png (RGBA, transparent), poses.json and contact-sheet.png.
+Needs numpy and Pillow. It is CPU heavy (about a minute per image on one
+core), so run it on a build machine, not on the headset.
+"""
+
+import argparse
+import json
+import math
+import os
+import sys
+from concurrent.futures import ProcessPoolExecutor
+
+for _v in ("OMP_NUM_THREADS", "OPENBLAS_NUM_THREADS", "MKL_NUM_THREADS"):
+    os.environ.setdefault(_v, "1")  # one thread per process: --jobs sets the parallelism
+
+import numpy as np  # noqa: E402
+from PIL import Image, ImageDraw, ImageFont  # noqa: E402
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+# ------------------------------------------------------------------ math
+
+
+def Rx(a):
+    a = math.radians(a)
+    c, s = math.cos(a), math.sin(a)
+    return np.array([[1, 0, 0], [0, c, -s], [0, s, c]], float)
+
+
+def Ry(a):
+    a = math.radians(a)
+    c, s = math.cos(a), math.sin(a)
+    return np.array([[c, 0, s], [0, 1, 0], [-s, 0, c]], float)
+
+
+def Rz(a):
+    a = math.radians(a)
+    c, s = math.cos(a), math.sin(a)
+    return np.array([[c, -s, 0], [s, c, 0], [0, 0, 1]], float)
+
+
+def unit(v):
+    v = np.asarray(v, float)
+    return v / np.linalg.norm(v)
+
+
+def orient(f, p):
+    """Hand rotation: fingers along f, palm facing p (right hand: thumb = f x p)."""
+    f = unit(f)
+    p = np.asarray(p, float)
+    p = unit(p - f * (p @ f))
+    return np.column_stack([np.cross(f, p), f, p])
+
+
+V = lambda *a: np.array(a, float)  # noqa: E731
+
+
+def smin(a, b, k):
+    if k <= 0:
+        return np.minimum(a, b)
+    h = np.clip(0.5 + 0.5 * (b - a) / k, 0.0, 1.0)
+    return b + (a - b) * h - k * h * (1.0 - h)
+
+
+# ------------------------------------------------------------------ SDF nodes
+# Every node maps points P (N,3) to signed distances (N,). Units are cm.
+# xf(M, t) returns a copy moved by p -> M p + t (M orthonormal, may mirror).
+
+
+class Cone:
+    """Round cone (tapered capsule) from a (radius r1) to b (radius r2)."""
+
+    def __init__(s, a, b, r1, r2):
+        s.a, s.b, s.r1, s.r2 = V(*a), V(*b), float(r1), float(r2)
+
+    def xf(s, M, t):
+        return Cone(M @ s.a + t, M @ s.b + t, s.r1, s.r2)
+
+    def bounds(s):
+        return [((s.a + s.b) / 2, np.linalg.norm(s.b - s.a) / 2 + max(s.r1, s.r2))]
+
+    def d(s, P):
+        ba = s.b - s.a
+        l2 = ba @ ba
+        rr = s.r1 - s.r2
+        a2 = l2 - rr * rr
+        il2 = 1.0 / l2
+        pa = P - s.a
+        y = pa @ ba
+        z = y - l2
+        q = pa * l2 - y[:, None] * ba
+        x2 = np.einsum("ij,ij->i", q, q)
+        y2 = y * y * l2
+        z2 = z * z * l2
+        k = math.copysign(1.0, rr) * rr * rr * x2 if rr != 0 else np.zeros_like(x2)
+        d1 = np.sqrt(x2 + z2) * il2 - s.r2
+        d2 = np.sqrt(x2 + y2) * il2 - s.r1
+        d3 = (np.sqrt(np.maximum(x2 * a2 * il2, 0.0)) + y * rr) * il2 - s.r1
+        return np.where(np.sign(z) * a2 * z2 > k, d1, np.where(np.sign(y) * a2 * y2 < k, d2, d3))
+
+
+class Box:
+    """Rounded box. R's columns are the box axes. taper: x half-size factor at -y end."""
+
+    def __init__(s, c, R, h, r, taper=None, bulge=0.0):
+        s.c, s.R, s.h, s.r, s.taper, s.bulge = V(*c), np.asarray(R, float), V(*h), float(r), taper, bulge
+
+    def xf(s, M, t):
+        return Box(M @ s.c + t, M @ s.R, s.h, s.r, s.taper, s.bulge)
+
+    def bounds(s):
+        return [(s.c, np.linalg.norm(s.h) + s.r)]
+
+    def d(s, P):
+        L = (P - s.c) @ s.R
+        q = np.abs(L) - s.h
+        if s.taper is not None:
+            tt = np.clip((L[:, 1] + s.h[1]) / (2 * s.h[1]), 0, 1)
+            q[:, 0] = np.abs(L[:, 0]) - s.h[0] * (s.taper + (1 - s.taper) * tt)
+        d = np.linalg.norm(np.maximum(q, 0), axis=1) + np.minimum(q.max(1), 0) - s.r
+        if s.bulge:  # gently convex faces instead of flat ones
+            ex, ey = s.h[0] + s.r, s.h[1] + s.r
+            d = d - s.bulge * np.clip(1 - (L[:, 0] / ex) ** 2, 0, 1) * np.clip(1 - (L[:, 1] / ey) ** 2, 0, 1)
+        return d
+
+
+class Ell:
+    """Ellipsoid (approximate distance)."""
+
+    def __init__(s, c, R, rad):
+        s.c, s.R, s.rad = V(*c), np.asarray(R, float), V(*rad)
+
+    def xf(s, M, t):
+        return Ell(M @ s.c + t, M @ s.R, s.rad)
+
+    def bounds(s):
+        return [(s.c, s.rad.max())]
+
+    def d(s, P):
+        L = (P - s.c) @ s.R
+        k0 = np.linalg.norm(L / s.rad, axis=1)
+        k1 = np.linalg.norm(L / (s.rad * s.rad), axis=1)
+        return k0 * (k0 - 1.0) / np.maximum(k1, 1e-6)
+
+
+class Cyl:
+    """Rounded cylinder along local y: radius ra, half height hh, edge rounding rb."""
+
+    def __init__(s, c, R, ra, hh, rb=0.1):
+        s.c, s.R, s.ra, s.hh, s.rb = V(*c), np.asarray(R, float), ra, hh, rb
+
+    def xf(s, M, t):
+        return Cyl(M @ s.c + t, M @ s.R, s.ra, s.hh, s.rb)
+
+    def bounds(s):
+        return [(s.c, math.hypot(s.ra, s.hh))]
+
+    def d(s, P):
+        L = (P - s.c) @ s.R
+        dx = np.hypot(L[:, 0], L[:, 2]) - s.ra + s.rb
+        dy = np.abs(L[:, 1]) - s.hh + s.rb
+        return np.minimum(np.maximum(dx, dy), 0) + np.hypot(np.maximum(dx, 0), np.maximum(dy, 0)) - s.rb
+
+
+class Torus:
+    """Torus in the local xz plane (axis local y)."""
+
+    def __init__(s, c, R, R1, r2):
+        s.c, s.R, s.R1, s.r2 = V(*c), np.asarray(R, float), R1, r2
+
+    def xf(s, M, t):
+        return Torus(M @ s.c + t, M @ s.R, s.R1, s.r2)
+
+    def bounds(s):
+        return [(s.c, s.R1 + s.r2)]
+
+    def d(s, P):
+        L = (P - s.c) @ s.R
+        return np.hypot(np.hypot(L[:, 0], L[:, 2]) - s.R1, L[:, 1]) - s.r2
+
+
+class Keys:
+    """A grid of nx * nz key caps on the local xz plane (local y up)."""
+
+    def __init__(s, c, R, nx, nz, pitch, kh, r):
+        s.c, s.R, s.nx, s.nz, s.pitch, s.kh, s.r = V(*c), np.asarray(R, float), nx, nz, pitch, V(*kh), r
+
+    def xf(s, M, t):
+        return Keys(M @ s.c + t, M @ s.R, s.nx, s.nz, s.pitch, s.kh, s.r)
+
+    def bounds(s):
+        return [(s.c, math.hypot(s.nx * s.pitch, s.nz * s.pitch) / 2 + 1)]
+
+    def d(s, P):
+        L = (P - s.c) @ s.R
+        cx, cz = (s.nx - 1) / 2, (s.nz - 1) / 2
+        ix = np.clip(np.round(L[:, 0] / s.pitch + cx), 0, s.nx - 1)
+        iz = np.clip(np.round(L[:, 2] / s.pitch + cz), 0, s.nz - 1)
+        q = np.abs(np.stack([L[:, 0] - (ix - cx) * s.pitch, L[:, 1], L[:, 2] - (iz - cz) * s.pitch], 1)) - s.kh
+        return np.linalg.norm(np.maximum(q, 0), axis=1) + np.minimum(q.max(1), 0) - s.r
+
+
+class U:
+    """Union of nodes, smooth when k > 0."""
+
+    def __init__(s, kids, k=0.0):
+        s.kids, s.k = list(kids), k
+
+    def xf(s, M, t):
+        return U([c.xf(M, t) for c in s.kids], s.k)
+
+    def bounds(s):
+        return [b for c in s.kids for b in c.bounds()]
+
+    def d(s, P):
+        d = s.kids[0].d(P)
+        for c in s.kids[1:]:
+            d = smin(d, c.d(P), s.k)
+        return d
+
+
+class Sub:
+    """a minus b."""
+
+    def __init__(s, a, b):
+        s.a, s.b = a, b
+
+    def xf(s, M, t):
+        return Sub(s.a.xf(M, t), s.b.xf(M, t))
+
+    def bounds(s):
+        return s.a.bounds()
+
+    def d(s, P):
+        return np.maximum(s.a.d(P), -s.b.d(P))
+
+
+class Clip:
+    """a cut by the plane through point o with outward normal n (keeps the -n side)."""
+
+    def __init__(s, a, o, n):
+        s.a, s.o, s.n = a, V(*o), unit(n)
+
+    def xf(s, M, t):
+        return Clip(s.a.xf(M, t), M @ s.o + t, M @ s.n)
+
+    def bounds(s):
+        return s.a.bounds()
+
+    def d(s, P):
+        return np.maximum(s.a.d(P), (P - s.o) @ s.n)
+
+
+# ------------------------------------------------------------------ the hand
+# Local frame of a right hand: wrist joint at the origin, fingers along +y,
+# palm facing +z, thumb on the +x side. cm, adult proportions.
+
+FINGERS = [
+    # name, MCP joint, bone lengths (proximal, middle, distal incl. tip), radii (MCP, PIP, DIP, tip)
+    ("index", (2.5, 9.45, 0.0), (4.2, 2.45, 2.1), (1.03, 0.95, 0.85, 0.77)),
+    ("middle", (0.62, 9.85, 0.0), (4.6, 2.85, 2.3), (1.06, 0.98, 0.87, 0.79)),
+    ("ring", (-1.25, 9.5, 0.0), (4.35, 2.7, 2.2), (1.0, 0.92, 0.83, 0.75)),
+    ("pinky", (-2.95, 8.6, 0.0), (3.5, 2.05, 2.0), (0.9, 0.82, 0.74, 0.67)),
+]
+THUMB_CMC = (2.1, 2.3, 0.6)
+THUMB_LENS = (4.6, 3.3, 2.6)
+THUMB_RADII = (1.45, 1.08, 0.98, 0.86)
+PARTS = {"palm": 0, "thumb": 1, "index": 2, "middle": 3, "ring": 4, "pinky": 5, "arm": 7}
+
+SKIN = V(0.93, 0.885, 0.84)
+NAIL = V(1.0, 0.84, 0.82)
+CREASE = V(0.62, 0.55, 0.52)
+# palm creases (hand local x, y on the palm side): they tell the palm from the back
+CREASES = [
+    [(-3.7, 7.3), (-2.0, 7.6), (-0.5, 8.0), (0.8, 8.5), (1.6, 9.1)],
+    [(3.5, 6.9), (2.0, 6.6), (0.5, 6.2), (-1.2, 5.8), (-2.8, 5.5)],
+    [(3.5, 6.9), (2.2, 6.2), (1.3, 5.0), (0.9, 3.5), (0.9, 2.2), (1.2, 0.9)],
+]
+
+
+def crease_dist(xy):
+    d = np.full(len(xy), 1e9)
+    for line in CREASES:
+        for a, b in zip(line[:-1], line[1:]):
+            a, b = V(*a), V(*b)
+            t = np.clip((xy - a) @ (b - a) / ((b - a) @ (b - a)), 0, 1)
+            d = np.minimum(d, np.linalg.norm(xy - (a + t[:, None] * (b - a)), axis=1))
+    return d
+
+
+def thumb_twist(palmar):
+    return -62.0 - 0.45 * palmar
+
+
+def finger_fk(base, lens, radii, ang):
+    mcp, pip, dip, abd = ang
+    F1 = Rz(-abd) @ Rx(mcp)
+    F2 = F1 @ Rx(pip)
+    F3 = F2 @ Rx(dip)
+    p0 = V(*base)
+    p1 = p0 + F1 @ V(0, lens[0], 0)
+    p2 = p1 + F2 @ V(0, lens[1], 0)
+    p3 = p2 + F3 @ V(0, lens[2] - radii[3], 0)
+    return dict(pts=[p0, p1, p2, p3], frames=[F1, F2, F3], radii=radii)
+
+
+def thumb_fk(q, twist=None):
+    spread, palmar, mcp, ip = q
+    tw = thumb_twist(palmar) if twist is None else twist
+    B = Rz(-spread) @ Rx(palmar) @ Ry(tw)
+    F2 = B @ Rx(mcp)
+    F3 = F2 @ Rx(ip)
+    p0 = V(*THUMB_CMC)
+    p1 = p0 + B @ V(0, THUMB_LENS[0], 0)
+    p2 = p1 + F2 @ V(0, THUMB_LENS[1], 0)
+    p3 = p2 + F3 @ V(0, THUMB_LENS[2] - THUMB_RADII[3], 0)
+    return dict(pts=[p0, p1, p2, p3], frames=[B, F2, F3], radii=THUMB_RADII)
+
+
+THUMB_LO = V(-30, -15, -15, -25)
+THUMB_HI = V(85, 85, 70, 85)
+
+
+def thumb_ik(target, prior, twist=None, fixed=()):
+    """Thumb angles that put the thumb tip centre at target (hand local).
+
+    A pattern search, first held close to the prior (which picks the natural
+    solution), then refined from there to hit the target."""
+    target = V(*target)
+    prior = V(*prior)
+
+    def search(q, w, step):
+        def cost(q):
+            tip = thumb_fk(q, twist)["pts"][3]
+            return float(np.sum((tip - target) ** 2) + w * np.sum((q - prior) ** 2))
+
+        c = cost(q)
+        while step > 0.05:
+            better = False
+            for i in range(4):
+                if i in fixed:
+                    continue
+                for sgn in (1, -1):
+                    q2 = q.copy()
+                    q2[i] = np.clip(q2[i] + sgn * step, THUMB_LO[i], THUMB_HI[i])
+                    c2 = cost(q2)
+                    if c2 < c:
+                        q, c, better = q2, c2, True
+            if not better:
+                step *= 0.5
+        return q
+
+    q = search(prior.copy(), 0.003, 16.0)
+    q = search(q, 0.00002, 4.0)
+    err = float(np.linalg.norm(thumb_fk(q, twist)["pts"][3] - target))
+    if err > 0.3:
+        print(f"warning: thumb misses its target by {err:.2f} cm", file=sys.stderr)
+    return q
+
+
+def pad_point(f, gap=0.0, seg=2, at=1.0, thumb_r=THUMB_RADII[3]):
+    """A point just off the pad side of a finger segment (seg 0..2; at 0..1 along it)."""
+    p = f["pts"][seg] + (f["pts"][seg + 1] - f["pts"][seg]) * at
+    r = f["radii"][seg] + (f["radii"][seg + 1] - f["radii"][seg]) * at
+    return p + f["frames"][seg][:, 2] * (r + thumb_r + gap - 0.08)
+
+
+def back_point(f, seg=1, at=0.5, gap=0.0, thumb_r=THUMB_RADII[3]):
+    """A point just off the back (nail side) of a finger segment."""
+    p = f["pts"][seg] + (f["pts"][seg + 1] - f["pts"][seg]) * at
+    r = f["radii"][seg] + (f["radii"][seg + 1] - f["radii"][seg]) * at
+    return p - f["frames"][seg][:, 2] * (r + thumb_r + gap - 0.1)
+
+
+def resolve(pose):
+    """Pose dict -> local joint data. pose['thumb'] is angles or ('to', fn(J) -> point, prior)."""
+    J = {}
+    for name, base, lens, radii in FINGERS:
+        J[name] = finger_fk(base, lens, radii, pose[name])
+    th = pose["thumb"]
+    tw = pose.get("twist")
+    if isinstance(th, tuple) and th and th[0] == "to":
+        q = thumb_ik(th[1](J), th[2], tw, th[3] if len(th) > 3 else ())
+    else:
+        q = V(*th)
+    J["thumb"] = thumb_fk(q, tw)
+    J["thumb_q"] = q
+    return J
+
+
+def chain_nodes(f):
+    p, r = f["pts"], f["radii"]
+    cones = [Cone(p[i], p[i + 1], r[i], r[i + 1]) for i in range(3)]
+    # the nail: a flat ellipsoid on the back of the last bone
+    F = f["frames"][2]
+    j, tip = p[2], p[3]
+    L = np.linalg.norm(tip - j)
+    nail = Ell(j + (tip - j) * 0.8 - F[:, 2] * (r[3] * 0.64), F, (r[3] * 0.72, L * 0.4 + 0.24, 0.32))
+    return cones, nail
+
+
+class Hand:
+    """A posed hand plus forearm, as an SDF scene item."""
+
+    def __init__(s, pose, R=np.eye(3), t=(0, 0, 0), left=False, arm=6.5, wrist=(0, 0), _copy=None):
+        if _copy is not None:
+            return
+        J = resolve(pose)
+        s.J = J
+        wf, wd = pose.get("wrist", wrist)
+        R = np.asarray(R, float)
+        S = np.diag([-1.0, 1, 1]) if left else np.eye(3)
+        Mh = S @ R @ Rx(wf) @ Rz(-wd)
+        Ma = S @ R
+        t = S @ V(*t)
+        s.M, s.t = Mh, t
+        palm = Box((-0.05, 4.95, 0.0), np.eye(3), (2.75, 4.15, 0.35), 1.1, taper=0.74, bulge=0.45)
+        meta_t = Cone(J["thumb"]["pts"][0], J["thumb"]["pts"][1], THUMB_RADII[0], THUMB_RADII[1])
+        heel = Cone((-1.9, 1.6, 0.45), (-2.4, 6.5, 0.35), 1.15, 0.95)
+        knuckles = [Ell(V(*base) + V(0, -0.35, -0.55), np.eye(3), (0.95, 0.9, 0.8)) for _, base, _, _ in FINGERS]
+        s.core = U([U([palm, meta_t, heel], 1.1)] + knuckles, 0.5).xf(Mh, t)
+        s.arm = Box((0, -arm / 2 + 0.6, 0), np.eye(3), (1.25, arm / 2, 0.3), 1.35, bulge=0.2).xf(Ma, t)
+        s.arm_o = Ma @ V(0, 0.6, 0) + t
+        s.arm_dir = Ma @ V(0, -1, 0)
+        s.arm_len = arm
+        s.fingers, s.nails, s.ids = [], [], []
+        for name in ("thumb", "index", "middle", "ring", "pinky"):
+            f = J[name]
+            cones, nail = chain_nodes(f)
+            if name == "thumb":
+                cones = cones[1:]
+            s.fingers.append(U(cones + [nail]).xf(Mh, t))
+            s.nails.append(nail.xf(Mh, t))
+            s.ids.append(PARTS[name])
+        s.k = 0.75
+        s.hid = 0
+
+    def world(s, p):
+        return s.M @ V(*p) + s.t
+
+    def joint(s, name, i):
+        return s.world(s.J[name]["pts"][i])
+
+    def xf(s, M, t):
+        h = Hand(None, _copy=True)
+        h.J = s.J
+        h.M, h.t = M @ s.M, M @ s.t + t
+        h.core, h.arm = s.core.xf(M, t), s.arm.xf(M, t)
+        h.arm_o, h.arm_dir, h.arm_len = M @ s.arm_o + t, M @ s.arm_dir, s.arm_len
+        h.fingers = [f.xf(M, t) for f in s.fingers]
+        h.nails = [n.xf(M, t) for n in s.nails]
+        h.ids, h.k, h.hid = s.ids, s.k, s.hid
+        return h
+
+    def bounds(s):
+        out = s.core.bounds() + s.arm.bounds()
+        for f in s.fingers:
+            out += f.bounds()
+        return out
+
+    def _palm(s, P):
+        return smin(s.core.d(P), s.arm.d(P), 1.0)
+
+    def d(s, P):
+        dp = s._palm(P)
+        out = dp
+        for f in s.fingers:
+            out = np.minimum(out, smin(dp, f.d(P), s.k))
+        return out
+
+    def info(s, P):
+        ds = [s.core.d(P), s.arm.d(P)] + [f.d(P) for f in s.fingers]
+        ids = np.array([PARTS["palm"], PARTS["arm"]] + s.ids)[np.argmin(np.stack(ds), 0)]
+        col = np.tile(SKIN, (len(P), 1))
+        nail = np.zeros(len(P), bool)
+        for pid, n in zip(s.ids, s.nails):
+            nail |= (ids == pid) & (n.d(P) < 0.03)
+        col[nail] = NAIL
+        palm = ids == PARTS["palm"]
+        if palm.any():
+            Lc = (P[palm] - s.t) @ s.M
+            w = np.clip(1 - crease_dist(Lc[:, :2]) / 0.13, 0, 1) * np.clip((Lc[:, 2] - 0.9) / 0.4, 0, 1)
+            col[palm] = col[palm] * (1 - w[:, None]) + CREASE * w[:, None]
+        along = (P - s.arm_o) @ s.arm_dir
+        fade = np.clip((s.arm_len - 0.4 - along) / (s.arm_len * 0.55), 0, 1)
+        fade = fade * fade * (3 - 2 * fade)
+        return s.hid * 16 + ids, col, fade, nail
+
+
+class Obj:
+    """A plain object: one SDF node, one colour."""
+
+    def __init__(s, node, color=(0.56, 0.6, 0.67), oid=0):
+        s.node, s.color, s.oid = node, V(*color), oid
+
+    def xf(s, M, t):
+        return Obj(s.node.xf(M, t), s.color, s.oid)
+
+    def bounds(s):
+        return s.node.bounds()
+
+    def d(s, P):
+        return s.node.d(P)
+
+    def info(s, P):
+        n = len(P)
+        return np.full(n, 100 + s.oid), np.tile(s.color, (n, 1)), np.ones(n), np.zeros(n, bool)
+
+
+# ------------------------------------------------------------------ rendering
+
+LIGHT = unit((-0.45, 0.7, 0.6))
+INK = V(0.1, 0.11, 0.13)
+
+
+def scene_d(items, P):
+    d = items[0].d(P)
+    for it in items[1:]:
+        d = np.minimum(d, it.d(P))
+    return d
+
+
+def to_cam(items, cam):
+    return [it.xf(cam["R"], V(0, 0, 0)) for it in items]
+
+
+def march(items, cam, W, ss):
+    """Orthographic sphere tracing along -z in camera space. Returns per-pixel buffers."""
+    s = cam["scale"] / ss
+    Wp = W * ss
+    cx, cy = cam["center"]
+    bs = [b for it in items for b in it.bounds()]
+    C = np.array([b[0] for b in bs])
+    Rr = np.array([b[1] for b in bs])
+    zmin = (C[:, 2] - Rr).min() - 0.1
+    px0 = int(max(0, math.floor(((C[:, 0] - Rr).min() - cx) / s + Wp / 2)))
+    px1 = int(min(Wp, math.ceil(((C[:, 0] + Rr).max() - cx) / s + Wp / 2)))
+    py0 = int(max(0, math.floor((cy - (C[:, 1] + Rr).max()) / s + Wp / 2)))
+    py1 = int(min(Wp, math.ceil((cy - (C[:, 1] - Rr).min()) / s + Wp / 2)))
+    out = dict(hit=np.zeros((Wp, Wp), bool), z=np.full((Wp, Wp), -1e9), id=np.full((Wp, Wp), -1, int),
+               rgb=np.zeros((Wp, Wp, 3)), fade=np.zeros((Wp, Wp)), nail=np.zeros((Wp, Wp), bool))
+    if px1 <= px0 or py1 <= py0:
+        return out
+    us = cx + (np.arange(px0, px1) + 0.5 - Wp / 2) * s
+    vs = cy - (np.arange(py0, py1) + 0.5 - Wp / 2) * s
+    UU, VV = np.meshgrid(us, vs)
+    n = UU.size
+    P = np.zeros((n, 3))
+    P[:, 0], P[:, 1] = UU.ravel(), VV.ravel()
+    zst = np.full(n, -1e9)
+    for c, r in bs:  # start each ray where it enters the first bounding sphere
+        dd = r * r - (P[:, 0] - c[0]) ** 2 - (P[:, 1] - c[1]) ** 2
+        ok = dd > 0
+        zst[ok] = np.maximum(zst[ok], c[2] + np.sqrt(dd[ok]))
+    act = np.nonzero(zst > -1e8)[0]
+    P[:, 2] = zst + 0.05
+    hit = np.zeros(n, bool)
+    eps = 0.0025
+    for _ in range(320):
+        if act.size == 0:
+            break
+        d = scene_d(items, P[act])
+        h = d < eps
+        hit[act[h]] = True
+        z = P[act, 2] - d * 0.9
+        P[act[~h], 2] = z[~h]
+        act = act[(~h) & (z > zmin)]
+    if act.size:
+        d = scene_d(items, P[act])
+        hit[act[d < 0.03]] = True
+    hi = np.nonzero(hit)[0]
+    if hi.size == 0:
+        return out
+    Ph = P[hi]
+    # normals (tetrahedron)
+    e = 0.01
+    K = np.array([[1, -1, -1], [-1, -1, 1], [-1, 1, -1], [1, 1, 1]], float)
+    N = np.zeros_like(Ph)
+    for k in K:
+        N += k * scene_d(items, Ph + k * e)[:, None]
+    N /= np.maximum(np.linalg.norm(N, axis=1, keepdims=True), 1e-9)
+    # ambient occlusion
+    occ = np.zeros(len(Ph))
+    for i in range(5):
+        hh = 0.15 + 0.45 * i
+        occ += (hh - scene_d(items, Ph + N * hh)) * (0.8 ** i)
+    ao = np.clip(1.0 - 0.32 * occ, 0, 1)
+    # soft shadow toward the key light
+    sh = np.ones(len(Ph))
+    t = np.full(len(Ph), 0.12)
+    a2 = np.arange(len(Ph))
+    P0 = Ph + N * 0.03
+    for _ in range(40):
+        if a2.size == 0:
+            break
+        hq = scene_d(items, P0[a2] + LIGHT * t[a2, None])
+        sh[a2] = np.minimum(sh[a2], 7.0 * hq / t[a2])
+        t[a2] += np.clip(hq, 0.06, 2.0)
+        a2 = a2[(sh[a2] > 0.03) & (t[a2] < 30)]
+    sh = np.clip(sh, 0, 1)
+    sh = sh * sh * (3 - 2 * sh)
+    # labels and base colours: nearest item wins
+    dist = np.stack([it.d(Ph) for it in items])
+    which = np.argmin(dist, 0)
+    ids = np.zeros(len(Ph), int)
+    base = np.zeros((len(Ph), 3))
+    fade = np.ones(len(Ph))
+    nail = np.zeros(len(Ph), bool)
+    for k, it in enumerate(items):
+        m = which == k
+        if m.any():
+            ids[m], base[m], fade[m], nail[m] = it.info(Ph[m])
+    diff = np.clip(N @ LIGHT, 0, 1) * (0.25 + 0.75 * sh)
+    hemi = 0.5 + 0.5 * N[:, 1]
+    amb = (0.62 + 0.38 * hemi) * ao
+    rim = np.clip(1 - np.clip(N[:, 2], 0, 1), 0, 1) ** 3 * 0.12
+    spec = np.clip(N @ unit(LIGHT + V(0, 0, 1)), 0, 1) ** 24 * 0.08 * sh
+    col = base * (0.5 * amb + 0.55 * diff)[:, None] + (rim + spec)[:, None]
+    col = np.clip(col, 0, 1)
+    yy, xx = np.divmod(np.arange(n)[hi], px1 - px0)
+    yy += py0
+    xx += px0
+    out["hit"][yy, xx] = True
+    out["z"][yy, xx] = Ph[:, 2]
+    out["id"][yy, xx] = ids
+    out["rgb"][yy, xx] = col
+    out["fade"][yy, xx] = fade
+    out["nail"][yy, xx] = nail
+    return out
+
+
+def disk(r):
+    R = int(math.ceil(r + 1))
+    return [(dx, dy, math.hypot(dx, dy)) for dy in range(-R, R + 1) for dx in range(-R, R + 1)
+            if math.hypot(dx, dy) <= r + 0.5]
+
+
+def smooth_pair(a, b):
+    """No line where palm/forearm meets the same hand's fingers."""
+    same = (a // 16 == b // 16) & (a < 100) & (b < 100)
+    pa, pb = a % 16, b % 16
+    return same & ((pa == 0) | (pa == 7) | (pb == 0) | (pb == 7))
+
+
+def ink(buf, ss, out_w=2.6, in_w=2.3, zt=0.45, line=INK, nail_line=V(0.62, 0.58, 0.56)):
+    """Shaded buffers -> premultiplied RGBA with outline and inner lines."""
+    hit, Z, ID, rgb, F, NL = buf["hit"], buf["z"], buf["id"], buf["rgb"], buf["fade"], buf["nail"]
+    ro, ri = out_w * ss / 2 + 0.5, in_w * ss / 2 + 0.25
+    inner = np.zeros(hit.shape)
+    outer = np.zeros(hit.shape)
+    ofade = np.zeros(hit.shape)
+    nl = np.zeros(hit.shape)
+    Fh = np.where(hit, F, 0)
+    for dx, dy, r in disk(max(ro, ri) + 1):
+        Hq = np.roll(hit, (dy, dx), (0, 1))
+        wo = np.clip(ro - r + 0.5, 0, 1)
+        wi = np.clip(ri - r + 0.5, 0, 1)
+        if wo > 0:
+            m = (~hit) & Hq
+            outer = np.maximum(outer, m * wo)
+            ofade = np.maximum(ofade, np.roll(Fh, (dy, dx), (0, 1)) * (m * wo > 0))
+        if wi > 0:
+            Zq = np.roll(Z, (dy, dx), (0, 1))
+            Iq = np.roll(ID, (dy, dx), (0, 1))
+            e = hit & (((~Hq) & (r <= ro * 0.6)) | (Hq & (Zq - Z > zt)) |
+                       (Hq & (Iq != ID) & ~smooth_pair(ID, Iq) & (Zq >= Z - 0.15)))
+            inner = np.maximum(inner, e * wi)
+            if r <= ss * 0.7 + 0.5:
+                Nq = np.roll(NL, (dy, dx), (0, 1))
+                nl = np.maximum(nl, (hit & Hq & (Nq != NL)) * 1.0)
+    col = rgb.copy()
+    col = col * (1 - nl[..., None] * 0.7) + nail_line * nl[..., None] * 0.7
+    col = col * (1 - inner[..., None]) + line * inner[..., None]
+    alpha = np.where(hit, F, outer * ofade)
+    col = np.where(hit[..., None], col, line)
+    return col * alpha[..., None], alpha
+
+
+def over(dst_rgb, dst_a, src_rgb, src_a):
+    return src_rgb + dst_rgb * (1 - src_a[..., None]), src_a + dst_a * (1 - src_a)
+
+
+# ------------------------------------------------------------------ arrows
+
+ACCENT = (255, 184, 64)
+ACCENT_DARK = (24, 26, 32)
+
+
+def arc(c, u, v, r, a0, a1, n=48):
+    c, u, v = V(*c), unit(u), unit(v)
+    a = np.radians(np.linspace(a0, a1, n))
+    return [c + r * (math.cos(t) * u + math.sin(t) * v) for t in a]
+
+
+def seg(p0, p1, n=12):
+    p0, p1 = V(*p0), V(*p1)
+    return [p0 + (p1 - p0) * t for t in np.linspace(0, 1, n)]
+
+
+def project(cam, W, ss, p):
+    q = cam["R"] @ V(*p)
+    s = cam["scale"] / ss
+    return ((q[0] - cam["center"][0]) / s + W * ss / 2, (cam["center"][1] - q[1]) / s + W * ss / 2)
+
+
+def draw_labels(img, labels, cam, W, ss):
+    """Short text labels at world points, light with a dark edge (Pillow's built-in font)."""
+    dr = ImageDraw.Draw(img)
+    sc = ss * W / 512
+    font = ImageFont.load_default(size=int(round(42 * sc)))
+    for lb in labels:
+        x, y = project(cam, W, ss, lb["at"])
+        dr.text((x, y), lb["text"], font=font, anchor=lb.get("anchor", "mm"), fill=(232, 235, 240, 255),
+                stroke_width=int(round(4 * sc)), stroke_fill=ACCENT_DARK + (255,))
+    return img
+
+
+def draw_arrows(arrows, cam, W, ss):
+    img = Image.new("RGBA", (W * ss, W * ss), (0, 0, 0, 0))
+    dr = ImageDraw.Draw(img)
+    sc = ss * W / 512
+    lw, bw, hl, hw = 7 * sc, 3.2 * sc, 22 * sc, 15 * sc
+    for a in arrows:
+        pts = [project(cam, W, ss, p) for p in a["pts"]]
+        heads = a.get("heads", "end")
+        k = a.get("scale", 1.0)
+        shapes = []
+
+        def head(tip, prev):
+            dx, dy = tip[0] - prev[0], tip[1] - prev[1]
+            L = math.hypot(dx, dy) or 1
+            dx, dy = dx / L, dy / L
+            base = (tip[0] - dx * hl * k, tip[1] - dy * hl * k)
+            return [(tip[0] + dx * 2 * sc, tip[1] + dy * 2 * sc),
+                    (base[0] - dy * hw * k, base[1] + dx * hw * k),
+                    (base[0] + dy * hw * k, base[1] - dx * hw * k)]
+
+        def back_to(pts, dist):
+            acc = 0
+            for i in range(len(pts) - 1, 0, -1):
+                acc += math.dist(pts[i], pts[i - 1])
+                if acc >= dist:
+                    return pts[i - 1]
+            return pts[0]
+
+        body = list(pts)
+        if heads in ("end", "both"):
+            shapes.append(head(pts[-1], back_to(pts, hl * k)))
+            # stop the line under the arrow head
+            while len(body) > 2 and math.dist(body[-1], pts[-1]) < hl * k * 0.6:
+                body.pop()
+        if heads in ("start", "both"):
+            rp = pts[::-1]
+            shapes.append(head(rp[-1], back_to(rp, hl * k)))
+            while len(body) > 2 and math.dist(body[0], pts[0]) < hl * k * 0.6:
+                body.pop(0)
+        for width, colr, grow in ((lw * k + 2 * bw, ACCENT_DARK, bw), (lw * k, ACCENT, 0)):
+            dr.line(body, fill=colr, width=int(round(width)), joint="curve")
+            for e in (body[0], body[-1]):
+                r = width / 2
+                dr.ellipse([e[0] - r, e[1] - r, e[0] + r, e[1] + r], fill=colr)
+            for sh in shapes:
+                if grow:
+                    cxs = sum(p[0] for p in sh) / 3
+                    cys = sum(p[1] for p in sh) / 3
+                    big = []
+                    for p in sh:
+                        dx, dy = p[0] - cxs, p[1] - cys
+                        L = math.hypot(dx, dy) or 1
+                        big.append((p[0] + dx / L * grow * 1.8, p[1] + dy / L * grow * 1.8))
+                    dr.polygon(big, fill=colr)
+                else:
+                    dr.polygon(sh, fill=colr)
+    return img
+
+
+# ------------------------------------------------------------------ layout
+
+
+def fit(spec, W):
+    """Pick scale and centre so that everything fits with a margin."""
+    cam = spec["cam"]
+    pts = []
+    lo = W // 4
+    tmp = dict(cam, scale=1.0, center=(0.0, 0.0))
+    for layer in spec["layers"]:
+        items = to_cam(layer["items"], cam)
+        bs = [b for it in items for b in it.bounds()]
+        C = np.array([b[0] for b in bs])
+        Rr = np.array([b[1] for b in bs])
+        ext = max(np.abs(C[:, :2]).max() + Rr.max(), 1.0) * 2.1
+        tmp = dict(cam, scale=ext / lo, center=(0.0, 0.0))
+        buf = march(items, tmp, lo, 1)
+        yy, xx = np.nonzero(buf["hit"] & (buf["fade"] > 0.35))
+        s = tmp["scale"]
+        for x, y in ((xx.min(), yy.min()), (xx.max() + 1, yy.max() + 1)):
+            pts.append((((x - lo / 2) * s), (-(y - lo / 2) * s)))
+    for a in spec.get("arrows", []):
+        for p in a["pts"]:
+            q = cam["R"] @ V(*p)
+            pts.append((q[0], q[1]))
+    for lb in spec.get("labels", []):  # rough text extent: about 2 cm per side
+        q = cam["R"] @ V(*lb["at"])
+        pts += [(q[0] - lb.get("half", 3.0), q[1] - 1.5), (q[0] + lb.get("half", 3.0), q[1] + 1.5)]
+    pts = np.array(pts)
+    x0, y0 = pts.min(0)
+    x1, y1 = pts.max(0)
+    margin = 26 if spec.get("arrows") else 14
+    scale = max(spec.get("scale", 0.056), (x1 - x0) / (W - 2 * margin), (y1 - y0) / (W - 2 * margin))
+    return dict(cam, scale=scale, center=((x0 + x1) / 2, (y0 + y1) / 2))
+
+
+def render_pose(spec, W=512, ss=2):
+    cam = fit(spec, W)
+    Wp = W * ss
+    rgb = np.zeros((Wp, Wp, 3))
+    a = np.zeros((Wp, Wp))
+    for layer in spec["layers"]:
+        items = to_cam(layer["items"], cam)
+        for i, it in enumerate(items):
+            if isinstance(it, Hand):
+                it.hid = i
+        buf = march(items, cam, W, ss)
+        ghost = layer.get("ghost", 0)
+        if ghost:
+            buf["rgb"] = buf["rgb"] * 0.55 + V(0.62, 0.78, 1.0) * 0.45
+            lrgb, la = ink(buf, ss * W / 512, out_w=2.0, in_w=1.2, line=V(0.25, 0.3, 0.4))
+            lrgb, la = lrgb * ghost, la * ghost
+        else:
+            lrgb, la = ink(buf, ss * W / 512)
+        rgb, a = over(rgb, a, lrgb, la)
+    if spec.get("arrows") or spec.get("labels"):
+        im = draw_arrows(spec.get("arrows", []), cam, W, ss)
+        im = draw_labels(im, spec.get("labels", []), cam, W, ss)
+        arr = np.asarray(im, float) / 255
+        aa = arr[..., 3]
+        rgb, a = over(rgb, a, arr[..., :3] * aa[..., None], aa)
+    # downsample (premultiplied box filter)
+    rgb = rgb.reshape(W, ss, W, ss, 3).mean((1, 3))
+    a = a.reshape(W, ss, W, ss).mean((1, 3))
+    col = np.where(a[..., None] > 1e-4, rgb / np.maximum(a[..., None], 1e-4), 0)
+    img = np.dstack([np.clip(col, 0, 1) * 255, np.clip(a, 0, 1) * 255]).round().astype(np.uint8)
+    return Image.fromarray(img, "RGBA")
+
+
+# ------------------------------------------------------------------ poses
+
+STRAIGHT = (0, 0, 0)
+
+
+def P(index, middle, ring, pinky, thumb, **kw):
+    d = dict(index=index, middle=middle, ring=ring, pinky=pinky, thumb=thumb)
+    d.update(kw)
+    return d
+
+
+def ab(f, a):
+    return tuple(f[:3]) + (a,)
+
+
+CURL = {"index": (86, 100, 58, -2), "middle": (88, 102, 58, 1), "ring": (90, 102, 56, 4), "pinky": (92, 98, 52, 8)}
+FLAT = P((0, 0, 0, 1), (0, 0, 0, 0), (0, 0, 0, -1), (0, 0, 0, -3), (16, 6, 6, 4))
+SPREAD = P((-2, 0, 0, 14), (-2, 0, 0, 2), (-2, 0, 0, -11), (-2, 0, 0, -25), (42, 14, -4, -8))
+RELAX = P((12, 16, 8, 6), (15, 20, 10, 1), (18, 24, 12, -5), (22, 28, 14, -12), (38, 24, 12, 14))
+FIST = P(CURL["index"], CURL["middle"], CURL["ring"], CURL["pinky"],
+         ("to", lambda J: back_point(J["middle"], 1, 0.35), (-5, 40, 40, 25)))
+CLAW = P((-10, 80, 70, 14), (-10, 86, 72, 2), (-10, 86, 72, -11), (-10, 84, 68, -24), (45, 30, 35, 55))
+POINT = P((0, 0, 0, 0), CURL["middle"], CURL["ring"], CURL["pinky"],
+          ("to", lambda J: back_point(J["middle"], 1, 0.4), (-5, 40, 40, 25)))
+OK = P((55, 50, 30, 3), (4, 6, 3, -3), (6, 8, 4, -13), (8, 10, 5, -26),
+       ("to", lambda J: pad_point(J["index"], 0.0), (12, 50, 5, 15)))
+PINCH = P((40, 48, 24, 3), (70, 80, 44, 0), (76, 84, 46, -1), (80, 84, 46, -2),
+          ("to", lambda J: pad_point(J["index"], 0.0), (25, 40, 10, 10)))
+PINCH_OPEN = P((34, 40, 18, 4), (46, 60, 30, 0), (54, 66, 34, -2), (60, 68, 36, -5),
+               ("to", lambda J: pad_point(J["index"], 2.8), (30, 35, 5, 5)))
+THUMBS = P(CURL["index"], CURL["middle"], CURL["ring"], CURL["pinky"], (62, 12, -5, -8))
+GRIP = P((52, 70, 36, 0), (55, 72, 36, 1), (58, 72, 34, 3), (62, 70, 32, 6), (8, 48, 30, 25))
+
+
+def COUNT(n):
+    up = ["index", "middle", "ring"][:n]
+    f = {}
+    spread = {"index": 4, "middle": -1, "ring": -6}
+    for name in ("index", "middle", "ring", "pinky"):
+        f[name] = (0, 0, 0, spread[name]) if name in up else CURL[name]
+    first_down = ["index", "middle", "ring", "pinky"][n]
+    th = ("to", lambda J: back_point(J[first_down], 1, 0.4), (-5, 40, 40, 25))
+    return P(f["index"], f["middle"], f["ring"], f["pinky"], th)
+
+
+COUNT4 = P((0, 0, 0, 6), (0, 0, 0, 0), (0, 0, 0, -6), (0, 0, 0, -14),
+           ("to", lambda J: (-1.6, 7.6, 2.3), (-15, 40, 40, 20)))
+
+UP = np.eye(3)                      # palm toward you, fingers up
+BACK = Ry(180)                      # back of the hand toward you
+PALM_DOWN_FWD = orient((0, 0, -1), (0, -1, 0))  # on a desk: fingers away, palm down
+
+
+def H(pose, R=UP, t=(0, 0, 0), **kw):
+    return Hand(pose, R, t, **kw)
+
+
+def L(*items, ghost=0):
+    return dict(items=list(items), ghost=ghost)
+
+
+def cam(pitch=0, yaw=0):
+    """World -> camera. pitch > 0 looks down, yaw > 0 looks from the right."""
+    return dict(R=Rx(pitch) @ Ry(-yaw))
+
+
+CTRL_GRIP = P((50, 66, 36, 0), (54, 70, 36, 1), (58, 70, 34, 3), (62, 68, 32, 6), (30, 45, 10, 12))
+
+
+def ctrl_local():
+    """A generic VR controller in the hand frame of CTRL_GRIP (hand local coordinates):
+    a handle across the curled fingers, a head above the thumb with a thumbstick,
+    and a strap over the back of the hand."""
+    y, z, r = grip_hole(resolve(CTRL_GRIP))
+    ax = unit((0.45, 1.0, 0.1))
+    c = V(0.0, y - 0.6, z)
+    a, b = c - ax * 4.5, c + ax * 4.0
+    grip = Cone(a, b, r * 0.92, r * 1.02)
+    head_c = b + ax * 1.6 + V(0.9, 0.0, 0.4)
+    head = Ell(head_c, orient(ax, (0.3, 0, 1)), (2.4, 2.0, 2.0))
+    body = U([grip, head], 0.9)
+    up = unit((0.55, 0.55, 0.65))
+    sb = head_c + up * 1.75
+    stick = U([Cone(sb - up * 0.4, sb + up * 0.7, 0.36, 0.36),
+               Cyl(sb + up * 0.85, orient(up, (0, 0, 1)), 0.78, 0.2, 0.12)])
+    strap = Box((0.3, y - 1.2, -2.3), orient(ax, (0, 0, 1)), (0.95, 4.4, 0.1), 0.18)
+    return dict(body=body, stick=stick, strap=strap, top=sb + up * 1.05)
+
+
+CTRL = None
+
+
+def ctrl_parts(M=np.eye(3), t=(0, 0, 0)):
+    global CTRL
+    if CTRL is None:
+        CTRL = ctrl_local()
+    t = V(*t)
+    return [Obj(CTRL["body"], (0.5, 0.54, 0.6), 1).xf(M, t), Obj(CTRL["stick"], (0.3, 0.32, 0.37), 2).xf(M, t),
+            Obj(CTRL["strap"], (0.36, 0.38, 0.43), 3).xf(M, t)]
+
+
+def stick_top(hand):
+    if CTRL is None:
+        ctrl_parts()
+    return hand.world(CTRL["top"])
+
+
+def with_ctrl(hand):
+    """Controller objects placed in a hand's frame."""
+    return ctrl_parts(hand.M, hand.t)
+
+
+def ctrl_open_parts(hand):
+    """The controller on an open hand, held on by its strap (hand local, then moved with the hand):
+    the body lies against the palm from the heel up to the base of the thumb, the head sits
+    by the thumb, the strap crosses the back of the hand, and the fingers stay free."""
+    a, b = V(-1.7, 1.4, 3.5), V(1.9, 7.4, 3.4)
+    ax = unit(b - a)
+    grip = Cone(a, b, 1.45, 1.6)
+    head_c = b + ax * 1.7 + V(0.8, 0.0, 0.5)
+    head = Ell(head_c, orient(ax, (0.3, 0, 1)), (2.3, 1.9, 1.9))
+    up = unit((0.3, 0.3, 1.0))
+    sb = head_c + up * 1.75
+    stick = U([Cone(sb - up * 0.4, sb + up * 0.6, 0.36, 0.36),
+               Cyl(sb + up * 0.75, orient(up, (1, 0, 0)), 0.78, 0.2, 0.12)])
+    band = Box((0.0, 4.4, -2.2), orient(ax, (0, 0, 1)), (0.95, 3.8, 0.1), 0.18)
+    ends = [Cone((-1.7, 0.9, -2.15), (-3.9, 1.3, 0.2), 0.3, 0.3), Cone((-3.9, 1.3, 0.2), (-2.0, 1.4, 2.6), 0.3, 0.3),
+            Cone((1.7, 7.9, -2.15), (3.9, 7.6, 0.2), 0.3, 0.3), Cone((3.9, 7.6, 0.2), (2.2, 7.4, 2.6), 0.3, 0.3)]
+    M, t = hand.M, hand.t
+    return [Obj(U([grip, head], 0.9), (0.5, 0.54, 0.6), 1).xf(M, t), Obj(stick, (0.3, 0.32, 0.37), 2).xf(M, t),
+            Obj(U([band] + ends, 0.25), (0.36, 0.38, 0.43), 3).xf(M, t)]
+
+
+def keyboard(c=(0, 0, 0), nx=14, nz=5):
+    pitch = 1.9
+    w, dpt = nx * pitch / 2 + 0.6, nz * pitch / 2 + 0.6
+    base = Box((c[0], c[1] + 0.8, c[2]), np.eye(3), (w - 0.4, 0.4, dpt - 0.4), 0.4)
+    keys = Keys((c[0], c[1] + 1.75, c[2]), np.eye(3), nx, nz, pitch, (0.62, 0.18, 0.62), 0.12)
+    return [Obj(base, (0.42, 0.45, 0.5), 4), Obj(keys, (0.6, 0.64, 0.7), 5)]
+
+
+def mouse(c=(0, 0, 0)):
+    body = Clip(Ell((c[0], c[1] + 0.2, c[2]), np.eye(3), (3.1, 3.6, 5.6)), (c[0], c[1], c[2]), (0, -1, 0))
+    groove = Box((c[0], c[1] + 3.6, c[2] - 3.0), np.eye(3), (0.08, 1.2, 2.6), 0.02)
+    return [Obj(Sub(body, groove), (0.56, 0.6, 0.67), 6)]
+
+
+def cup(c=(0, 0, 0)):
+    c = V(*c)
+    outer = Cyl(c + V(0, 4.75, 0), np.eye(3), 3.9, 4.75, 0.35)
+    inner = Cyl(c + V(0, 5.6, 0), np.eye(3), 3.45, 4.75, 0.3)
+    handle = Torus(c + V(-4.6, 5.2, 0), Rx(90), 2.0, 0.45)
+    return [Obj(U([Sub(outer, inner), Clip(handle, c + V(-4.2, 0, 0), (1, 0, 0))], 0.3), (0.56, 0.6, 0.67), 7)]
+
+
+def place(hand_pose, R, anchor, target, joint=("middle", 3), **kw):
+    """Hand with a joint (default: middle fingertip) at a target point."""
+    h = Hand(hand_pose, R, (0, 0, 0), **kw)
+    p = h.joint(*joint)
+    if kw.get("left"):
+        p = p  # joint() already includes the mirror
+    off = V(*target) - p + V(*anchor)
+    return Hand(hand_pose, R, (np.diag([-1.0, 1, 1]) if kw.get("left") else np.eye(3)) @ off, **kw)
+
+
+def typing_hands(lift=0.0):
+    pose = P((18, 42, 18, 3), (20, 46, 20, 0), (22, 48, 20, -3), (26, 46, 20, -7), (30, 28, 10, 10),
+             wrist=(-12, 0))
+    R = PALM_DOWN_FWD
+    rh = place(pose, R, (0, lift, 0), (4.0, 2.55 + 0.74, -1.0))
+    lh = place(pose, R, (0, lift, 0), (-4.0, 2.55 + 0.74, -1.0), left=True)
+    return rh, lh
+
+
+def spec_typing():
+    rh, lh = typing_hands()
+    return dict(cam=cam(48), layers=[L(*keyboard(), rh, lh)])
+
+
+def spec_lift():
+    rh, lh = typing_hands()
+    g1, g2 = typing_hands(lift=7)
+    return dict(cam=cam(48), layers=[L(g1, g2, ghost=0.5), L(*keyboard(), rh, lh)],
+                arrows=[dict(pts=seg((13.5, 4, 3), (13.5, 11, 3)), heads="both")])
+
+
+MOUSE_POSE = P((12, 22, 10, 2), (12, 24, 12, -1), (30, 50, 26, -6), (40, 54, 28, -12), (52, 18, 10, 8),
+               wrist=(-8, 0))
+
+
+def mouse_hand(c=(0, 0, 0)):
+    return place(MOUSE_POSE, PALM_DOWN_FWD, (0, 0, 0), V(*c) + V(0.4, 3.6, -4.6))
+
+
+def spec_mouse():
+    return dict(cam=cam(35, -40), layers=[L(*mouse(), mouse_hand())])
+
+
+def spec_switch():
+    rh, lh = typing_hands()
+    mh = mouse_hand((26, 0, 0))
+    return dict(cam=cam(48), layers=[L(mh, ghost=0.5), L(*keyboard(), *mouse((26, 0, 0)), rh, lh)],
+                arrows=[dict(pts=arc((17, 6, 2), (1, 0, 0), (0, 1, 0), 7, 160, 20), heads="both")])
+
+
+def grip_hole(J, name="middle", palm_z=1.9):
+    """Centre (y, z) and radius of the biggest bar that fits inside a curled finger (hand local)."""
+    f = J[name]
+    best = (0.0, 0.0, 0.0)
+    ys = [p[1] for p in f["pts"]]
+    zs = [p[2] for p in f["pts"]]
+    for y in np.linspace(ys[0], max(ys), 60):
+        for z in np.linspace(palm_z, max(zs), 60):
+            r = z - palm_z
+            c = V(y, z)
+            for i in range(3):
+                a, b = f["pts"][i][1:], f["pts"][i + 1][1:]
+                t = np.clip((c - a) @ (b - a) / ((b - a) @ (b - a)), 0, 1)
+                r = min(r, np.linalg.norm(c - (a + (b - a) * t)) - f["radii"][i + 1])
+            if r > best[2]:
+                best = (y, z, r)
+    return best
+
+
+GLASS = P((40, 70, 40, 0), (42, 72, 40, 1), (44, 72, 38, 3), (48, 70, 36, 6),
+          ("to", lambda J: (2.4, 9.0, 6.4), (10, 50, 20, 20)))
+HOLD_VIEW = Rz(75) @ Ry(-15)
+
+
+def spec_hold():
+    h = H(GLASS, HOLD_VIEW)
+    y, z, r = grip_hole(h.J)
+    c = h.world((0.3, y, z))
+    ax = unit(h.M @ V(1, 0, 0))
+    R = orient(ax, (0, 0, 1))  # the bottle's axis runs along the hand's x axis
+    body = Cyl(c + ax * 1.0, R, r - 0.05, 6.5, 0.4)
+    neck = Cone(c + ax * 7.0, c + ax * 9.6, r * 0.75, r * 0.45)
+    cap = Cyl(c + ax * 10.0, R, r * 0.5, 0.6, 0.15)
+    bottle = Obj(U([body, neck, cap], 0.6), (0.56, 0.6, 0.67), 7)
+    top = c + ax * 9.5
+    return dict(cam=cam(12), layers=[L(bottle, h)],
+                arrows=[dict(pts=seg(top + V(7, -6, 0), top + V(7, 1, 0)), heads="both", scale=0.85)])
+
+
+def touch_scene(lR, f, p, lt=(0, 0, 0), left=True):
+    """A hand holding a controller (left by default) and the other index on its thumbstick."""
+    ch = Hand(CTRL_GRIP, lR, lt, left=left)
+    up = ch.M @ unit((0.55, 0.55, 0.65))
+    tgt = stick_top(ch) + up * 0.7
+    ph = place(POINT, orient(f, p), (0, 0, 0), tgt, joint=("index", 3), left=not left)
+    return [ch, *with_ctrl(ch), ph]
+
+
+def spec_touch_stick():
+    return dict(cam=cam(20), layers=[L(*touch_scene(Rz(-10) @ Rx(-50), (-1, -1, -0.6), (-0.3, -0.6, -1)))])
+
+
+def spec_touch_stick_desk(f=(-1, -0.8, 0), p=(0, -1, -0.3)):
+    hold = Hand(CTRL_GRIP, orient((0, 0, -1), (0, 1, 0)))
+    objs = with_ctrl(hold)[:2]  # no strap: it hangs loose on the desk
+    up = hold.M @ unit((0.55, 0.55, 0.65))
+    tgt = stick_top(hold) + up * 0.7
+    rh = place(POINT, orient(f, p), (0, 0, 0), tgt, joint=("index", 3))
+    return dict(cam=cam(25), layers=[L(*objs, rh)])
+
+
+def head_and_headset(R=np.eye(3)):
+    """The wearer's head with a headset on, facing -z (the head's local frame), as two objects."""
+    head = Ell((0, 0, 0), np.eye(3), (7.6, 10.2, 8.8))
+    nose = Cone((0, -1.5, -8.2), (0, -3.6, -9.6), 0.7, 0.9)
+    visor = Box((0, 2.4, -6.5), np.eye(3), (8.2, 2.6, 2.6), 1.4)
+    band = Torus((0, 3.0, 0.5), Rx(8), 8.0, 0.9)
+    z = V(0, 0, 0)
+    return [Obj(U([head, nose], 0.6), (0.5, 0.53, 0.58), 8).xf(R, z),
+            Obj(U([visor, band], 0.4), (0.36, 0.38, 0.43), 9).xf(R, z)]
+
+
+def push_hand(pose, z, controllers=False):
+    """A right hand pushed out in front of the face (forward is -z), palm out, arm reaching back."""
+    fwd = unit((0, 0.42, -1))                      # the forearm points forward and a little up
+    R = orient(fwd, unit(np.cross(fwd, (1, 0, 0))))  # palm down along the arm
+    h = Hand(dict(pose, wrist=(-66, 0)), R, (3.0, -17.0, z), arm=15)  # wrist bent back: fingers up
+    return [h] + (ctrl_open_parts(h) if controllers else [])
+
+
+def push_spec(controllers=False):
+    pose = FLAT  # open hand, palm out; with controllers the strap holds the controller on
+    near, far = -21.0, -44.0
+    eye = V(0, 2.4, -10.5)
+    tip_y = 0.0
+    return dict(cam=cam(4, 65), scale=0.11,
+                layers=[L(*push_hand(pose, far, controllers), ghost=0.45),
+                        L(*head_and_headset(), *push_hand(pose, near, controllers))],
+                arrows=[dict(pts=seg(eye + V(0, tip_y, -1.0), V(0, eye[1] + tip_y, far - 7.0)), heads="both")],
+                labels=[dict(at=(0, eye[1] + tip_y + 4.2, near - 1.0), text="near", half=4.0),
+                        dict(at=(0, eye[1] + tip_y + 4.2, far - 2.0), text="arm out", half=7.0)])
+
+
+def ghost_pair(main_pose, ghost_pose, R, cam_, arrows, ghost_alpha=0.45, **kw):
+    return dict(cam=cam_, layers=[L(H(ghost_pose, R, **kw), ghost=ghost_alpha), L(H(main_pose, R, **kw))],
+                arrows=arrows)
+
+
+def spec_cross():
+    R = Rz(30)
+    rh = H(FLAT, R, (-2.2, 0, 1.6), arm=12)
+    lh = H(FLAT, R, (-2.2, 0, -1.6), left=True, arm=12)
+    return dict(cam=cam(), layers=[L(rh, lh)],
+                arrows=[dict(pts=seg((-5, 22, 3), (-14, 22, 3)), scale=0.85),
+                        dict(pts=seg((5, 22, 3), (14, 22, 3)), scale=0.85)])
+
+
+def spec_overlap():
+    rh = H(FLAT, Rz(8), (-2.5, 2.5, 3))
+    lh = H(FLAT, Rz(8), (-2.5, -2.5, -3), left=True)
+    return dict(cam=cam(), layers=[L(rh, lh)],
+                arrows=[dict(pts=arc((0, 9, 4), (1, 0, 0), (0, 1, 0), 13.5, 35, 145), heads="both")])
+
+
+def spec_near_face():
+    head = Ell((0, 0, 0), np.eye(3), (7.6, 10.2, 8.8))
+    visor = Box((0, 2.4, 6.5), np.eye(3), (8.2, 2.6, 2.6), 1.4)
+    band = Torus((0, 3.0, -0.5), Rx(-8), 8.0, 0.9)
+    objs = [Obj(U([head]), (0.5, 0.53, 0.58), 8), Obj(U([visor, band], 0.4), (0.36, 0.38, 0.43), 9)]
+    R = orient((0, 1, 0.15), (1, 0, 0.2))
+    rh = H(RELAX, R, (-12.5, -9, 4))
+    lh = H(RELAX, R, (-12.5, -9, 4), left=True)
+    return dict(cam=cam(5, 22), layers=[L(*objs, rh, lh)],
+                arrows=[dict(pts=arc((0, 2, 0), (1, 0, 0), (0, 1, 0), 15.5, 40, 140), heads="both")])
+
+
+def spec_screen_point():
+    R = Rx(-35) @ BACK
+    h = H(POINT, R, (0, -12, 0))
+    tip = h.joint("index", 3)
+    scr = Box((2, tip[1] + 9, -30), np.eye(3), (14, 8, 0.4), 0.5)
+    stand = Box((2, tip[1] - 1, -30.5), np.eye(3), (1.2, 2.5, 0.3), 0.3)
+    return dict(cam=cam(8), layers=[L(Obj(U([scr, stand]), (0.42, 0.45, 0.5), 10), h)],
+                arrows=[dict(pts=seg(tip + V(0, 1.2, 0), tip + V(0, 7.0, -20)), scale=0.75)])
+
+
+def spec_turn_in_out():
+    return dict(cam=cam(16), layers=[L(H(RELAX, Ry(-25)))],
+                arrows=[dict(pts=arc((0, -1.5, 0), (1, 0, 0), (0, 0, 1), 6.5, -20, 200), heads="both")])
+
+
+def spec_turn_up_down():
+    R = PALM_DOWN_FWD
+    Rg = orient((0, 0, -1), (0, 1, 0))
+    return dict(cam=cam(40), layers=[L(H(FLAT, Rg, (0, 0.2, 0)), ghost=0.4), L(H(FLAT, R))],
+                arrows=[dict(pts=arc((0, 0, 0.5), (1, 0, 0), (0, 1, 0), 7.0, 15, 165), heads="both")])
+
+
+def spec_bend():
+    R = PALM_DOWN_FWD
+    g1 = H(dict(FLAT, wrist=(0, 28)), R)
+    g2 = H(dict(FLAT, wrist=(0, -28)), R)
+    g3 = H(dict(FLAT, wrist=(-35, 0)), R)
+    return dict(cam=cam(38), layers=[L(g1, g2, ghost=0.35), L(g3, ghost=0.35), L(H(FLAT, R))],
+                arrows=[dict(pts=arc((0, 1, 0), (1, 0, 0), (0, 0, -1), 21, 60, 120), heads="both"),
+                        dict(pts=arc((0, 1, 0), (0, 0, -1), (0, 1, 0), 21, 10, 50), heads="both", scale=0.8)])
+
+
+PINCH_VIEW = Ry(-90)
+
+
+def spec_pinch_tap():
+    h = H(PINCH_OPEN, PINCH_VIEW)
+    a, b = h.joint("index", 3), h.joint("thumb", 3)
+    side = V(-3.2, 0, 0)
+    return dict(cam=cam(20), layers=[L(h)],
+                arrows=[dict(pts=seg(a + side + V(0, 1.0, 0), b + side - V(0, 1.0, 0)), heads="both", scale=0.7)])
+
+
+def spec_pinch_drag():
+    h = H(PINCH, PINCH_VIEW)
+    g = H(PINCH, PINCH_VIEW, (15, 0, 0))
+    top = h.joint("middle", 1)
+    return dict(cam=cam(20), layers=[L(g, ghost=0.4), L(h)],
+                arrows=[dict(pts=seg(top + V(1, 3.5, 0), top + V(12, 3.5, 0)))])
+
+
+def spec_grab():
+    R = Ry(-60)
+    h = H(GRIP, R)
+    y, z, r = grip_hole(h.J)
+    c = h.world((-0.4, y, z))
+    bar = Cyl(c, orient(h.M @ V(1, 0, 0), (0, 0, 1)), r - 0.05, 8, 0.3)
+    return dict(cam=cam(10), layers=[L(H(RELAX, R), ghost=0.4), L(h, Obj(bar, (0.5, 0.54, 0.6), 11))],
+                arrows=[dict(pts=arc(c, (0, 1, 0), (1, 0, 0), 9.5, 20, 100), heads="both", scale=0.85)])
+
+
+def spec_open_close():
+    R = UP
+    return dict(cam=cam(), layers=[L(H(SPREAD, R), ghost=0.45), L(H(FIST, R))],
+                arrows=[dict(pts=arc((0, 11, 3), (1, 0, 0), (0, 1, 0), 9.5, -20, 60), heads="both", scale=0.85)])
+
+
+def spec_no_hands():
+    g = H(RELAX, BACK, (0, 6, 0))
+    return dict(cam=cam(), layers=[L(g, ghost=0.4)],
+                arrows=[dict(pts=seg((7.5, 12, 4), (7.5, -2, 4)))])
+
+
+POSES = {
+    "flat": ("Palm toward you, fingers together", False, lambda: dict(cam=cam(), layers=[L(H(FLAT))])),
+    "flat-back": ("Back of the hand toward you", False, lambda: dict(cam=cam(), layers=[L(H(FLAT, BACK))])),
+    "spread": ("Fingers spread wide", False, lambda: dict(cam=cam(), layers=[L(H(SPREAD))])),
+    "open": ("Open and relaxed", False, lambda: dict(cam=cam(), layers=[L(H(RELAX, Ry(-25) @ Rx(-10)))])),
+    "fist": ("A fist", False, lambda: dict(cam=cam(), layers=[L(H(FIST, Ry(-20)))])),
+    "point": ("Point with your index finger", False,
+              lambda: dict(cam=cam(20, -30), layers=[L(H(POINT, orient((0.1, 0.5, -1), (-0.6, -1, 0))))])),
+    "pinch": ("Thumb and index tips touching", False,
+              lambda: dict(cam=cam(20), layers=[L(H(PINCH, Ry(-90)))])),
+    "ok": ("OK sign: a ring, three fingers up", False,
+           lambda: dict(cam=cam(10), layers=[L(H(OK, Ry(-70)))])),
+    "thumbs-up": ("Thumbs up", False, lambda: dict(cam=cam(), layers=[L(H(THUMBS, Rz(75) @ Ry(-15)))])),
+    "claw": ("Fingers curled like a claw", False,
+             lambda: dict(cam=cam(35), layers=[L(H(CLAW, Ry(-20)))])),
+    "count-1": ("One: index finger", False, lambda: dict(cam=cam(), layers=[L(H(COUNT(1)))])),
+    "count-2": ("Two: index and middle", False, lambda: dict(cam=cam(), layers=[L(H(COUNT(2)))])),
+    "count-3": ("Three: index, middle, ring", False, lambda: dict(cam=cam(), layers=[L(H(COUNT(3)))])),
+    "count-4": ("Four: thumb folded in", False, lambda: dict(cam=cam(), layers=[L(H(COUNT4))])),
+    "count-5": ("Five: all fingers spread", False, lambda: dict(cam=cam(), layers=[L(H(SPREAD))])),
+    "turn-in-out": ("Turn your wrist: palm in, palm out", False, spec_turn_in_out),
+    "turn-up-down": ("Palm down, turn it up, then back", False, spec_turn_up_down),
+    "bend": ("Bend your wrist up, down, side to side", False, spec_bend),
+    "pinch-tap": ("Tap thumb and index together", False, spec_pinch_tap),
+    "pinch-drag": ("Pinch, move to the side, let go", False, spec_pinch_drag),
+    "grab": ("Close your hand around a bar, open it", False, spec_grab),
+    "open-close": ("Open and close your hand", False, spec_open_close),
+    "cross": ("Cross your hands, then uncross", True, spec_cross),
+    "overlap": ("One hand over the other, slide around", True, spec_overlap),
+    "near-face": ("Hands near your face, not touching", True, spec_near_face),
+    "screen-point": ("Point at a screen at arm's length", False, spec_screen_point),
+    "typing": ("Type on the keyboard", True, spec_typing),
+    "lift": ("Lift your hands off the keyboard, put them back", True, spec_lift),
+    "mouse": ("Hand on the mouse, move and click", False, spec_mouse),
+    "switch": ("Switch between keyboard and mouse", True, spec_switch),
+    "hold": ("Pick it up, use it, put it down", True, spec_hold),
+    "push": ("Push straight out, away from the headset, and back", True, lambda: push_spec(False)),
+    "push-controller": ("Controllers on: push straight out from the headset, and back", True,
+                        lambda: push_spec(True)),
+    "touch-stick": ("Touch the thumbstick with your other index", True, spec_touch_stick),
+    "touch-stick-desk": ("Touch the thumbstick of the controller on the desk", True, spec_touch_stick_desk),
+    "no-hands": ("Hands down, out of view", False, spec_no_hands),
+}
+
+
+# ------------------------------------------------------------------ main
+
+
+def _job(args):
+    pid, out, W, ss = args
+    img = render_pose(POSES[pid][2](), W, ss)
+    img.save(os.path.join(out, pid + ".png"), optimize=True)
+    return pid
+
+
+def contact_sheet(ids, out, thumb=240, cols=6):
+    rows = (len(ids) + cols - 1) // cols
+    pad, lab = 14, 26
+    W = cols * (thumb + pad) + pad
+    Hh = rows * (thumb + lab + pad) + pad
+    sheet = Image.new("RGBA", (W, Hh), (22, 24, 29, 255))
+    dr = ImageDraw.Draw(sheet)
+    try:
+        font = ImageFont.load_default(size=17)
+    except TypeError:
+        font = ImageFont.load_default()
+    for i, pid in enumerate(ids):
+        x = pad + (i % cols) * (thumb + pad)
+        y = pad + (i // cols) * (thumb + lab + pad)
+        dr.rounded_rectangle([x, y, x + thumb, y + thumb], 10, fill=(34, 37, 44, 255))
+        im = Image.open(os.path.join(out, pid + ".png")).convert("RGBA").resize((thumb, thumb), Image.LANCZOS)
+        sheet.alpha_composite(im, (x, y))
+        dr.text((x + thumb / 2, y + thumb + 4), pid, fill=(220, 224, 230, 255), font=font, anchor="mt")
+    sheet.convert("RGB").save(os.path.join(out, "contact-sheet.png"), optimize=True)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--out", default=HERE)
+    ap.add_argument("--only", default="", help="comma-separated pose ids")
+    ap.add_argument("--size", type=int, default=512)
+    ap.add_argument("--ss", type=int, default=3, help="supersampling per axis")
+    ap.add_argument("--jobs", type=int, default=1)
+    ap.add_argument("--no-sheet", action="store_true")
+    a = ap.parse_args()
+    ids = [p for p in a.only.split(",") if p] or list(POSES)
+    bad = [p for p in ids if p not in POSES]
+    if bad:
+        sys.exit("unknown pose: " + ", ".join(bad))
+    os.makedirs(a.out, exist_ok=True)
+    work = [(p, a.out, a.size, a.ss) for p in ids]
+    if a.jobs > 1:
+        with ProcessPoolExecutor(a.jobs) as ex:
+            for pid in ex.map(_job, work):
+                print(pid, flush=True)
+    else:
+        for w in work:
+            print(_job(w), flush=True)
+    if not a.only:
+        meta = {pid: {"file": pid + ".png", "two_hands": two, "caption": cap}
+                for pid, (cap, two, _) in POSES.items()}
+        with open(os.path.join(a.out, "poses.json"), "w") as f:
+            json.dump(meta, f, indent=2)
+            f.write("\n")
+    if not a.no_sheet:
+        have = [p for p in POSES if os.path.exists(os.path.join(a.out, p + ".png"))]
+        contact_sheet(have, a.out)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/hands/rec/poses/mouse.png b/hands/rec/poses/mouse.png
new file mode 100644
index 0000000..9b8d92c
Binary files /dev/null and b/hands/rec/poses/mouse.png differ
diff --git a/hands/rec/poses/near-face.png b/hands/rec/poses/near-face.png
new file mode 100644
index 0000000..4da0519
Binary files /dev/null and b/hands/rec/poses/near-face.png differ
diff --git a/hands/rec/poses/no-hands.png b/hands/rec/poses/no-hands.png
new file mode 100644
index 0000000..7b7eebe
Binary files /dev/null and b/hands/rec/poses/no-hands.png differ
diff --git a/hands/rec/poses/ok.png b/hands/rec/poses/ok.png
new file mode 100644
index 0000000..d8b6c00
Binary files /dev/null and b/hands/rec/poses/ok.png differ
diff --git a/hands/rec/poses/open-close.png b/hands/rec/poses/open-close.png
new file mode 100644
index 0000000..051c372
Binary files /dev/null and b/hands/rec/poses/open-close.png differ
diff --git a/hands/rec/poses/open.png b/hands/rec/poses/open.png
new file mode 100644
index 0000000..7f9cf9b
Binary files /dev/null and b/hands/rec/poses/open.png differ
diff --git a/hands/rec/poses/overlap.png b/hands/rec/poses/overlap.png
new file mode 100644
index 0000000..dc60427
Binary files /dev/null and b/hands/rec/poses/overlap.png differ
diff --git a/hands/rec/poses/pinch-drag.png b/hands/rec/poses/pinch-drag.png
new file mode 100644
index 0000000..eab4981
Binary files /dev/null and b/hands/rec/poses/pinch-drag.png differ
diff --git a/hands/rec/poses/pinch-tap.png b/hands/rec/poses/pinch-tap.png
new file mode 100644
index 0000000..4a7ca50
Binary files /dev/null and b/hands/rec/poses/pinch-tap.png differ
diff --git a/hands/rec/poses/pinch.png b/hands/rec/poses/pinch.png
new file mode 100644
index 0000000..d1906a9
Binary files /dev/null and b/hands/rec/poses/pinch.png differ
diff --git a/hands/rec/poses/point.png b/hands/rec/poses/point.png
new file mode 100644
index 0000000..e050565
Binary files /dev/null and b/hands/rec/poses/point.png differ
diff --git a/hands/rec/poses/poses.json b/hands/rec/poses/poses.json
new file mode 100644
index 0000000..4d25c5d
--- /dev/null
+++ b/hands/rec/poses/poses.json
@@ -0,0 +1,182 @@
+{
+  "flat": {
+    "file": "flat.png",
+    "two_hands": false,
+    "caption": "Palm toward you, fingers together"
+  },
+  "flat-back": {
+    "file": "flat-back.png",
+    "two_hands": false,
+    "caption": "Back of the hand toward you"
+  },
+  "spread": {
+    "file": "spread.png",
+    "two_hands": false,
+    "caption": "Fingers spread wide"
+  },
+  "open": {
+    "file": "open.png",
+    "two_hands": false,
+    "caption": "Open and relaxed"
+  },
+  "fist": {
+    "file": "fist.png",
+    "two_hands": false,
+    "caption": "A fist"
+  },
+  "point": {
+    "file": "point.png",
+    "two_hands": false,
+    "caption": "Point with your index finger"
+  },
+  "pinch": {
+    "file": "pinch.png",
+    "two_hands": false,
+    "caption": "Thumb and index tips touching"
+  },
+  "ok": {
+    "file": "ok.png",
+    "two_hands": false,
+    "caption": "OK sign: a ring, three fingers up"
+  },
+  "thumbs-up": {
+    "file": "thumbs-up.png",
+    "two_hands": false,
+    "caption": "Thumbs up"
+  },
+  "claw": {
+    "file": "claw.png",
+    "two_hands": false,
+    "caption": "Fingers curled like a claw"
+  },
+  "count-1": {
+    "file": "count-1.png",
+    "two_hands": false,
+    "caption": "One: index finger"
+  },
+  "count-2": {
+    "file": "count-2.png",
+    "two_hands": false,
+    "caption": "Two: index and middle"
+  },
+  "count-3": {
+    "file": "count-3.png",
+    "two_hands": false,
+    "caption": "Three: index, middle, ring"
+  },
+  "count-4": {
+    "file": "count-4.png",
+    "two_hands": false,
+    "caption": "Four: thumb folded in"
+  },
+  "count-5": {
+    "file": "count-5.png",
+    "two_hands": false,
+    "caption": "Five: all fingers spread"
+  },
+  "turn-in-out": {
+    "file": "turn-in-out.png",
+    "two_hands": false,
+    "caption": "Turn your wrist: palm in, palm out"
+  },
+  "turn-up-down": {
+    "file": "turn-up-down.png",
+    "two_hands": false,
+    "caption": "Palm down, turn it up, then back"
+  },
+  "bend": {
+    "file": "bend.png",
+    "two_hands": false,
+    "caption": "Bend your wrist up, down, side to side"
+  },
+  "pinch-tap": {
+    "file": "pinch-tap.png",
+    "two_hands": false,
+    "caption": "Tap thumb and index together"
+  },
+  "pinch-drag": {
+    "file": "pinch-drag.png",
+    "two_hands": false,
+    "caption": "Pinch, move to the side, let go"
+  },
+  "grab": {
+    "file": "grab.png",
+    "two_hands": false,
+    "caption": "Close your hand around a bar, open it"
+  },
+  "open-close": {
+    "file": "open-close.png",
+    "two_hands": false,
+    "caption": "Open and close your hand"
+  },
+  "cross": {
+    "file": "cross.png",
+    "two_hands": true,
+    "caption": "Cross your hands, then uncross"
+  },
+  "overlap": {
+    "file": "overlap.png",
+    "two_hands": true,
+    "caption": "One hand over the other, slide around"
+  },
+  "near-face": {
+    "file": "near-face.png",
+    "two_hands": true,
+    "caption": "Hands near your face, not touching"
+  },
+  "screen-point": {
+    "file": "screen-point.png",
+    "two_hands": false,
+    "caption": "Point at a screen at arm's length"
+  },
+  "typing": {
+    "file": "typing.png",
+    "two_hands": true,
+    "caption": "Type on the keyboard"
+  },
+  "lift": {
+    "file": "lift.png",
+    "two_hands": true,
+    "caption": "Lift your hands off the keyboard, put them back"
+  },
+  "mouse": {
+    "file": "mouse.png",
+    "two_hands": false,
+    "caption": "Hand on the mouse, move and click"
+  },
+  "switch": {
+    "file": "switch.png",
+    "two_hands": true,
+    "caption": "Switch between keyboard and mouse"
+  },
+  "hold": {
+    "file": "hold.png",
+    "two_hands": true,
+    "caption": "Pick it up, use it, put it down"
+  },
+  "push": {
+    "file": "push.png",
+    "two_hands": true,
+    "caption": "Push straight out, away from the headset, and back"
+  },
+  "push-controller": {
+    "file": "push-controller.png",
+    "two_hands": true,
+    "caption": "Controllers on: push straight out from the headset, and back"
+  },
+  "touch-stick": {
+    "file": "touch-stick.png",
+    "two_hands": true,
+    "caption": "Touch the thumbstick with your other index"
+  },
+  "touch-stick-desk": {
+    "file": "touch-stick-desk.png",
+    "two_hands": true,
+    "caption": "Touch the thumbstick of the controller on the desk"
+  },
+  "no-hands": {
+    "file": "no-hands.png",
+    "two_hands": false,
+    "caption": "Hands down, out of view"
+  }
+}
diff --git a/hands/rec/poses/push-controller.png b/hands/rec/poses/push-controller.png
new file mode 100644
index 0000000..d1dcd70
Binary files /dev/null and b/hands/rec/poses/push-controller.png differ
diff --git a/hands/rec/poses/push.png b/hands/rec/poses/push.png
new file mode 100644
index 0000000..a21dbf6
Binary files /dev/null and b/hands/rec/poses/push.png differ
diff --git a/hands/rec/poses/screen-point.png b/hands/rec/poses/screen-point.png
new file mode 100644
index 0000000..ca116f6
Binary files /dev/null and b/hands/rec/poses/screen-point.png differ
diff --git a/hands/rec/poses/spread.png b/hands/rec/poses/spread.png
new file mode 100644
index 0000000..e56012a
Binary files /dev/null and b/hands/rec/poses/spread.png differ
diff --git a/hands/rec/poses/switch.png b/hands/rec/poses/switch.png
new file mode 100644
index 0000000..4583de5
Binary files /dev/null and b/hands/rec/poses/switch.png differ
diff --git a/hands/rec/poses/thumbs-up.png b/hands/rec/poses/thumbs-up.png
new file mode 100644
index 0000000..4d2cd90
Binary files /dev/null and b/hands/rec/poses/thumbs-up.png differ
diff --git a/hands/rec/poses/touch-stick-desk.png b/hands/rec/poses/touch-stick-desk.png
new file mode 100644
index 0000000..e57f8ce
Binary files /dev/null and b/hands/rec/poses/touch-stick-desk.png differ
diff --git a/hands/rec/poses/touch-stick.png b/hands/rec/poses/touch-stick.png
new file mode 100644
index 0000000..c75f096
Binary files /dev/null and b/hands/rec/poses/touch-stick.png differ
diff --git a/hands/rec/poses/turn-in-out.png b/hands/rec/poses/turn-in-out.png
new file mode 100644
index 0000000..a6aaf0b
Binary files /dev/null and b/hands/rec/poses/turn-in-out.png differ
diff --git a/hands/rec/poses/turn-up-down.png b/hands/rec/poses/turn-up-down.png
new file mode 100644
index 0000000..57e0759
Binary files /dev/null and b/hands/rec/poses/turn-up-down.png differ
diff --git a/hands/rec/poses/typing.png b/hands/rec/poses/typing.png
new file mode 100644
index 0000000..54e3220
Binary files /dev/null and b/hands/rec/poses/typing.png differ
diff --git a/hands/rec/rehearse.sh b/hands/rec/rehearse.sh
new file mode 100755
index 0000000..6e03dd8
--- /dev/null
+++ b/hands/rec/rehearse.sh
@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+# The hand recorder end to end, without the headset (DESIGN.md "Upload"): a short stretch of
+# an ft-hands recording plays into a camera ring (ft-ringplay), a session records it with a
+# short test script (session.py, the panel as ft-handpanel --no-vr, a tracking ft-hands),
+# takes.py exports it, validate.py checks the export, and hub.py uploads it: a dry run by
+# default, or for real to a (test) dataset with --repo.
+#
+#   hands/rec/rehearse.sh [--repo ID] [--capture DIR] [--from S] [--prompt-seconds N] [--keep]
+#
+#   --repo ID            upload for real to this dataset, as a pull request. While the texts are
+#                        drafts that also needs FT_HANDREC_ALLOW_UPLOAD=1 in the environment.
+#   --capture DIR        the recording to play (default the frame-hands capture
+#                        rec-20260930-103803-lit); --from S: start this far into it (60)
+#   --prompt-seconds N   each test step's length (3): a prompt, a two-cue sweep, no hands. The
+#                        session runs in step mode, Next pressed by itself (--next-after): each
+#                        step is a recording part of its own, with its 3 s countdown, so about
+#                        18 s are recorded in all, a few hundred MB before compression
+#   --keep               keep the temporary folders (camera images of a room: delete them after)
+#
+# It runs in the dev container (where ft-hands, ft-handpanel, zstd and huggingface_hub are),
+# and in one frame-job scope when frame-job is installed, so it stays capped while the headset
+# is worn. Everything goes in temporary folders that are deleted at the end, and every process
+# it started is stopped, also on Ctrl+C. A tracking ft-hands that's already running is used as
+# it is; otherwise one is started for the rehearsal (it publishes the usual hands file).
+set -euo pipefail
+here=$(cd "$(dirname "$(readlink -f "$0")")" && pwd)
+root=$(cd "$here/../.." && pwd)
+uid=$(id -u)
+
+if [ ! -e /run/.containerenv ]; then
+  "$root/scripts/container-up.sh"
+  # Ctrl+C and kill don't reach through distrobox: the rehearsal inside writes its PID to this
+  # file, and a signal here is passed on to it, so it still cleans up.
+  pidfile=$(mktemp "/run/user/$uid/ft-handrec-rehearse-pid.XXXXXX")
+  # The real user bus, so frame-job's systemd-run reaches the host's user manager.
+  "$HOME/.local/bin/distrobox" enter dev -- env DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/$uid/bus" \
+    XDG_RUNTIME_DIR="/run/user/$uid" FT_REHEARSE_PIDFILE="$pidfile" bash "$here/rehearse.sh" "$@" </dev/null &
+  child=$! stopping=0 status=0
+  pass_on() { [ -s "$pidfile" ] && kill -TERM "$(cat "$pidfile")" 2>/dev/null; return 0; }
+  trap 'stopping=1; pass_on' INT TERM HUP
+  while kill -0 "$child" 2>/dev/null; do
+    wait "$child" && status=0 || status=$?   # (set -e would end this on a signal)
+    [ "$stopping" = 0 ] || pass_on
+  done
+  rm -f "$pidfile"
+  exit "$status"
+fi
+if [ -z "${FT_REHEARSE_SCOPE:-}" ] && command -v frame-job >/dev/null; then
+  export FT_REHEARSE_SCOPE=1
+  cd /tmp   # no .frame-job up from here: it runs locally, capped
+  exec frame-job --local -- bash "$here/rehearse.sh" "$@"
+fi
+[ -z "${FT_REHEARSE_PIDFILE:-}" ] || echo $$ >"$FT_REHEARSE_PIDFILE"
+
+repo="" capture="$HOME/Desktop/Projects/frame-hands/captures/rec-20260930-103803-lit" from=60 prompt_s=3 keep=0
+while [ $# -gt 0 ]; do
+  case $1 in
+    --repo) repo=$2; shift 2 ;;
+    --capture) capture=$2; shift 2 ;;
+    --from) from=$2; shift 2 ;;
+    --prompt-seconds) prompt_s=$2; shift 2 ;;
+    --keep) keep=1; shift ;;
+    -h|--help) sed -n '2,/^set -euo/p' "$0" | sed '$d; s/^# \{0,1\}//'; exit 0 ;;
+    *) echo "rehearse: unknown option $1" >&2; exit 2 ;;
+  esac
+done
+
+ringplay=$root/hands/build/ft-ringplay
+hands=$root/hands/build/ft-hands
+panel=$here/build/ft-handpanel
+for b in "$ringplay" "$hands"; do
+  [ -x "$b" ] || { echo "rehearse: $b isn't built: hands/build.sh --tools" >&2; exit 1; }
+done
+[ -x "$panel" ] || { echo "rehearse: $panel isn't built: hands/rec/build.sh" >&2; exit 1; }
+[ -f "$capture/sets.bin" ] || { echo "rehearse: no recording in $capture" >&2; exit 1; }
+if pgrep -x ft-handpanel >/dev/null; then
+  echo "rehearse: an ft-handpanel is running (a real session?): try again when it's done" >&2
+  exit 1
+fi
+if [ -n "$repo" ]; then
+  if python3 -c "import sys; sys.path.insert(0, '$here'); import hub; sys.exit(0 if hub.upload_allowed() else 1)"; then :; else
+    echo "rehearse: the texts are drafts: a real upload needs FT_HANDREC_ALLOW_UPLOAD=1 as well as --repo" >&2
+    exit 1
+  fi
+  python3 -c "import huggingface_hub" 2>/dev/null || {
+    echo "rehearse: huggingface_hub isn't installed: setup/dev-container.sh" >&2; exit 1; }
+fi
+
+# The data: the ring in the runtime folder (memory), the rest in /tmp. Both go at the end.
+work=$(mktemp -d "${TMPDIR:-/tmp}/ft-handrec-rehearse.XXXXXX")
+ringdir=$(mktemp -d "/run/user/$uid/ft-handrec-rehearse.XXXXXX")
+base=$work/base ring=$ringdir/cam-ring logs=$work/logs
+mkdir -p "$base" "$logs"
+pids=()
+cleanup() {
+  local code=$?
+  # Finish even if more signals come: frame-job stops its scope with SIGTERM to every process
+  # in it when it's interrupted.
+  trap '' INT TERM HUP
+  trap - EXIT
+  for p in "${pids[@]}"; do kill "$p" 2>/dev/null || true; done
+  for p in "${pids[@]}"; do wait "$p" 2>/dev/null || true; done
+  if [ "$keep" = 1 ]; then
+    echo "kept: $work and $ringdir (camera images of a room: delete them when done)"
+  else
+    rm -rf "$work" "$ringdir"
+  fi
+  exit "$code"
+}
+trap cleanup EXIT
+trap 'exit 130' INT TERM
+t0=$(date +%s)
+step() { echo; echo "== $*"; }
+# Long steps run in the background and are waited for: a signal then ends the wait at once,
+# and cleanup stops them (bash runs traps only after a foreground command ends).
+run() { "$@" & local p=$!; pids+=("$p"); wait "$p"; }
+indent() { sed 's/^/  /'; }
+
+step "1. Playing ${capture##*/} from ${from} s into $ring"
+"$ringplay" "$capture" --ring "$ring" --from "$from" --to "$((from + 30))" --loop >"$logs/ringplay.log" 2>&1 &
+pids+=($!)
+for _ in $(seq 100); do
+  python3 -c "import sys; sys.path.insert(0, '$here'); import session
+r = session.Ring('$ring'); sys.exit(0 if r.alive() else 1)" 2>/dev/null && break
+  sleep 0.2
+done
+python3 -c "import sys; sys.path.insert(0, '$here'); import session
+r = session.Ring('$ring'); print('  cameras:', ', '.join('%s %dx%d' % (c['name'], c['width'], c['height']) for c in r.cams))
+sys.exit(0 if r.alive() else 1)" || { echo "rehearse: ft-ringplay doesn't publish: $(tail -3 "$logs/ringplay.log")" >&2; exit 1; }
+
+step "2. Session (test script, panel --no-vr)"
+tracker=existing
+if ! python3 -c "import sys; sys.path.insert(0, '$here'); import session; sys.exit(0 if session.tracker_running() else 1)"; then
+  "$hands" --ring "$ring" --no-gestures --status 0 >"$logs/tracker.log" 2>&1 &
+  pids+=($!)
+  tracker=started
+fi
+echo "  tracker: $tracker"
+"$panel" --no-vr >"$logs/panel.log" 2>&1 &
+pids+=($!)
+python3 - "$here" "$base" "$prompt_s" "$work/script.json" <<'EOF'
+import json, os, re, sys, uuid
+here, base, secs, out = sys.argv[1], sys.argv[2], float(sys.argv[3]), sys.argv[4]
+consent = re.search(r"^Version:\s*(\S+)", open(os.path.join(here, "CONSENT.md")).read(), re.M).group(1)
+json.dump({"schema": 1, "contributor": str(uuid.uuid4()),
+           "consent": {"version": consent, "accepted": "2026-10-02T00:00:00+00:00", "adult": True},
+           "optional": {"handedness": "", "notes": ""}}, open(os.path.join(base, "profile.json"), "w"))
+json.dump({"version": 1, "intro_s": 1, "between_s": 1,
+           "welcome": {"title": "Rehearsal", "seconds": 1, "text": "A rehearsal of the hand recorder."},
+           "done": {"title": "Done", "seconds": 1, "text": "Rehearsal done."},
+           "stopped": {"title": "Stopped", "seconds": 1, "text": "Rehearsal stopped."},
+           "sections": [
+               {"id": "hand-size", "title": "Hand size", "intro": "Rehearsal: hands.",
+                "prompts": [{"text": "Both hands flat, palms toward you.", "seconds": secs, "hands": "both",
+                             "pose": "flat", "distance": "mid"}]},
+               {"id": "pose-sweeps", "title": "Hand poses", "kind": "sweep", "intro": "", "cue_s": secs / 2,
+                "groups": [["open", "fist"]], "sweeps": [{"hands": "both", "group": "next", "text": "Keep moving."}]},
+               {"id": "no-hands", "title": "No hands", "intro": "",
+                "prompts": [{"text": "Hands out of view.", "seconds": secs, "hands": "none"}]}]},
+          open(out, "w"))
+EOF
+for _ in $(seq 50); do
+  python3 -c "import sys; sys.path.insert(0, '$here'); import session
+sys.exit(0 if session.Panel().cmd('ping', reply=True) else 1)" 2>/dev/null && break
+  sleep 0.2
+done
+run python3 "$here/session.py" --ring "$ring" --no-start --base "$base" --script "$work/script.json" --lighting room \
+  --next-after 0.3 \
+  </dev/null > >(indent)
+sid=$(ls "$base/sessions" | tail -1)
+[ -n "$sid" ] || { echo "rehearse: the session left nothing" >&2; exit 1; }
+python3 "$here/takes.py" --base "$base" takes "$sid" | sed 's/^/  /'
+echo "  panel pictures: $(grep -c '^--- picture' "$logs/panel.log" || true)"
+
+step "3. Export"
+run python3 "$here/takes.py" --base "$base" export "$sid" >"$logs/export.log"
+tr '\r' '\n' <"$logs/export.log" | tail -1 | indent
+export_dir=$base/exports/$sid
+
+step "4. Validate"
+valid=1
+run python3 "$here/validate.py" "$export_dir" --json >"$work/validate.json" || valid=0
+python3 -c "import json, sys; v = json.load(open(sys.argv[1]))
+for k in ('errors', 'warnings'):
+    for line in v[k]: print('  %s: %s' % (k[:-1], line))
+print('  OK' if v['ok'] else '  %d errors' % len(v['errors']))" "$work/validate.json"
+[ "$valid" = 1 ] || { echo "rehearse: the export didn't validate" >&2; exit 1; }
+
+if [ -n "$repo" ]; then
+  step "5. Upload to $repo (for real)"
+  run env FT_HANDREC_DATASET="$repo" python3 "$here/hub.py" --base "$base" upload "$sid" >"$logs/hub.log"
+  indent <"$logs/hub.log"
+else
+  step "5. Upload (dry run: --repo ID uploads for real)"
+  run python3 "$here/hub.py" --base "$base" upload "$sid" --dry-run >"$logs/hub.log"
+  indent <"$logs/hub.log"
+fi
+
+step "Summary"
+python3 - "$work/validate.json" "$logs/hub.log" "$tracker" "$(( $(date +%s) - t0 ))" <<'EOF'
+import json, sys
+v = json.load(open(sys.argv[1]))
+s = v["summary"]
+hub = open(sys.argv[2]).read().strip().splitlines()
+print(f"  session {s['session']}: {s['takes']} takes, {s['sets']} sets, {s['minutes']} min recorded")
+print(f"  export: {v['bytes'] / 1e6:.1f} MB, {len(v['errors'])} errors, {len(v['warnings'])} warnings")
+for w in v["warnings"]:
+    print(f"    warning: {w}")
+print(f"  hub: {hub[-1] if hub else '-'}")
+print(f"  tracker: {sys.argv[3]}; took {sys.argv[4]} s")
+EOF
diff --git a/hands/rec/script.json b/hands/rec/script.json
new file mode 100644
index 0000000..e61132e
--- /dev/null
+++ b/hands/rec/script.json
@@ -0,0 +1,118 @@
+{
+ "version": 1,
+ "intro_s": 4,
+ "between_s": 3,
+ "welcome": {"title": "Hand recorder", "seconds": 7,
+  "text": "Follow the steps on this panel. Each one shows what to do with your hands, and where. A bar shows the time left.|The button on the right side of the headset goes on when a step waits for you, and pauses while recording."},
+ "done": {"title": "All done", "seconds": 6,
+  "text": "Thank you! You can take off the headset.|Review your recordings in the Hand recorder window."},
+ "stopped": {"title": "Stopped", "seconds": 4,
+  "text": "What was recorded so far is saved. Review it in the Hand recorder window."},
+ "cue_names": {"flat": "Flat", "flat-back": "Backs", "spread": "Spread", "open": "Open", "fist": "Fist",
+  "point": "Point", "pinch": "Pinch", "ok": "OK", "thumbs-up": "Thumbs up", "claw": "Claw", "count-1": "1",
+  "count-2": "2", "count-3": "3", "count-4": "4", "count-5": "5", "pinch-tap": "Tap", "pinch-drag": "Drag",
+  "grab": "Grab", "cross": "Cross", "overlap": "Overlap", "near-face": "Face", "screen-point": "Screen",
+  "mouse": "Mouse", "switch": "Switch"},
+ "objects": {"pencil": "pencil or pen", "phone": "phone", "cup": "cup", "keyboard": "keyboard",
+  "mouse": "mouse", "gamepad": "gamepad", "small": "small thing"},
+ "sections": [
+  {"id": "hand-size", "title": "Hand size", "requires": [], "go": "Hold", "quick": true,
+   "intro": "First, your hand size. Hold each shape still while its picture is lit.",
+   "defaults": {"hands": "both", "distance": "mid", "position": "centre"},
+   "prompts": [
+    {"text": "Both hands about 40 cm away, still. Make each lit shape: flat with palms toward you, then the backs toward you, then fingers spread wide.",
+     "cues": ["flat", "flat-back", "spread"], "cue_s": 5}
+   ]},
+
+  {"id": "pose-sweeps", "title": "Hand poses", "kind": "sweep", "requires": [], "quick": true,
+   "intro": "Now keep your hands moving slowly while they change shape. A picture lights up every few seconds: make that shape wherever your hands are. Close, far, high, low: all of it helps.",
+   "cue_s": 4, "step_s": 20,
+   "groups": [["open", "fist", "point", "pinch"], ["ok", "thumbs-up", "spread", "claw"],
+              ["count-1", "count-2", "count-3", "count-4", "count-5"]],
+   "sweeps": [
+    {"hands": "both", "group": "next", "text": "Both hands: move them slowly and keep going, from close to you out to arm's length and all around in front of you. Change shape with the lit picture."},
+    {"hands": "both", "group": "next", "text": "Both hands again: slowly near and far, high and low, left and right. Change shape with the lit picture."},
+    {"hands": "both", "group": "next", "text": "Both hands, still moving slowly all around in front of you. Change shape with the lit picture."},
+    {"hands": "left", "group": "any", "quick": false, "text": "Left hand only, the right one in your lap. Move it slowly near and far and all around, change shape with the lit picture, and turn your wrist as you go: palm toward you, then away."},
+    {"hands": "right", "group": "any", "quick": false, "text": "Right hand only, the left one in your lap. Move it slowly near and far and all around, change shape with the lit picture, and turn your wrist as you go: palm toward you, then away."}
+   ]},
+
+  {"id": "gestures", "title": "Gestures", "kind": "sweep", "requires": [], "shuffle": false, "cycle": false,
+   "intro": "Now some movements, at a calm, normal pace. Follow the lit picture.",
+   "defaults": {"hands": "both"},
+   "sweeps": [
+    {"id": "pinch", "cues": ["pinch-tap", "pinch-drag"], "cue_s": 8,
+     "text": "Both hands: tap thumb and index finger together a few times. Then pinch, drag slowly to the side and let go, again and again."},
+    {"id": "grab-cross", "cues": ["grab", "cross", "overlap"], "cue_s": 6,
+     "text": "Grab as if holding a bar and open again. Then cross your hands and uncross them. Then hold one over the other and slide them around."},
+    {"id": "face-screen", "cues": ["near-face", "screen-point"], "cue_s": 8,
+     "text": "Move your hands close around your face, without touching the headset. Then reach out to where a screen would be and point at things on it."}
+   ]},
+
+  {"id": "desk-work", "title": "Desk work", "requires": [],
+   "intro": "Now your desk. Look down at your hands while you work.",
+   "defaults": {"hands": "both", "position": "down"},
+   "prompts": [
+    {"when": "objects:keyboard", "text": "Type on your keyboard the way you normally do. Any text is fine.", "seconds": 10, "pose": "typing", "object": "keyboard"},
+    {"when": "!objects:keyboard", "text": "Rest your hands on the desk and pretend to type.", "seconds": 10, "pose": "typing"},
+    {"when": ["objects:mouse", "objects:keyboard"], "text": "Use your mouse: move it and click. When the picture changes, switch between the mouse and the keyboard a few times.", "cues": ["mouse", "switch"], "cue_s": 6, "object": "mouse"},
+    {"when": ["objects:mouse", "!objects:keyboard"], "text": "Use your mouse: move it around and click a few times.", "seconds": 10, "hands": "right", "pose": "mouse", "object": "mouse"},
+    {"when": "!objects:mouse", "text": "Put one hand flat on the desk and slide it around, as if using a mouse.", "seconds": 10, "hands": "right", "pose": "mouse"}
+   ]},
+
+  {"id": "objects", "title": "Things you hold", "requires": ["objects"], "for_each": "object",
+   "skip_objects": ["keyboard", "mouse"],
+   "intro": "Now the things you set out. Use each one the way you normally would.",
+   "defaults": {"hands": "both"},
+   "prompts": [
+    {"text": "Pick up the {object}, use it for a moment, then put it down.", "seconds": 12, "pose": "hold", "object": "{object}"}
+   ]},
+
+  {"id": "touch", "title": "Touch the dot", "kind": "targets", "requires": [], "quick": true,
+   "intro": "A small dot will appear. Touch it with your index fingertip and hold still until it turns green.",
+   "defaults": {"hands": "any", "pose": "point"},
+   "hold_s": 1.0, "timeout_s": 8,
+   "text": "Touch the dot with your index fingertip and hold still.",
+   "targets": [[0.00, -0.20, -0.25], [-0.20, -0.10, -0.40], [0.20, -0.10, -0.40], [-0.15, -0.25, -0.35],
+               [0.25, -0.05, -0.50], [0.05, -0.10, -0.55]]},
+
+  {"id": "controller-push", "title": "Depth with controllers", "kind": "bar", "requires": ["controllers"],
+   "before": {"text": "Put on both controllers and tighten the straps. Take your time.", "seconds": 25},
+   "intro": "Push both hands straight out in front of you, away from the headset, then pull them back toward it. Only nearer and farther, not sideways. Follow the hollow circle on the bar: right is arm out, left is at your chest. The blue dot is the current hand tracking's guess at how far your hands are. It's only an approximation and often wrong, so ignore it.",
+   "defaults": {"hands": "both", "pose": "open", "picture": "push-controller", "controller": true, "controllers": ["left", "right"]},
+   "near_m": 0.2, "far_m": 0.6, "near_label": "At your chest", "far_label": "Arm out", "period_s": 6, "lead_s": 3, "reps": 3,
+   "heights": [
+    {"id": "chest", "text": "Chest height, palms out like a stop sign. Push straight out, away from the headset, then pull back to your chest. Follow the hollow circle, not the blue dot."},
+    {"id": "eye", "text": "Now at eye level, palms out. Push straight out, away from the headset, then pull back toward it. Follow the hollow circle, not the blue dot."}
+   ],
+   "prompts": [
+    {"text": "Controllers on: slowly turn your wrists, and open and close your hands, a few times.", "seconds": 10, "pose": "open-close", "distance": "mid"}
+   ]},
+
+  {"id": "bridge", "title": "Controller and fingertip", "requires": ["controllers"],
+   "intro": "Now one controller on and one hand bare. The thumbstick is the point to touch.",
+   "defaults": {"controller": true},
+   "prompts": [
+    {"text": "Left controller on, the right one off on the desk. Touch the left thumbstick with your right index fingertip, and keep touching it while you move your left hand slowly from close to you out to arm's length and back.", "seconds": 12, "hands": "both", "pose": "touch-stick", "controllers": ["left"]},
+    {"text": "Swap: right controller on, the left one off. Touch the right thumbstick with your left index fingertip, and keep touching it while you move your right hand slowly from close to you out to arm's length and back.", "seconds": 12, "hands": "both", "pose": "touch-stick", "picture_mirror": true, "controllers": ["right"]},
+    {"text": "Put the right controller on the desk in front of you. Touch its thumbstick with your index fingertip from the front, then from above.", "seconds": 8, "hands": "any", "pose": "touch-stick", "picture": "touch-stick-desk", "position": "down"},
+    {"text": "Now touch it reaching from the left, then from the right.", "seconds": 8, "hands": "any", "pose": "touch-stick", "picture": "touch-stick-desk", "position": "down"}
+   ]},
+
+  {"id": "bare-push", "title": "Depth, bare hands", "kind": "bar", "requires": [],
+   "before": {"when": "controllers", "text": "Take the controllers off and put them out of view.", "seconds": 15},
+   "intro": "Push both hands straight out in front of you, away from the headset, then pull them back toward it. Only nearer and farther, not sideways. Follow the hollow circle on the bar: right is arm out, left is at your chest. The blue dot is the current hand tracking's guess at how far your hands are. It's only an approximation and often wrong, so ignore it.",
+   "defaults": {"hands": "both", "pose": "open", "picture": "push"},
+   "near_m": 0.2, "far_m": 0.6, "near_label": "At your chest", "far_label": "Arm out", "period_s": 6, "lead_s": 3, "reps": 3,
+   "heights": [
+    {"id": "chest", "text": "Chest height, palms out like a stop sign. Push straight out, away from the headset, then pull back to your chest. Follow the hollow circle, not the blue dot."},
+    {"id": "eye", "text": "Now at eye level, palms out. Push straight out, away from the headset, then pull back toward it. Follow the hollow circle, not the blue dot."}
+   ]},
+
+  {"id": "no-hands", "title": "No hands", "requires": [], "quick": true,
+   "intro": "Last one: put your hands down, out of view.",
+   "prompts": [
+    {"text": "Keep your hands out of view and look slowly around the room.", "seconds": 10, "hands": "none", "picture": "no-hands"}
+   ]}
+ ]
+}
diff --git a/hands/rec/session.py b/hands/rec/session.py
new file mode 100755
index 0000000..33ab5d2
--- /dev/null
+++ b/hands/rec/session.py
@@ -0,0 +1,2587 @@
+#!/usr/bin/env python3
+"""The hand recorder's session runner (DESIGN.md: "Processes during a session", "Files", "The
+script", "Feedback while recording", "Controls").
+
+It reads script.json, starts what the session needs (ft-camd and a tracking ft-hands, only if
+they aren't running), and runs the sections in order. Each section is one take: a recording
+ft-hands child process (--record-only, 10 sets a second) plus prompts.jsonl, take.json and the
+panel's poses.jsonl. The headset panel (ft-handpanel) shows the prompts; the live hands file
+gives feedback ("I can't see your left hand").
+
+Plain Python, standard library only: ft_handrec.py imports it, and it runs from the command line
+for testing (in the dev container):
+
+  python3 hands/rec/session.py --dry-run --speed 20 --next-after 0.2   # no processes: prints the panel commands
+  python3 hands/rec/session.py --ring /tmp/ring --base /tmp/hr        # ft-ringplay's frames, no headset needed
+
+Before anything starts it runs the camera check (hands/camcheck.py) and won't start while the
+upper cameras are off (--ignore-cameras overrides it). If the hand-size section's first step sees
+no hands at all, it stops that step and asks: try again, or stop (DESIGN.md, "Camera check").
+
+Step mode (the default) shows each step and waits for Next (Space in the window, n or Enter
+here); a 3-2-1 countdown, recorded, then the hold. Only the countdowns and holds are recorded:
+each is a part of the take's recording (sets-N.bin). --auto is the old timed flow.
+
+All _ns times are CLOCK_MONOTONIC nanoseconds.
+"""
+import argparse
+import glob
+import hashlib
+import json
+import math
+import mmap
+import os
+import random
+import re
+import select
+import shutil
+import signal
+import socket
+import struct
+import subprocess
+import sys
+import threading
+import time
+import traceback
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+REPO = os.path.dirname(os.path.dirname(HERE))
+HANDS = os.path.join(REPO, "hands")
+sys.path.insert(0, HANDS)
+import camcheck  # noqa: E402  (hands/camcheck.py: are all four mono cameras running?)
+sys.path.insert(0, HERE)
+import sides  # noqa: E402  (hands/rec/sides.py: which side camera is which)
+FT_HANDS = os.path.join(HANDS, "build", "ft-hands")
+FT_CAMD = os.path.join(HANDS, "build", "ft-camd")
+PANEL_BIN = os.path.join(HERE, "build", "ft-handpanel")
+SCRIPT_PATH = os.path.join(HERE, "script.json")
+POSES_DIR = os.path.join(HERE, "poses")   # the pose pictures: poses.json and its PNGs
+BASE_DIR = os.path.expanduser("~/.local/share/frametop/hands/contrib")
+PANEL_SOCKET = "ft_handpanel"
+CAMD_UNIT = "frametop-handrec-camd.service"
+HANDS_UNIT = "frametop-handrec-hands.service"
+
+RECORD_HZ = 10
+SIDES_READ_S = 0.5       # how often the tracking ft-hands' side camera decision is read
+TICK_S = 0.05            # the session loop's step (real time)
+FRESH_S = 0.3            # the hands file counts as live if published this recently
+LOST_S = 1.5             # an asked-for hand lost this long gets a note
+CONTROLLER_LOST_S = 1.0  # a controller off 200 (Running_OK) this long gets a note
+TOUCH_M = 0.03           # touch the dot: the index tip within this of the dot
+MIN_FREE = 1.5e9         # stop the session before the disk fills
+COUNTDOWN_S = 3          # step mode: the 3-2-1 before each step, recorded
+FIRST_SET_S = 3.0        # step mode: how long the hold may wait for its recording's first set
+RESUME_HINT = "Paused. Resume: P in the Hand recorder window"
+READY_TEXT = "Ready? Press Space or click Next"
+# With the headset's button: it leads when no mouse is connected (the window's Next can't be clicked).
+READY_BUTTON = "Ready? Press the button on the right side of the headset"
+READY_BUTTON_MOUSE = "Ready? Press Space, click Next, or press the headset button"
+KEYS_STEP = "Hand recorder window:  Space next  \u00b7  P pause  \u00b7  R redo  \u00b7  S skip section  \u00b7  Esc stop"
+KEYS_AUTO = "Hand recorder window:  P pause  \u00b7  R redo  \u00b7  S skip section  \u00b7  Esc stop"
+KEYS_STEP_BUTTON = ("Headset button: next, pause  \u00b7  Window: Space next  \u00b7  P pause  \u00b7  R redo  "
+                    "\u00b7  S skip  \u00b7  Esc stop")
+KEYS_AUTO_BUTTON = "Headset button: pause  \u00b7  Window: P pause  \u00b7  R redo  \u00b7  S skip section  \u00b7  Esc stop"
+# The early no-hands stop (DESIGN.md, "Camera check"): the first step of this section has both
+# hands up. If the live tracker publishes through its hold and never sees a hand, the session
+# stops that step and asks: try again, or stop. Only when the tracker published in at least
+# HANDS_CHECK_PUBLISHED of at least HANDS_CHECK_MIN_READS reads (about 20 a second): without
+# a tracker it can't tell.
+HANDS_CHECK_SECTION = "hand-size"
+HANDS_CHECK_MIN_READS = 10
+HANDS_CHECK_PUBLISHED = 0.5
+NO_HANDS_TITLE = "I can't see your hands"
+NO_HANDS_TEXT = "The hand tracker didn't see either of your hands during that whole step."
+NO_HANDS_RETRY = ("Try again: hold both hands up in front of you, about 40 cm away. To stop instead: "
+                  "Esc or Stop in the Hand recorder window.")
+
+
+def mono_ns():
+    return time.clock_gettime_ns(time.CLOCK_MONOTONIC)
+
+
+def clock_sample():
+    """[CLOCK_MONOTONIC ns, CLOCK_MONOTONIC_RAW - CLOCK_MONOTONIC ns], as ft-hands' raw_minus_mono_ns().
+    sets.bin's capture_ns is on the RAW clock and everything else on MONOTONIC; the two drift
+    apart with NTP's corrections (0.8 s apart and ~10 ppm on 2026-10-03), so take.json keeps
+    samples to turn capture_ns into MONOTONIC: capture_ns - offset, interpolated by time."""
+    a = time.clock_gettime_ns(time.CLOCK_MONOTONIC)
+    r = time.clock_gettime_ns(time.CLOCK_MONOTONIC_RAW)
+    b = time.clock_gettime_ns(time.CLOCK_MONOTONIC)
+    mid = (a + b) // 2
+    return [mid, r - mid]
+
+
+def run_dir():
+    return "/run/user/%d/frametop-hands" % os.getuid()
+
+
+def in_container():
+    return os.path.exists("/run/.containerenv") or os.path.exists("/.dockerenv")
+
+
+def host_command(*cmd):
+    """argv to run a command on the SteamOS host from the dev container (as in
+    display-settings: distrobox-host-exec needs the user's real session bus). It runs from the
+    home folder: host-spawn starts the command in the caller's folder, and a container-only
+    one such as /run/host/tmp doesn't exist on the host (every command then exits 127)."""
+    exe = shutil.which("distrobox-host-exec")
+    if not in_container() or not exe:
+        return list(cmd)
+    return ["env", "-C", os.path.expanduser("~"), "DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/%d/bus" % os.getuid(),
+            exe] + list(cmd)
+
+
+def host_path(path):
+    """A host file, from the container (/run/host) or the host itself."""
+    for p in ("/run/host" + path, path):
+        if os.path.exists(p):
+            return p
+    return None
+
+
+def write_json(path, data):
+    tmp = path + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump(data, f, indent=1)
+        f.write("\n")
+    os.replace(tmp, path)
+
+
+def clean_text(s):
+    """Text for a panel command: one line; "|" is the panel's line break, so callers use it."""
+    return " ".join(str(s).replace("\r", " ").replace("\n", " ").split())
+
+
+# ------------------------------------------------------------------------------------------
+# The camera ring (camd/fhring.h; tools/ring.py's layout, struct only)
+
+RING_HDR = struct.Struct("<8sIIIIQqQ16x")              # 64 bytes
+RING_CAM = struct.Struct("<32s32siIIIIIQQQQQIf24x")      # 160 bytes
+RING_SLOT = struct.Struct("<QQQQQIf16x")                 # 64 bytes, the image follows
+FH_CAM_DARK, FH_CAM_COLOR = 1, 2
+
+
+class Ring:
+    def __init__(self, path):
+        fd = os.open(path, os.O_RDONLY)
+        try:
+            self.map = mmap.mmap(fd, 0, mmap.MAP_SHARED, mmap.PROT_READ)
+        finally:
+            os.close(fd)
+        magic, version, _, ncams, _, _, self.writer_pid, _ = RING_HDR.unpack_from(self.map, 0)
+        if magic != b"FHRING01" or version != 1:
+            self.map.close()
+            raise ValueError("%s isn't a camera ring" % path)
+        self.cams = []
+        for i in range(min(ncams, 8)):
+            f = RING_CAM.unpack_from(self.map, RING_HDR.size + i * RING_CAM.size)
+            self.cams.append({
+                "index": i, "sensor": f[0].split(b"\0", 1)[0].decode(errors="replace"),
+                "name": f[1].split(b"\0", 1)[0].decode(errors="replace"), "node": f[2],
+                "width": f[4], "height": f[5], "stride": f[6], "nslots": f[7],
+                "slot_offset": f[8], "slot_bytes": f[9], "flags": f[13]})
+
+    def close(self):
+        self.map.close()
+
+    def alive(self, max_age=1.0):
+        hb = struct.unpack_from("<Q", self.map, 40)[0]
+        return hb != 0 and (mono_ns() - hb) / 1e9 < max_age
+
+    def _cam_field(self, cam, fmt, off):
+        return struct.unpack_from(fmt, self.map, RING_HDR.size + cam["index"] * RING_CAM.size + off)[0]
+
+    def latest(self, cam):
+        return self._cam_field(cam, "<Q", 104)
+
+    def dark_mean(self, cam):
+        return self._cam_field(cam, "<f", 132)
+
+    def mono(self):
+        """The mono tracking cameras (no dark twins, no colour cameras, also by name for
+        ft-ringplay's rings, which carry no flags)."""
+        return [c for c in self.cams if not c["flags"] & (FH_CAM_DARK | FH_CAM_COLOR)
+                and not c["name"].endswith("_dk") and not c["name"].startswith("color")]
+
+    def frame_mean(self, cam):
+        """The newest frame's mean luma: ft-camd's from the slot header, else (ft-ringplay
+        leaves it 0) measured on a sparse grid. None if there's no complete frame."""
+        n = self.latest(cam)
+        if not n:
+            return None
+        off = cam["slot_offset"] + (n % cam["nslots"]) * cam["slot_bytes"]
+        seq, _, _, _, _, _, mean = RING_SLOT.unpack_from(self.map, off)
+        if seq != 2 * n + 2:
+            return None
+        if mean <= 0:
+            img, total, count = off + RING_SLOT.size, 0, 0
+            for y in range(0, cam["height"], 16):
+                row = self.map[img + y * cam["stride"]: img + y * cam["stride"] + cam["width"]: 16]
+                total += sum(row)
+                count += len(row)
+            mean = total / count if count else 0.0
+        if struct.unpack_from("<Q", self.map, off)[0] != seq:
+            return None
+        return float(mean)
+
+
+def ring_lighting(ring_path=None, samples=5, interval=0.2):
+    """Each mono camera's brightness now: {"<cam>": {"mean": float, "dark_mean": float}}, the
+    newest frames' mean luma and ft-camd's near-black frame mean (the room's IR light), averaged
+    over about a second. None if no camera ring is running."""
+    path = ring_path or os.path.join(run_dir(), "cam-ring")
+    try:
+        ring = Ring(path)
+    except (OSError, ValueError):
+        return None
+    try:
+        if not ring.alive():
+            return None
+        sums = {}
+        for k in range(samples):
+            for cam in ring.mono():
+                m = ring.frame_mean(cam)
+                s = sums.setdefault(cam["name"], [0.0, 0, 0.0, 0])
+                if m is not None:
+                    s[0] += m
+                    s[1] += 1
+                s[2] += ring.dark_mean(cam)
+                s[3] += 1
+            if k + 1 < samples:
+                time.sleep(interval)
+        out = {name: {"mean": round(s[0] / s[1], 2) if s[1] else 0.0,
+                      "dark_mean": round(s[2] / s[3], 2) if s[3] else 0.0} for name, s in sums.items()}
+        return out or None
+    finally:
+        ring.close()
+
+
+def _light_levels(ring):
+    vals = [v for v in (ring or {}).values() if isinstance(v, dict)]
+    if not vals:
+        return None
+    return (sum(float(v.get("mean", 0)) for v in vals) / len(vals),
+            sum(float(v.get("dark_mean", 0)) for v in vals) / len(vals))
+
+
+def _close(a, b, share=0.15, floor=1.0):
+    """Within 15% of the larger; the floor keeps near-black levels (a dim room's dark mean is a
+    few levels) from looking different over sensor noise."""
+    return abs(a - b) <= max(share * max(abs(a), abs(b)), floor)
+
+
+def similar_lighting(base_dir, lighting):
+    """An earlier session whose cameras saw about the same light (the mean of every mono
+    camera's mean and dark_mean, each within 15%): (session_id, chosen), the latest such, or
+    None. lighting is ring_lighting()'s dict, or session.json's {"chosen", "ring"}."""
+    if not lighting:
+        return None
+    ring = lighting.get("ring") if isinstance(lighting.get("ring"), dict) else lighting
+    now = _light_levels(ring)
+    if not now:
+        return None
+    for path in sorted(glob.glob(os.path.join(base_dir, "sessions", "*", "session.json")), reverse=True):
+        try:
+            with open(path) as f:
+                light = json.load(f).get("lighting") or {}
+        except (OSError, ValueError):
+            continue
+        then = _light_levels(light.get("ring"))
+        if then and _close(now[0], then[0]) and _close(now[1], then[1]):
+            return os.path.basename(os.path.dirname(path)), light.get("chosen", "")
+    return None
+
+
+DAYLIGHT_IR = 6.0   # ambient IR (the mono cameras' mean dark_mean) from which it's daylight
+
+
+def ambient_ir(ring):
+    """The mono cameras' mean dark_mean (the room's infrared light, as ft-hands logs it), or
+    None if none has one. ring is ring_lighting()'s dict."""
+    vals = [float(v.get("dark_mean", 0)) for v in (ring or {}).values() if isinstance(v, dict)]
+    vals = [v for v in vals if v > 0]
+    return round(sum(vals) / len(vals), 2) if vals else None
+
+
+def classify_lighting(ring):
+    """"daylight" or "indoor" from the room's infrared light, "" if it can't tell. Sunlight
+    carries a lot of infrared; lamps and LEDs hardly any, so a dim room and a bright one read
+    about the same (2026-10: 1.8 by one lamp, 2.2 in a lamp-lit room) and aren't told apart."""
+    ir = ambient_ir(ring)
+    if ir is None:
+        return ""
+    return "daylight" if ir >= DAYLIGHT_IR else "indoor"
+
+
+def lighting_record(choice, ring):
+    """session.json's "lighting": chosen is the person's pick, or with "auto" (or none) what
+    the cameras measured; measured and ambient_ir are always the cameras' reading."""
+    measured = classify_lighting(ring)
+    picked = choice if choice in ("dim", "room", "daylight") else ""
+    return {"chosen": picked or measured, "source": "picked" if picked else "measured",
+            "measured": measured, "ambient_ir": ambient_ir(ring), "ring": ring or {}}
+
+
+def unit_active(unit):
+    return subprocess.run(host_command("systemctl", "--user", "-q", "is-active", unit),
+                          capture_output=True, timeout=30).returncode == 0
+
+
+def start_unit(unit, what, argv, log=lambda line: None):
+    """Start argv as a transient user unit that stops with SteamVR. True if it started it,
+    False if it was running already; raises RuntimeError if it couldn't."""
+    if unit_active(unit):
+        log("%s is running already" % unit)
+        return False
+    cmd = host_command("systemd-run", "--user", "--quiet", "--collect", "--unit=" + unit,
+                       "--description=Frametop hand recorder: " + what,
+                       "-p", "PartOf=steamvr.service", "-p", "After=steamvr.service",
+                       "-p", "Restart=on-failure", "-p", "RestartSec=3", "-p", "TimeoutStopSec=5", *argv)
+    for attempt in range(3):   # distrobox-host-exec has failed once, silently, and worked again
+        r = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+        if r.returncode == 0 or unit_active(unit):
+            log("started %s" % unit)
+            return True
+        log("starting %s failed (exit %d): %s" % (unit, r.returncode, (r.stderr or r.stdout).strip()))
+        time.sleep(0.5)
+    raise RuntimeError("couldn't start %s (exit %d): %s" % (unit, r.returncode, (r.stderr or r.stdout).strip()))
+
+
+def stop_unit(unit):
+    subprocess.run(host_command("systemctl", "--user", "stop", unit), capture_output=True, timeout=30)
+
+
+def ring_alive(path=None):
+    try:
+        r = Ring(path or os.path.join(run_dir(), "cam-ring"))
+    except (OSError, ValueError):
+        return False
+    try:
+        return r.alive()
+    finally:
+        r.close()
+
+
+def start_camd(path=None, log=lambda line: None, stop=lambda: False, timeout=15.0):
+    """Make sure ft-camd fills the camera ring: start it (CAMD_UNIT) if nothing does. True if
+    it started it, False if a ring was live already; raises RuntimeError if it can't."""
+    path = path or os.path.join(run_dir(), "cam-ring")
+    if ring_alive(path):
+        return False
+    if not os.access(FT_CAMD, os.X_OK):
+        raise RuntimeError("ft-camd isn't built: hands/build.sh")
+    caps = subprocess.run(["getcap", FT_CAMD], capture_output=True, text=True) if shutil.which("getcap") else None
+    if caps is not None and "cap_sys_ptrace" not in caps.stdout:
+        raise RuntimeError("ft-camd needs its capabilities: hands/run.sh caps (asks for sudo)")
+    started = start_unit(CAMD_UNIT, "the camera broker", [FT_CAMD, "--status", "60"], log)
+    end = time.monotonic() + timeout
+    while time.monotonic() < end:
+        if ring_alive(path):
+            return started
+        if stop():
+            return started
+        time.sleep(0.1)
+    raise RuntimeError("ft-camd didn't start (is SteamVR running?): journalctl --user -u " + CAMD_UNIT)
+
+
+# ------------------------------------------------------------------------------------------
+# The factory calibration, without what identifies the unit
+
+ID_TOKENS = {"serial", "sn", "uuid", "guid", "mac", "id", "ids", "identifier"}
+
+
+def _key_identifies(key):
+    k = str(key)
+    if re.search(r"serial|uuid", k, re.I):
+        return True
+    tokens = re.findall(r"[A-Z]+(?![a-z])|[A-Z]?[a-z]+|\d+", k)
+    return any(t.lower() in ID_TOKENS for t in tokens)
+
+
+def _value_identifies(value):
+    """A string holding something like a serial number: a run of 8 or more letters and digits
+    with at least 4 digits and a letter (sensor names like og01a1b are shorter)."""
+    if not isinstance(value, str):
+        return False
+    for run in re.findall(r"[A-Za-z0-9]+", value):
+        if len(run) >= 8 and sum(c.isdigit() for c in run) >= 4 and any(c.isalpha() for c in run):
+            return True
+    return False
+
+
+def strip_calibration(xrservice_json_dict):
+    """/persist/xrservice.json without what identifies the unit: keys naming a serial, sn,
+    uuid, mac or id, and string values that look like serial numbers. Returns (cleaned dict,
+    removed key paths such as "cameras[0].serial")."""
+    removed = []
+
+    def walk(o, path):
+        if isinstance(o, dict):
+            out = {}
+            for k, v in o.items():
+                p = "%s.%s" % (path, k) if path else str(k)
+                if _key_identifies(k) or _value_identifies(v):
+                    removed.append(p)
+                    continue
+                out[k] = walk(v, p)
+            return out
+        if isinstance(o, list):
+            out = []
+            for i, v in enumerate(o):
+                p = "%s[%d]" % (path, i)
+                if _value_identifies(v):
+                    removed.append(p)
+                    out.append(None)   # keep the other items' positions
+                    continue
+                out.append(walk(v, p))
+            return out
+        return o
+
+    return walk(xrservice_json_dict, ""), removed
+
+
+# ------------------------------------------------------------------------------------------
+# The live hands file (include/fh_hands.h)
+
+HANDS_HDR = struct.Struct("<8sIIQQQII16x")    # 64 bytes
+HAND = struct.Struct("<IIff63fI")             # 272 bytes
+FH_HAND_RIGHT = 1
+PALM = (0, 5, 9, 13, 17)                      # wrist and knuckles
+INDEX_TIP = 8
+
+
+class HandsFile:
+    """Reads ft-hands' hands file under its sequence lock. read() gives None while no tracker
+    publishes (no file, or nothing for FRESH_S), else {"left": hand|None, "right": hand|None}
+    with hand = {"palm": [x,y,z], "palm_m": float, "tip": [x,y,z]} in the head frame."""
+
+    def __init__(self, path):
+        self.path = path
+
+    def read(self):
+        try:
+            fd = os.open(self.path, os.O_RDONLY)
+        except OSError:
+            return None
+        try:
+            size = HANDS_HDR.size + 2 * HAND.size
+            for _ in range(4):
+                data = os.pread(fd, size, 0)
+                if len(data) < size:
+                    return None
+                magic, version, _, seq, _, publish_ns, nhands, _ = HANDS_HDR.unpack_from(data, 0)
+                if magic != b"FHHANDS1" or version != 1:
+                    return None
+                if seq % 2 or os.pread(fd, 8, 16) != data[16:24]:
+                    continue
+                if (mono_ns() - publish_ns) / 1e9 > FRESH_S:
+                    return None
+                out = {"left": None, "right": None}
+                for k in range(min(nhands, 2)):
+                    f = HAND.unpack_from(data, HANDS_HDR.size + k * HAND.size)
+                    side = "right" if f[1] & FH_HAND_RIGHT else "left"
+                    if out[side]:
+                        continue
+                    pts = [f[4 + 3 * i: 7 + 3 * i] for i in range(21)]
+                    palm = [sum(pts[i][j] for i in PALM) / len(PALM) for j in range(3)]
+                    out[side] = {"palm": palm, "palm_m": math.sqrt(sum(v * v for v in palm)),
+                                 "tip": list(pts[INDEX_TIP])}
+                return out
+            return None
+        finally:
+            os.close(fd)
+
+
+# ------------------------------------------------------------------------------------------
+# The panel (ft-handpanel, @ft_handpanel)
+
+class Panel:
+    """Commands to ft-handpanel over its datagram socket. Commands that need an answer wait
+    for it; the rest don't, and their replies are read (and errors logged) later. With
+    dry=True nothing is sent: commands are printed and replies made up."""
+
+    def __init__(self, name=PANEL_SOCKET, dry=False, log=None, out=None):
+        self.name, self.dry, self.log, self.out = name, dry, log or (lambda s: None), out or print
+        self.sock = None
+        self.sent = {}
+        self.pending = 0   # commands sent and not answered yet
+        if not dry:
+            self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM | socket.SOCK_CLOEXEC)
+            self.sock.bind("\0ft_handrec.%d.%d" % (os.getpid(), id(self) & 0xffff))
+            self.sock.setblocking(False)
+
+    def close(self):
+        if self.sock:
+            self.sock.close()
+            self.sock = None
+
+    def _drain(self):
+        while self.sock:
+            try:
+                r = self.sock.recv(4096).decode(errors="replace")
+            except (BlockingIOError, OSError):
+                return
+            self.pending = max(0, self.pending - 1)
+            if r.startswith("error"):
+                self.log("panel: %s" % r)
+
+    def cmd(self, text, reply=False, timeout=0.5):
+        """Send a command; with reply=True, its answer ("ok ..." or "error ..."), or None.
+        The panel answers every command in order, so the answer is the one after those of
+        the commands still unanswered."""
+        if self.dry:
+            self.out("panel: %s" % text)
+            if not reply:
+                return None
+            if text.startswith("devices"):
+                return "ok hmd 200 left 200 right 200"
+            return "ok shown" if text == "ping" else "ok"
+        if not self.sock:
+            return None
+        self._drain()
+        try:
+            self.sock.sendto(text.encode(), "\0" + self.name)
+        except OSError:
+            return None
+        self.pending += 1
+        if not reply:
+            return None
+        end = time.monotonic() + timeout
+        while time.monotonic() < end:
+            try:
+                self.sock.settimeout(max(0.01, end - time.monotonic()))
+                r = self.sock.recv(4096).decode(errors="replace")
+            except OSError:
+                break
+            finally:
+                self.sock.setblocking(False)
+            self.pending = max(0, self.pending - 1)
+            if self.pending == 0:
+                return r
+            if r.startswith("error"):
+                self.log("panel: %s" % r)
+        self.pending = 0   # a lost answer: start counting afresh
+        return None
+
+    def set(self, key, text):
+        """Send a command only if it changes what that part of the panel shows."""
+        if self.sent.get(key) == text:
+            return
+        self.sent[key] = text
+        self.cmd(text)
+
+
+# ------------------------------------------------------------------------------------------
+# Processes
+
+def find_processes(name):
+    """[(pid, argv)] of running processes called name (the container shares the host's PIDs)."""
+    out = []
+    for pid in os.listdir("/proc"):
+        if not pid.isdigit():
+            continue
+        try:
+            with open("/proc/%s/comm" % pid) as f:
+                if f.read().strip() != name:
+                    continue
+            with open("/proc/%s/cmdline" % pid, "rb") as f:
+                argv = [a.decode(errors="replace") for a in f.read().split(b"\0") if a]
+        except OSError:
+            continue
+        out.append((int(pid), argv))
+    return out
+
+
+def tracker_running():
+    """A tracking ft-hands (not a --record-only recorder)."""
+    return any("--record-only" not in argv for _, argv in find_processes("ft-hands"))
+
+
+class Recorder:
+    """One part of a take's recording: ft-hands --record-only as a child process. Part 1
+    writes TAKE/sets.bin; part N (after a pause) records into TAKE/.part-N and is moved to
+    TAKE/sets-N.bin when it ends (ft-hands never overwrites, and always writes DIR/sets.bin)."""
+
+    def __init__(self, take_dir, part, seconds, ring, log_file, swap=None):
+        """swap: the side cameras' decision (sides.py), passed on as --sides 1 or 0; None (not
+        known yet) records them as ft-camd names them (--sides auto, whatever the config says)."""
+        self.take_dir, self.part = take_dir, part
+        self.dir = take_dir if part == 1 else os.path.join(take_dir, ".part-%d" % part)
+        self.file = "sets.bin" if part == 1 else "sets-%d.bin" % part
+        self.names_swapped = bool(swap)
+        argv = [FT_HANDS, "--record-only", "--record", self.dir, "--record-for", "%.0f" % max(seconds, 5),
+                "--record-hz", str(RECORD_HZ), "--status", "0",
+                "--sides", "auto" if swap is None else "1" if swap else "0"]
+        if ring:
+            argv += ["--ring", ring]
+        if not in_container():
+            argv = [os.path.expanduser("~/.local/bin/distrobox"), "enter", "dev", "--"] + argv
+        self.proc = subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=log_file, stderr=log_file)
+        self.started_ns = mono_ns()
+
+    def exited(self):
+        return self.proc.poll() is not None
+
+    def has_data(self):
+        """It has written a set (ft-hands starts recording within a few tens of milliseconds)."""
+        try:
+            return os.path.getsize(os.path.join(self.dir, "sets.bin")) > 0
+        except OSError:
+            return False
+
+    def stop(self):
+        """End it (SIGTERM: ft-hands writes out its queue) and put the part in place. Afterwards
+        names_swapped is what ft-hands says it applied (its DIR/sides.json, which goes into
+        take.json's "parts" and is removed here)."""
+        if self.proc.poll() is None:
+            self.proc.send_signal(signal.SIGTERM)
+            try:
+                self.proc.wait(15)
+            except subprocess.TimeoutExpired:
+                self.proc.kill()
+                self.proc.wait()
+        side_file = os.path.join(self.dir, "sides.json")
+        try:
+            with open(side_file) as f:
+                runs = json.load(f).get("names_swapped") or []
+            if runs:
+                self.names_swapped = bool(runs[0][1])   # --record-only never changes it
+            os.remove(side_file)
+        except (OSError, ValueError, TypeError, IndexError):
+            pass
+        if self.part > 1:
+            src = os.path.join(self.dir, "sets.bin")
+            if os.path.exists(src):
+                os.replace(src, os.path.join(self.take_dir, "sets-%d.bin" % self.part))
+            try:
+                os.rmdir(self.dir)
+            except OSError:
+                pass
+        return self.proc.returncode
+
+
+# ------------------------------------------------------------------------------------------
+# The headset's button, and mice (/proc/bus/input/devices, linux/input.h)
+#
+# The Frame's click button on its right side is KEY_SELECT on the "gpio-keys" device. It's read
+# as any other reader does, never grabbed (EVIOCGRAB): Frametop's input relay, ft-powerd, SteamVR
+# and gamescope read the same device, and the relay remaps its volume keys.
+
+INPUT_DEVICES = "/proc/bus/input/devices"
+INPUT_EVENT = struct.Struct("@llHHi")   # struct input_event: a timeval, type, code, value (24 bytes on 64-bit)
+EV_KEY, EV_REL = 0x01, 0x02
+REL_X, REL_Y = 0x00, 0x01
+KEY_SELECT = 353
+BUTTON_DEVICE = "gpio-keys"
+BUTTON_DEBOUNCE_S = 0.3   # presses closer than this count once
+
+
+def parse_input_devices(text):
+    """/proc/bus/input/devices as [{"name", "phys", "sysfs", "bus", "handlers": [...], "bits": {"EV": int, ...}}]."""
+    out, dev = [], None
+    for line in text.splitlines() + [""]:
+        line = line.strip()
+        if not line:
+            if dev:
+                out.append(dev)
+            dev = None
+            continue
+        if dev is None:
+            dev = {"name": "", "phys": "", "sysfs": "", "bus": 0, "handlers": [], "bits": {}}
+        tag, _, rest = line.partition(": ")
+        if tag == "I":
+            m = re.search(r"Bus=([0-9a-fA-F]+)", rest)
+            dev["bus"] = int(m.group(1), 16) if m else 0
+        elif tag == "N":
+            dev["name"] = rest.partition("=")[2].strip('"')
+        elif tag == "P":
+            dev["phys"] = rest.partition("=")[2]
+        elif tag == "S":
+            dev["sysfs"] = rest.partition("=")[2]
+        elif tag == "H":
+            dev["handlers"] = rest.partition("=")[2].split()
+        elif tag == "B":
+            key, _, words = rest.partition("=")
+            value = 0
+            for w in words.split():   # the highest long first
+                try:
+                    value = (value << 64) | int(w, 16)
+                except ValueError:
+                    value = 0
+                    break
+            dev["bits"][key] = value
+    return out
+
+
+def _event_node(dev):
+    for h in dev["handlers"]:
+        if re.fullmatch(r"event\d+", h):
+            return "/dev/input/" + h
+    return None
+
+
+def find_button(devices):
+    """The headset button's event device: "gpio-keys" with KEY_SELECT, or None."""
+    for dev in devices:
+        if dev["name"] == BUTTON_DEVICE and dev["bits"].get("KEY", 0) >> KEY_SELECT & 1:
+            return _event_node(dev)
+    return None
+
+
+def real_mouse(dev):
+    """A pointing device a person holds: relative X and Y, not made in software. uinput devices
+    (Frametop's virtual mouse, frame-voice's keyboard) sit under /devices/virtual/input or on the
+    virtual bus (6); Bluetooth mice come through uhid, also under /devices/virtual, so those count."""
+    bits = dev["bits"]
+    if not (bits.get("EV", 0) >> EV_REL & 1) or (bits.get("REL", 0) & 3) != 3:   # REL_X and REL_Y
+        return False
+    sysfs = dev["sysfs"]
+    if dev["bus"] == 0x06 or "virtual" in dev["name"].lower() or "uinput" in dev["phys"]:
+        return False
+    return not sysfs.startswith("/devices/virtual/") or sysfs.startswith("/devices/virtual/misc/uhid/")
+
+
+def read_input_devices(path=INPUT_DEVICES):
+    try:
+        with open(path) as f:
+            return parse_input_devices(f.read())
+    except OSError:
+        return []
+
+
+def mouse_connected(path=INPUT_DEVICES):
+    return any(real_mouse(d) for d in read_input_devices(path))
+
+
+def button_presses(data):
+    """KEY_SELECT key-downs in a run of input_event structs (value 1; releases and autorepeat
+    are left out). Returns (how many, the bytes left over after the last whole event)."""
+    n, usable = 0, len(data) - len(data) % INPUT_EVENT.size
+    for off in range(0, usable, INPUT_EVENT.size):
+        _, _, etype, code, value = INPUT_EVENT.unpack_from(data, off)
+        if etype == EV_KEY and code == KEY_SELECT and value == 1:
+            n += 1
+    return n, data[usable:]
+
+
+class ButtonReader:
+    """Reads the headset button on a thread and calls on_press() per press, debounced. path:
+    an event device or, for testing, a FIFO carrying input_event structs. It's opened read-only
+    and shared; if it can't be opened (no device, no permission, /dev/input not reachable in a
+    container) it says so in the log and tries again now and then."""
+
+    def __init__(self, path, on_press, log=None, debounce_s=BUTTON_DEBOUNCE_S):
+        self.path, self.on_press, self.log = path, on_press, log or (lambda s: None)
+        self.debounce_s = debounce_s
+        self.ok = False      # opened at least once
+        self._stop = threading.Event()
+        self._last = -1e9
+        self._thread = threading.Thread(target=self._run, name="handrec-button", daemon=True)
+
+    def start(self):
+        self._thread.start()
+        return self
+
+    def stop(self):
+        self._stop.set()
+        self._thread.join(2)
+
+    def _press(self, n):
+        now = time.monotonic()
+        if n and now - self._last >= self.debounce_s:
+            self._last = now
+            self.on_press()
+
+    def _run(self):
+        failed = False
+        while not self._stop.is_set():
+            try:
+                fd = os.open(self.path, os.O_RDONLY | os.O_NONBLOCK | os.O_CLOEXEC)
+            except OSError as e:
+                if not failed:
+                    self.log("headset button: can't open %s (%s): the window's keys still work" % (self.path, e.strerror))
+                failed = True
+                self._stop.wait(5)
+                continue
+            if failed or not self.ok:
+                self.log("headset button: reading %s" % self.path)
+            self.ok, failed = True, False
+            rest = b""
+            try:
+                while not self._stop.is_set():
+                    r, _, _ = select.select([fd], [], [], 0.2)
+                    if not r:
+                        continue
+                    try:
+                        data = os.read(fd, INPUT_EVENT.size * 64)
+                    except BlockingIOError:
+                        continue
+                    if not data:   # a FIFO's writer left: open it again
+                        self._stop.wait(0.2)
+                        break
+                    n, rest = button_presses(rest + data)
+                    self._press(n)
+            except OSError as e:   # the device went away
+                self.log("headset button: %s: %s" % (self.path, e.strerror))
+                self._stop.wait(2)
+            finally:
+                os.close(fd)
+
+
+# ------------------------------------------------------------------------------------------
+# The pose pictures (poses/poses.json: {"<pose>": {"file": "<name>.png", "two_hands", "caption"}})
+
+def load_poses(poses_dir):
+    """{pose id: {"path", "two_hands", "caption"}} from poses_dir/poses.json, or {} without one."""
+    try:
+        with open(os.path.join(poses_dir, "poses.json")) as f:
+            raw = json.load(f)
+    except (OSError, ValueError):
+        return {}
+    out = {}
+    for pose, e in (raw.items() if isinstance(raw, dict) else ()):
+        if isinstance(e, dict) and isinstance(e.get("file"), str) and e["file"]:
+            out[pose] = {"path": os.path.join(poses_dir, os.path.basename(e["file"])),
+                         "two_hands": bool(e.get("two_hands")), "caption": clean_text(e.get("caption", ""))}
+    return out
+
+
+def pose_view(poses, p):
+    """A prompt's picture: (path, mode, caption), mode "" (as drawn: a right hand, or both hands),
+    "mirror" (a left hand) or "both" (a mirrored copy on the left, the picture on the right).
+    The prompt's "picture" (a pose id) picks a picture other than its pose's, and
+    "picture_mirror" mirrors a two-hand picture. ("", "", "") when there's none."""
+    e = poses.get(p.get("picture") or p.get("pose") or "")
+    if not e or not os.path.isfile(e["path"]):
+        return "", "", ""
+    hands = p.get("hands")
+    if e["two_hands"]:
+        mode = "mirror" if p.get("picture_mirror") else ""
+    else:
+        mode = "mirror" if hands == "left" else "both" if hands == "both" else ""
+    return e["path"], mode, e["caption"]
+
+
+# ------------------------------------------------------------------------------------------
+# The script
+
+HAND_VALUES = ("left", "right", "both", "none", "any", "")
+PROMPT_KEYS = ("text", "seconds", "hands", "pose", "distance", "position", "object", "controller")
+
+
+def _when_ok(cond, ctx):
+    """A prompt's or block's "when": "controllers", "objects:keyboard", either negated with "!",
+    or a list of them, all to hold."""
+    if not cond:
+        return True
+    if isinstance(cond, list):   # all of them
+        return all(_when_ok(c, ctx) for c in cond)
+    neg = cond.startswith("!")
+    c = cond.lstrip("!")
+    value = c[len("objects:"):] in ctx["objects"] if c.startswith("objects:") else bool(ctx.get(c))
+    return value != neg
+
+
+def _prompt(section, raw, ctx, subst=None):
+    p = dict(section.get("defaults") or {})
+    p.update(raw)
+    p.pop("when", None)
+    for k, v in (subst or {}).items():
+        for key in ("text", "object"):
+            if isinstance(p.get(key), str):
+                p[key] = p[key].replace("{%s}" % k, v)
+    if subst and "object_key" in subst:
+        p["object"] = subst["object_key"]
+    for key in PROMPT_KEYS:
+        p.setdefault(key, False if key == "controller" else 0 if key == "seconds" else "")
+    p["controllers"] = list(p.get("controllers") or [])
+    if p["hands"] not in HAND_VALUES:
+        raise ValueError("%s: hands %r" % (section["id"], p["hands"]))
+    return p
+
+
+def _set_ids(section, prompts):
+    seen = {}
+    for p in prompts:
+        if not p.get("id"):
+            parts = [section["id"]] + [re.sub(r"[^a-z0-9]+", "-", str(p[k]).lower()).strip("-")
+                                       for k in ("pose", "hands", "distance", "position", "object") if p[k]]
+            p["id"] = "/".join(parts) if len(parts) > 1 else "%s/%d" % (section["id"], len(seen) + 1)
+        n = seen.get(p["id"], 0) + 1
+        seen[p["id"]] = n
+        if n > 1:
+            p["id"] = "%s#%d" % (p["id"], n)
+
+
+def load_script(path):
+    with open(path) as f:
+        script = json.load(f)
+    if script.get("version") != 1 or not isinstance(script.get("sections"), list):
+        raise ValueError("%s: not a version 1 script" % path)
+    return script
+
+
+def session_seed(session_id):
+    """The shuffle's seed for a session: from its id, so the same id gives the same plan."""
+    return int(hashlib.sha256(session_id.encode()).hexdigest()[:8], 16)
+
+
+def _sweep_prompts(s, raw, ctx, rng):
+    """A sweep section's steps (DESIGN.md, "Sweeps"): each a prompt with "cues", the pose of each
+    cue_s slot in order. A step names its cues, or takes a group: "next" (the groups in turn, in
+    the shuffled order) or "any" (a group drawn at random, different for each "any" while there
+    are groups left). With rng (the session's shuffle) the groups' order, the "any" draws and the
+    cues' order within a step are shuffled, unless the section says "shuffle": false or the
+    step "fixed": true; without it, everything goes in the script's order."""
+    groups = [list(g) for g in raw.get("groups") or []]
+    shuffle = rng is not None and raw.get("shuffle", True)
+    order = list(range(len(groups)))
+    pool = list(range(len(groups)))
+    if shuffle:
+        rng.shuffle(order)
+        rng.shuffle(pool)
+    taken, drawn, counts = 0, 0, {}
+    out = []
+    for step in raw.get("sweeps") or []:
+        if not _when_ok(step.get("when"), ctx):
+            continue
+        g = step.get("group")
+        if step.get("cues"):
+            cues = list(step["cues"])
+        elif g == "next" and groups:
+            cues, taken = list(groups[order[taken % len(order)]]), taken + 1
+        elif g == "any" and groups:
+            cues, drawn = list(groups[pool[drawn % len(pool)]]), drawn + 1
+        elif isinstance(g, int) and 0 <= g < len(groups):
+            cues = list(groups[g])
+        else:
+            raise ValueError("%s: a sweep needs cues or a group" % s["id"])
+        if shuffle and not step.get("fixed"):
+            rng.shuffle(cues)
+        cue_s = float(step.get("cue_s", raw.get("cue_s", 4)))
+        slots = max(len(cues), int(math.ceil(float(step.get("seconds", raw.get("step_s", cue_s * len(cues)))) / cue_s
+                                             - 1e-9))) if step.get("cycle", raw.get("cycle", True)) else len(cues)
+        p = _prompt(s, {k: v for k, v in step.items() if k not in ("group", "cues", "fixed", "cycle", "quick")}, ctx)
+        p["cues"] = [cues[k % len(cues)] for k in range(slots)]
+        p["cue_s"] = cue_s
+        p["seconds"] = cue_s * slots
+        p["pose"] = p["cues"][0]
+        if not step.get("id"):
+            counts[p["hands"]] = counts.get(p["hands"], 0) + 1
+            p["id"] = "%s/%s-%d" % (s["id"], p["hands"] or "any", counts[p["hands"]])
+        else:
+            p["id"] = "%s/%s" % (s["id"], step["id"])
+        if step.get("quick") is False:
+            p["quick"] = False
+        out.append(p)
+    return out
+
+
+def build_plan(script, checklist, seed=None, quick=False):
+    """The sections this session runs, prompts expanded for the checklist, and the ones
+    skipped: (plan, skipped) with skipped = [{"section", "reason"}]. seed: the shuffle of the
+    sweeps (session_seed; None: the script's order). quick: the quick round, only sections
+    marked "quick" and, in those, no step marked "quick": false."""
+    objects = [o for o in (checklist.get("objects") or []) if o]
+    own = [o for o in (checklist.get("own_objects") or []) if str(o).strip()]
+    ctx = {"objects": set(objects) | set(own), "controllers": checklist.get("controllers") == "straps"}
+    names = script.get("objects") or {}
+    plan, skipped = [], []
+    for raw in script["sections"]:
+        sid = raw["id"]
+        if quick and not raw.get("quick"):
+            skipped.append({"section": sid, "reason": "not in a quick round"})
+            continue
+        missing = [r for r in raw.get("requires") or [] if not ctx.get(r)]
+        if missing:
+            skipped.append({"section": sid, "reason": "needs " + ", ".join(missing)})
+            continue
+        s = dict(raw)
+        s["kind"] = raw.get("kind", "prompts")
+        s["intro_s"] = float(raw.get("intro_s", script.get("intro_s", 4)))
+        prompts = []
+        if s["kind"] == "sweep":
+            rng = random.Random("%d/%s" % (seed, sid)) if seed is not None else None
+            prompts = _sweep_prompts(s, raw, ctx, rng)
+            if quick:
+                prompts = [p for p in prompts if p.get("quick") is not False]
+        elif raw.get("for_each") == "object":
+            skip = set(raw.get("skip_objects") or [])
+            for o in [o for o in objects if o not in skip] + own:
+                label = clean_text(names.get(o, o)).replace("|", "/")
+                for p in raw.get("prompts") or []:
+                    if _when_ok(p.get("when"), ctx):
+                        prompts.append(_prompt(s, p, ctx, {"object": label, "object_key": clean_text(o)}))
+        else:
+            prompts = [_prompt(s, p, ctx) for p in raw.get("prompts") or [] if _when_ok(p.get("when"), ctx)
+                       and not (quick and p.get("quick") is False)]
+            for p in prompts:   # a prompt may have cues too (hand size): its own, in its order
+                if p.get("cues"):
+                    cue_s = float(p.get("cue_s", raw.get("cue_s", 4)))
+                    p["cues"], p["cue_s"] = list(p["cues"]), cue_s
+                    p["seconds"] = cue_s * len(p["cues"])
+                    p["pose"] = p["cues"][0]
+        _set_ids(s, prompts)
+        s["prompts"] = prompts
+        if s["kind"] == "bar":
+            heights = []
+            for h in raw.get("heights") or []:
+                h = {"id": h} if isinstance(h, str) else dict(h)
+                h.setdefault("text", (raw.get("height_text") or {}).get(h["id"], raw.get("text", "")))
+                h.setdefault("reps", raw.get("reps", 5))
+                heights.append(h)
+            s["heights"] = heights
+        before = raw.get("before")
+        s["before"] = before if before and _when_ok(before.get("when"), ctx) else None
+        if s["kind"] in ("prompts", "sweep") and not prompts:
+            skipped.append({"section": sid, "reason": "nothing to do"})
+            continue
+        if s["kind"] == "targets" and not raw.get("targets"):
+            skipped.append({"section": sid, "reason": "no targets"})
+            continue
+        plan.append(s)
+    return plan, skipped
+
+
+def plan_record(plan):
+    """What the shuffle chose, for session.json: each section's sweep steps and their cues."""
+    out = {}
+    for s in plan:
+        steps = [{"id": p["id"], "hands": p["hands"], "cues": p["cues"]} for p in s["prompts"] if p.get("cues")]
+        if steps:
+            out[s["id"]] = steps
+    return out
+
+
+def section_steps(s):
+    """The steps that wait for Next in step mode: each prompt and bar height, and the first target."""
+    return (len(s["prompts"]) + (len(s.get("heights") or []) if s["kind"] == "bar" else 0)
+            + (1 if s["kind"] == "targets" and s.get("targets") else 0))
+
+
+def section_seconds(s, worst=False, auto=True):
+    """A section's length in script seconds (targets: about 4 s each, or the timeout if worst).
+    In step mode, what's recorded: a countdown before each step and the holds; the intro and
+    the waits for Next aren't."""
+    t = (s["intro_s"] if auto else COUNTDOWN_S * section_steps(s)) + sum(p["seconds"] for p in s["prompts"])
+    if s["kind"] == "targets":
+        t += len(s["targets"]) * (s.get("timeout_s", 8) if worst else min(4.0, s.get("timeout_s", 8)))
+    if s["kind"] == "bar":
+        lead = s.get("lead_s", 3) if auto else 0
+        t += sum(lead + h["reps"] * s.get("period_s", 6) for h in s["heights"])
+    return t
+
+
+def plan_seconds(script, plan, worst=False, auto=True):
+    """The session's length: in auto mode all of it; in step mode only what's recorded, as the
+    time spent reading each step before pressing Next is up to the person (plan_steps)."""
+    if not auto:
+        return sum(section_seconds(s, worst, auto=False) for s in plan)
+    t = (script.get("welcome") or {}).get("seconds", 0) + (script.get("done") or {}).get("seconds", 0)
+    for i, s in enumerate(plan):
+        t += section_seconds(s, worst)
+        t += s["before"]["seconds"] if s.get("before") else (script.get("between_s", 3) if i else 0)
+    return t
+
+
+def plan_steps(plan):
+    return sum(section_steps(s) for s in plan)
+
+
+def plan_summary(script, plan, auto=False):
+    """The length in words, for the window and --plan (the plan of a quick round or a full one)."""
+    minutes = max(1, round(plan_seconds(script, plan, auto=auto) / 60))
+    if auto:
+        return "about %d min, each step advancing by itself" % minutes
+    n = plan_steps(plan)
+    return ("about %d min of recording in %d steps, plus the time you take to read each step before "
+            "pressing Next (at 5 s a step, about %d min more)" % (minutes, n, max(1, round(n * 5 / 60))))
+
+
+# ------------------------------------------------------------------------------------------
+# The session
+
+class _Skip(Exception):
+    pass
+
+
+class _Stop(Exception):
+    pass
+
+
+class _Fail(Exception):
+    pass
+
+
+class _Redo(Exception):
+    pass
+
+
+def _git_describe():
+    try:
+        r = subprocess.run(["git", "-C", REPO, "describe", "--always", "--dirty", "--tags"],
+                           capture_output=True, text=True, timeout=5)
+        return r.stdout.strip() or "unknown"
+    except (OSError, subprocess.TimeoutExpired):
+        return "unknown"
+
+
+def _os_version():
+    path = "/run/host/etc/os-release" if in_container() else "/etc/os-release"
+    try:
+        with open(path) as f:
+            for line in f:
+                if line.startswith("VERSION_ID="):
+                    return line.split("=", 1)[1].strip().strip('"')
+    except OSError:
+        pass
+    return ""
+
+
+def _steamvr_version():
+    for db in ("/usr/lib/holo/pacmandb", "/var/lib/pacman"):   # SteamOS keeps it in the image
+        found = sorted(glob.glob(("/run/host" if in_container() else "") + db + "/local/deckard-steamvr-rel-*"))
+        if found:
+            return os.path.basename(found[-1])[len("deckard-steamvr-rel-"):]
+    p = host_path("/opt/steamvr/bin/version.txt")
+    if p:
+        try:
+            with open(p) as f:
+                return "build " + f.read().strip()
+        except OSError:
+            pass
+    return ""
+
+
+def camera_check():
+    """camcheck.check() (the XRService log, its open cameras where readable, ft-camd's ring);
+    never raises: a failure is "unknown"."""
+    try:
+        return camcheck.check()
+    except Exception as e:
+        return {"status": "unknown", "summary": "unknown: the camera check failed (%s)" % e,
+                "reason": str(e), "evidence": []}
+
+
+def camera_text(result):
+    """What to tell the person about a camera check that isn't ok ("" if it's ok or unknown)."""
+    if not result or result.get("status") != "degraded":
+        return ""
+    if camcheck.is_vcint_failure(result):
+        return camcheck.USER_TEXT
+    return ("Not all of the headset's tracking cameras are running (%s). Restart SteamVR, or restart the "
+            "headset if that doesn't fix it." % result.get("reason", ""))
+
+
+class Session:
+    """One recording session. start() runs it in its own thread; next_step(), pause(), resume(),
+    redo(), skip() and stop() steer it from any thread. on_status(dict) is called from the
+    session thread whenever something changes (the keys of _status).
+
+    auto=False is step mode: each step waits for next_step(), then a recorded countdown, then
+    the hold; nothing is recorded while it waits. auto=True: the timed flow, each prompt
+    advancing by itself, one recording per take. next_after (a test hook): press Next by itself
+    after that many seconds of waiting. poses_dir: the pose pictures (poses/). button: read the
+    headset's button (not in a dry run unless button_device, a test hook, names the device or
+    a FIFO of input_event structs). check_cameras: run the camera check first and don't start
+    if it fails (not in a dry run, nor with ring). hands_reader (a test hook): an object whose
+    read() stands in for the hands file, read in a dry run too. quick: the quick round (a few
+    sections, about 3 min). seed: the sweeps' shuffle (default: from the session's id)."""
+
+    def __init__(self, base_dir, profile, checklist, lighting_choice, script_path, *, ring=None,
+                 start_processes=True, dry_run=False, speed=1.0, on_status=None, hands_dir=None, panel_bin=None,
+                 auto=False, next_after=None, poses_dir=None, button=True, button_device=None,
+                 check_cameras=True, hands_reader=None, quick=False, seed=None):
+        self.base_dir = os.path.abspath(os.path.expanduser(base_dir or BASE_DIR))
+        self.profile = dict(profile or {})
+        self.checklist = dict(checklist or {})
+        self.lighting_choice = lighting_choice or ""
+        self.script_path = script_path or SCRIPT_PATH
+        self.ring = ring
+        self.start_processes = start_processes
+        self.dry_run = dry_run
+        self.speed = max(float(speed or 1.0), 0.01)
+        self.on_status = on_status
+        self.hands_dir = hands_dir or run_dir()
+        self.panel_bin = panel_bin or PANEL_BIN
+        self.auto = bool(auto)
+        self.next_after = next_after
+        self.button, self.button_device = bool(button), button_device
+        self.check_cameras = bool(check_cameras)
+        self.quick = bool(quick)
+        self.seed = seed   # set from the session's id when it starts, unless given
+        # the camera check (a test hook: tests swap it); a dry run looks at no real cameras
+        self.camera_check_fn = (lambda: None) if dry_run else camera_check
+        self.input_devices = INPUT_DEVICES   # where mice are looked for (a test hook)
+        self._button = None                  # the ButtonReader
+        self.print = print   # where dry-run panel commands go (the CLI's stdout)
+        self.script = load_script(self.script_path)
+        # the plan in the script's order; the session's own shuffle comes with its id (_make_dir)
+        self.plan, self.skipped = build_plan(self.script, self.checklist, seed=seed, quick=self.quick)
+        self._poses = load_poses(poses_dir or POSES_DIR)
+        self.session_dir = ""
+        self._thread = None
+        self._lock = threading.Lock()
+        self._want = {"pause": False, "skip": False, "stop": False, "next": False, "redo": False}
+        self._wake = threading.Event()
+        # state: starting, intro, ready (a step waits for Next), countdown, running (a hold),
+        # between, paused, done, stopped, error. waiting: Next is wanted. big: the countdown's
+        # number, then the hold's word ("Hold", "Go"), as the panel shows them. The picture and the
+        # diagram: image (a path or ""), image_mode ("", "mirror", "both"), position, distance.
+        self._status = {"state": "starting", "mode": "auto" if self.auto else "step", "section": "", "title": "",
+                        "section_index": 0, "section_count": len(self.plan), "step_index": 0, "step_count": 0,
+                        "prompt": "", "seconds_left": 0.0, "note": "", "hands": {"left": None, "right": None},
+                        "take": None, "error": "", "waiting": False, "countdown": 0, "big": "", "can_redo": False,
+                        "image": "", "image_mode": "", "caption": "", "position": "", "distance": "",
+                        "ready_text": READY_TEXT, "button": False, "mouse": True,
+                        "camera": None, "nohands": False, "strip": [], "cue": -1, "quick": self.quick}
+        self._last_emit = 0.0
+        self._log_file = None
+        self._panel = None
+        self._panel_proc = None
+        self._units = []           # transient units this session started
+        self._session_json = None
+        self._take = None          # the take in progress: dict
+        self._recorder = None
+        self._prompt = None        # the prompt shown: dict (hands, controllers)
+        self._live = None          # the hands file's last read
+        self._hands_file = hands_reader or HandsFile(os.path.join(self.hands_dir, "hands"))
+        self._read_hands = not dry_run or hands_reader is not None
+        self._hold_watch = None    # the no-hands check's counts during a hold
+        self._stop_note = ""       # why the session stopped, when it says more than "stopped"
+        self._paused = False
+        self._recording = False    # a recording part is running
+        self._paused_recording = False
+        self._waiting = False      # waiting for Next: no notes about lost hands
+        self._redo_ok = False      # R does something now
+        self._step_t0 = None       # the step's first event (ready or prompt), for R
+        self._fb = {}              # feedback timers
+        self._ring_path = None
+        self._sides_read = 0.0     # when the side camera decision was last read
+
+    # --- controls (any thread)
+    def start(self):
+        if self._thread:
+            raise RuntimeError("the session has started already")
+        self._thread = threading.Thread(target=self._run, name="handrec-session", daemon=True)
+        self._thread.start()
+
+    def _set(self, key, value):
+        with self._lock:
+            self._want[key] = value
+        self._wake.set()
+
+    def button_press(self):
+        """The headset's button: Next while a step waits, pause during a countdown or hold
+        (and auto mode's timed screens), resume while paused."""
+        with self._lock:
+            paused = self._want["pause"]
+        state = self._status["state"]
+        if paused:
+            self.resume()
+        elif self._waiting:
+            self.next_step()
+        elif state in ("countdown", "running", "intro", "between"):
+            self.pause()
+        else:
+            return
+        self._log("headset button (%s)" % ("resume" if paused else "next" if self._waiting else "pause"))
+
+    def next_step(self):
+        """Step mode: start the step that's waiting (its countdown)."""
+        self._set("next", True)
+
+    def redo(self):
+        """Record a step again: the one running, or at a step's ready screen the one before."""
+        self._set("redo", True)
+
+    def pause(self):
+        self._set("pause", True)
+
+    def resume(self):
+        self._set("pause", False)
+
+    def skip(self):
+        self._set("skip", True)
+
+    def stop(self, wait=20.0):
+        """Stop. The take in progress is kept as far as it got. Blocks until the session has
+        written its files (up to wait seconds), unless called from the session thread."""
+        self._set("stop", True)
+        if self._thread and threading.current_thread() is not self._thread and wait:
+            self._thread.join(wait)
+
+    def join(self, timeout=None):
+        if self._thread:
+            self._thread.join(timeout)
+
+    @property
+    def state(self):
+        return self._status["state"]
+
+    # --- status and logging
+    def _emit(self, force=True, **changes):
+        self._status.update(changes)
+        now = time.monotonic()
+        if not force and now - self._last_emit < 0.25:
+            return
+        self._last_emit = now
+        if self.on_status:
+            try:
+                self.on_status(dict(self._status, hands=dict(self._status["hands"])))
+            except Exception:
+                self._log("on_status: " + traceback.format_exc())
+
+    def _log(self, text):
+        if self._log_file:
+            self._log_file.write("%s %s\n" % (time.strftime("%H:%M:%S"), text))
+            self._log_file.flush()
+
+    def _event(self, event, **fields):
+        """A line in the take's prompts.jsonl; returns its time."""
+        t = mono_ns()
+        if not self._take:
+            return t
+        line = {"t": t, "event": event}
+        line.update(fields)
+        self._take["prompts"].write(json.dumps(line) + "\n")
+        self._take["prompts"].flush()
+        return t
+
+    # --- the run
+    def _run(self):
+        try:
+            if self._preflight():
+                return
+            self._make_dir()
+            self._emit(state="starting")
+            self._setup()
+            self._screen("starting", self.script.get("welcome") or {})
+            for i, s in enumerate(self.plan):
+                self._section(i, s)
+            self._finish("done")
+        except _Stop:
+            self._finish("stopped")
+        except _Fail as e:
+            self._finish("error", str(e))
+        except Exception as e:
+            self._log(traceback.format_exc())
+            self._finish("error", "%s: %s" % (type(e).__name__, e))
+
+    def _preflight(self):
+        """The camera check, before anything is made or started (camcheck.py): with the upper
+        cameras off a session records nothing useful. True if it stopped the session (state
+        "error", no session folder)."""
+        if self.dry_run or self.ring or not self.check_cameras:
+            return False
+        r = self.camera_check_fn()
+        self._status["camera"] = r
+        text = camera_text(r)
+        if not text:
+            return False
+        self._emit(state="error", error=text, prompt=text, camera=r)
+        return True
+
+    def _make_dir(self):
+        sessions = os.path.join(self.base_dir, "sessions")
+        os.makedirs(sessions, exist_ok=True)
+        sid = time.strftime("%Y%m%d-%H%M%S")
+        path, n = os.path.join(sessions, sid), 1
+        while True:
+            try:
+                os.mkdir(path)
+                break
+            except FileExistsError:
+                n += 1
+                path = os.path.join(sessions, "%s-%d" % (sid, n))
+        os.mkdir(os.path.join(path, "takes"))
+        self.session_dir = path
+        if self.seed is None:
+            self.seed = session_seed(os.path.basename(path))
+        # the same sections and steps, the sweeps shuffled for this session
+        self.plan, self.skipped = build_plan(self.script, self.checklist, seed=self.seed, quick=self.quick)
+        self._log_file = open(os.path.join(path, "session.log"), "a", buffering=1)
+        self._log("session %s%s, script %s" % (os.path.basename(path), " (dry run)" if self.dry_run else "",
+                                                self.script_path))
+        for s in self.skipped:
+            self._log("skipping %s: %s" % (s["section"], s["reason"]))
+        cam = self._status.get("camera")
+        if cam:
+            self._log("camera check: %s" % cam.get("summary", cam.get("status")))
+            for line in cam.get("evidence", []):
+                self._log("  " + line)
+        elif not self.check_cameras and not self.dry_run:
+            self._log("camera check skipped (--ignore-cameras)")
+
+    def _setup(self):
+        ring_path = self.ring or os.path.join(self.hands_dir, "cam-ring")
+        self._ring_path = ring_path
+        if not self.dry_run:
+            if not os.access(FT_HANDS, os.X_OK):
+                raise _Fail("ft-hands isn't built: hands/build.sh")
+            self._ensure_ring(ring_path)
+            if not tracker_running():
+                if self.start_processes:
+                    self._start_tracker()
+                else:
+                    self._log("no tracking ft-hands found: feedback only if one publishes")
+        lighting = ring_lighting(ring_path)
+        cams = []
+        try:
+            ring = Ring(ring_path)
+            cams = [{"name": c["name"], "width": c["width"], "height": c["height"]}
+                    for c in ring.cams if not c["flags"] & FH_CAM_DARK and not c["name"].endswith("_dk")]
+            ring.close()
+        except (OSError, ValueError):
+            pass
+        removed = self._write_calibration() + self._write_device()
+        self._session_json = {
+            "schema": 1, "tool": "ft-handrec " + _git_describe(), "started": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+            "contributor": self.profile.get("contributor", ""),
+            "lighting": lighting_record(self.lighting_choice, lighting),
+            "checklist": self.checklist,
+            "device": {"steamos": _os_version(), "steamvr": _steamvr_version(), "cameras": cams},
+            "calibration_removed": removed,
+            "script": {"version": self.script.get("version"), "sections": [s["id"] for s in self.plan],
+                       "skipped": self.skipped},
+            "mode": "auto" if self.auto else "step", "quick": self.quick,
+            "shuffle": {"seed": self.seed, "sweeps": plan_record(self.plan)},
+            "takes": [], "status": "recording", "sides": {"swapped": None}}
+        self._read_sides(force=True)
+        cam = self._status.get("camera")
+        if cam:
+            self._session_json["camera"] = {"status": cam.get("status"), "reason": cam.get("reason", "")}
+        if self.dry_run:
+            self._session_json["dry_run"] = True
+        if self.speed != 1:
+            self._session_json["speed"] = self.speed
+        self._save_session()
+        self._panel = Panel(dry=self.dry_run, log=self._log, out=self.print)
+        if not self.dry_run:
+            self._start_panel()
+        self._start_button()
+        self._panel.cmd("show")
+        self._panel.cmd("paused off")
+        for key, c in (("note", "note "), ("countdown", "countdown off"), ("hands", "hands off off"),
+                       ("bar", "bar off"), ("target", "target off"), ("image", "image off"), ("where", "where off"),
+                       ("big", "big "), ("action", "action "), ("rec", "rec off"), ("strip", "strip off")):
+            self._panel.set(key, c)
+        self._hints(action=False)
+
+    def _start_button(self):
+        """The headset button's reader, unless turned off (a dry run has none unless a test
+        device is given). Without the device the session goes on: the window's keys work."""
+        if not self.button or (self.dry_run and not self.button_device):
+            return
+        path = self.button_device or find_button(read_input_devices())
+        if not path:
+            self._log("headset button: no %s device with KEY_SELECT in %s" % (BUTTON_DEVICE, INPUT_DEVICES))
+            return
+        self._button = ButtonReader(path, self.button_press, log=self._log, debounce_s=BUTTON_DEBOUNCE_S).start()
+        end = time.monotonic() + 0.5   # opened in a moment, or it isn't reachable
+        while not self._button.ok and time.monotonic() < end:
+            time.sleep(0.01)
+
+    def _write_calibration(self):
+        src = host_path("/persist/xrservice.json")
+        if not src:
+            self._log("no /persist/xrservice.json: no calibration.json")
+            return []
+        with open(src) as f:
+            clean, removed = strip_calibration(json.load(f))
+        write_json(os.path.join(self.session_dir, "calibration.json"), clean)
+        return removed
+
+    def _write_device(self):
+        """device.json: the rig's pose in the CAD frame from /persist/device_config.json, only
+        cv.cad_from_cal (Cam0 in CAD) and head (the head in CAD), in the shape the labeller reads
+        (frame-hands train/label, as its cut.py writes it). The rest of that file names the unit
+        (serial number, EDID). Returns what was removed, as "device.json:<path>"."""
+        src = host_path("/persist/device_config.json")
+        if not src:
+            self._log("no /persist/device_config.json: no device.json")
+            return []
+        try:
+            with open(src) as f:
+                dev = json.load(f)
+            picked = {"cv": {"cad_from_cal": dev["cv"]["cad_from_cal"]}, "head": dev["head"]}
+        except (OSError, ValueError, KeyError, TypeError) as e:
+            self._log("device_config.json unreadable (%s): no device.json" % e)
+            return []
+        clean, removed = strip_calibration(picked)
+        write_json(os.path.join(self.session_dir, "device.json"), clean)
+        return ["device.json:" + r for r in removed]
+
+    def _save_session(self):
+        if self._session_json is not None:
+            write_json(os.path.join(self.session_dir, "session.json"), self._session_json)
+
+    def _read_sides(self, force=False):
+        """The tracking ft-hands' side camera decision (sides.py, read_live) into session.json's
+        "sides": {"swapped", "decided_by", "state", "evidence", "decided_at"}. Later recording
+        parts are named right (Recorder's swap); parts before it are renamed when read. Without
+        a tracking ft-hands it stays undecided ("swapped": null): export then leaves the names,
+        and the maintainer's check (hub_review check) tells."""
+        now = time.monotonic()
+        if self._session_json is None or (not force and now - self._sides_read < SIDES_READ_S):
+            return
+        self._sides_read = now
+        live = sides.read_live(os.path.join(self.hands_dir, "sides.json"), self._ring_path)
+        if not live or live.get("swapped") is None:
+            return
+        cur = self._session_json.get("sides") or {}
+        swapped = bool(live["swapped"])
+        if cur.get("swapped") is not None and bool(cur["swapped"]) == swapped:
+            if live.get("state") != cur.get("state"):   # e.g. decided -> confirmed
+                cur["state"] = live.get("state")
+                self._save_session()
+            return
+        new = {"swapped": swapped, "decided_by": live.get("decided_by"), "state": live.get("state"),
+               "evidence": live.get("evidence"), "decided_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+               "decided_ns": mono_ns()}
+        if cur.get("swapped") is not None:
+            new["reversed_from"] = cur
+        self._session_json["sides"] = new
+        self._save_session()
+        self._log("side cameras: %s (%s, %s)" % ("SWAPPED" if swapped else "as named", new["decided_by"],
+                                                  json.dumps(new["evidence"])))
+
+    def _sides_swapped(self):
+        """session.json's decision: True, False, or None (not known yet)."""
+        return (self._session_json or {}).get("sides", {}).get("swapped")
+
+    def _ensure_ring(self, path):
+        if ring_alive(path):
+            return
+        if self.ring:
+            raise _Fail("No frames in %s (start ft-ringplay first)" % path)
+        if not self.start_processes:
+            raise _Fail("ft-camd isn't running (and --no-start)")
+        try:
+            if start_camd(path, self._log, lambda: self._want["stop"]):
+                self._units.append(CAMD_UNIT)
+        except RuntimeError as e:
+            raise _Fail(str(e))
+        if self._want["stop"]:
+            raise _Stop()
+
+    def _start_tracker(self):
+        up = os.path.join(REPO, "scripts", "container-up.sh")
+        if os.access(up, os.X_OK):
+            subprocess.run(host_command(up), capture_output=True, timeout=120)
+        argv = [os.path.expanduser("~/.local/bin/distrobox"), "enter", "dev", "--", FT_HANDS,
+                "--no-gestures", "--status", "0"]
+        if self.ring:
+            argv += ["--ring", self.ring]
+        self._start_unit(HANDS_UNIT, "hand tracking for feedback", argv)
+
+    def _start_unit(self, unit, what, argv):
+        try:
+            if start_unit(unit, what, argv, self._log):
+                self._units.append(unit)
+        except RuntimeError as e:
+            raise _Fail(str(e))
+
+    def _stop_units(self):
+        for unit in reversed(self._units):
+            stop_unit(unit)
+            self._log("stopped %s" % unit)
+        self._units = []
+
+    def _start_panel(self):
+        if self._panel.cmd("ping", reply=True):
+            self._log("using the ft-handpanel that's running")
+            return
+        if not os.access(self.panel_bin, os.X_OK):
+            raise _Fail("ft-handpanel isn't built: hands/rec/build.sh")
+        self._panel_proc = subprocess.Popen([self.panel_bin, "--watch-stdin"], stdin=subprocess.PIPE,
+                                            stdout=self._log_file, stderr=self._log_file)
+        end = time.monotonic() + 15
+        while time.monotonic() < end:
+            if self._panel.cmd("ping", reply=True, timeout=0.2):
+                return
+            if self._panel_proc.poll() is not None:
+                raise _Fail("ft-handpanel exited (is SteamVR running?): see session.log")
+            time.sleep(0.1)
+        raise _Fail("ft-handpanel doesn't answer")
+
+    def _stop_panel(self):
+        if self._panel:
+            self._panel.cmd("hide")
+        if self._panel_proc:
+            try:
+                self._panel_proc.stdin.close()
+                self._panel_proc.wait(3)
+            except (OSError, subprocess.TimeoutExpired):
+                self._panel_proc.terminate()
+                try:
+                    self._panel_proc.wait(3)
+                except subprocess.TimeoutExpired:
+                    self._panel_proc.kill()
+            self._panel_proc = None
+        if self._panel:
+            self._panel.close()
+
+    def _finish(self, state, error=""):
+        if self._take:
+            self._end_take({"done": "complete", "stopped": "stopped"}.get(state, "stopped"))
+        if self._session_json is not None:
+            self._session_json["status"] = state
+            self._session_json["ended"] = time.strftime("%Y-%m-%dT%H:%M:%S%z")
+            if error:
+                self._session_json["error"] = error
+            if self._stop_note and state == "stopped":
+                self._session_json["stop_reason"] = self._stop_note
+            self._save_session()
+        self._log("%s%s" % (state, ": " + error if error else ""))
+        if self._stop_note and state == "stopped":
+            self._log(self._stop_note)
+        self._stop_units()
+        if self._button:
+            self._button.stop()
+            self._button = None
+        if self._panel:
+            screen = {"done": self.script.get("done") or {}, "stopped": self.script.get("stopped") or {},
+                      "error": {"title": "Something went wrong", "text": "See the Hand recorder window.",
+                                "seconds": 4}}[state]
+            try:
+                self._panel.cmd("paused off")
+                for key, c in (("big", "big "), ("action", "action "), ("rec", "rec off"), ("keys", "keys "),
+                               ("bar", "bar off"), ("target", "target off"), ("strip", "strip off")):
+                    self._panel.set(key, c)
+                self._screen(state, screen, controls=False)
+            except (_Stop, _Skip, _Fail):
+                pass
+        self._stop_panel()
+        if self._log_file:
+            self._log_file.close()
+            self._log_file = None
+        screen = {"done": self.script.get("done"), "stopped": self.script.get("stopped")}.get(state) or {}
+        self._emit(state=state, error=error, seconds_left=0.0, note="", take=None, section="",
+                   prompt=error or (self._stop_note if state == "stopped" else "") or screen.get("text", "").replace("|", "\n"),
+                   hands={"left": None, "right": None}, nohands=False,
+                   waiting=False, countdown=0, big="", can_redo=False, image="", image_mode="", caption="",
+                   position="", distance="", strip=[], cue=-1)
+
+    # --- the timing loop
+    def _controls(self):
+        """Handle a pause (blocking until resumed), skip, stop and redo (only where _redo_ok:
+        else it's dropped). True if a pause happened."""
+        with self._lock:
+            want = dict(self._want)
+            self._want["skip"] = self._want["redo"] = False
+        if want["stop"]:
+            raise _Stop()
+        if want["skip"]:
+            raise _Skip()
+        if want["redo"] and self._redo_ok:
+            raise _Redo()
+        if not want["pause"]:
+            return False
+        self._pause()
+        outcome = None
+        while outcome is None:
+            self._wake.wait(0.2)
+            self._wake.clear()
+            with self._lock:
+                want = dict(self._want)
+                self._want["skip"] = self._want["redo"] = False
+                redo = want["redo"] and self._redo_ok
+                if want["skip"] or redo:
+                    self._want["pause"] = False
+            if want["stop"]:
+                outcome = _Stop
+            elif want["skip"]:
+                outcome = _Skip
+            elif redo:
+                outcome = _Redo
+            elif not want["pause"]:
+                outcome = True
+        self._unpause(record=outcome is True)
+        if outcome is not True:
+            raise outcome()
+        return True
+
+    def _pause(self):
+        self._paused = True
+        self._state_before = self._status["state"]
+        self._paused_recording = self._recording
+        if self._recording:
+            self._stop_recording()
+            self._event("pause")
+        self._panel.cmd("paused on")
+        self._panel.set("note", "note " + RESUME_HINT)
+        self._emit(state="paused", note=RESUME_HINT)
+        self._log("paused")
+
+    def _unpause(self, record=True):
+        self._paused = False
+        self._panel.cmd("paused off")
+        self._panel.set("note", "note ")
+        self._fb.clear()
+        with self._lock:
+            self._want["next"] = False   # a Next pressed while paused doesn't count
+        if self._take and self._paused_recording and record:
+            self._event("resume")
+            self._start_recording()
+        self._emit(state=self._state_before, note="")
+        self._log("resumed")
+
+    def _wait(self, seconds, tick=None, countdown=True):
+        """Let `seconds` (script time) pass, handling the controls and feedback. tick(dt) runs
+        every step with the script time passed; it ends the wait early by returning True.
+        Returns True if tick ended it, else False."""
+        left = float(seconds)
+        last = time.monotonic()
+        last_cd = -1.0
+        while True:
+            if self._controls():
+                last = time.monotonic()
+            now = time.monotonic()
+            dt = (now - last) * self.speed
+            last = now
+            left -= dt
+            self._feedback()
+            if tick and tick(dt):
+                return True
+            if countdown and seconds > 0 and (now - last_cd >= 0.25 or left <= 0):
+                last_cd = now
+                self._panel.set("countdown", "countdown %.2f" % max(0.0, min(1.0, left / seconds)))
+            self._emit(force=False, seconds_left=round(max(left, 0.0), 1))
+            if left <= 0:
+                return False
+            self._wake.wait(TICK_S)
+            self._wake.clear()
+
+    # --- feedback
+    def _feedback(self):
+        now = time.monotonic()
+        fb = self._fb
+        if self._panel_proc and self._panel_proc.poll() is not None:
+            raise _Fail("The headset panel closed (did SteamVR quit?)")
+        if self._recorder and self._recorder.exited():
+            raise _Fail("The recording stopped by itself: see session.log")
+        if not self.dry_run and now - fb.get("disk", 0) > 5:
+            fb["disk"] = now
+            if shutil.disk_usage(self.session_dir).free < MIN_FREE:
+                raise _Fail("The disk is nearly full: the session stopped")
+        if not self.dry_run:
+            self._read_sides()
+        live = self._hands_file.read() if self._read_hands else None
+        self._live = live
+        w = self._hold_watch
+        if w is not None:
+            w["reads"] += 1
+            if live is not None:
+                w["published"] += 1
+                if live["left"] or live["right"]:
+                    w["seen"] += 1
+        p = self._prompt or {}
+        asked = p.get("hands", "")
+        # While a step waits for Next the chips show what's seen, with no notes yet.
+        seen = {s: (bool(live[s]) if live else None) for s in ("left", "right")}
+        # the chips: the asked-for hands, seen or lost, while the tracker publishes
+        chips = []
+        for side in ("left", "right"):
+            show = live is not None and (asked in (side, "both", "any"))
+            chips.append(("seen" if seen[side] else "lost") if show else "off")
+        self._panel.set("hands", "hands %s %s" % tuple(chips))
+        # a note when an asked-for hand stays lost, or a hand shows when none is wanted
+        notes = []
+        if live is not None and asked and not self._waiting:
+            if asked == "none":
+                missing = [] if not (seen["left"] or seen["right"]) else ["shown"]
+            elif asked == "any":
+                missing = [] if (seen["left"] or seen["right"]) else ["any"]
+            else:
+                missing = [s for s in ("left", "right") if asked in (s, "both") and not seen[s]]
+            key = ",".join(missing)
+            if key != fb.get("lost_key"):
+                fb["lost_key"], fb["lost_since"] = key, now
+            if missing and now - fb["lost_since"] > LOST_S:
+                if missing == ["shown"]:
+                    notes.append("I can see a hand: keep them out of view")
+                elif missing == ["any"] or len(missing) == 2:
+                    notes.append("I can't see your hands: bring them into view")
+                else:
+                    notes.append("I can't see your %s hand: bring it into view" % missing[0])
+        else:
+            fb.pop("lost_key", None)
+        notes = ([] if self._waiting else self._controller_feedback(now, p)) + notes
+        note = notes[0] if notes else ""
+        if not self._paused:
+            self._panel.set("note", "note " + note)
+        hands = {"left": seen["left"], "right": seen["right"]}
+        if note != self._status["note"] or hands != self._status["hands"]:
+            self._emit(note=note, hands=hands)
+        if self._take and self._recording and live is not None and now - fb.get("logged", 0) >= 0.5:
+            fb["logged"] = now
+            self._event("feedback", left=seen["left"], right=seen["right"],
+                        palm_m=[round(live[s]["palm_m"], 4) if live[s] else None for s in ("left", "right")])
+
+    def _controller_feedback(self, now, p):
+        """Sections with controllers: `devices` once a second; a result other than 200 for
+        more than a second gets a note, and each change goes into prompts.jsonl."""
+        sides = p.get("controllers") or []
+        fb = self._fb
+        if not sides:
+            fb.pop("ctl", None)
+            return []
+        ctl = fb.setdefault("ctl", {"polled": 0, "r": {}, "bad_since": {}, "lost": []})
+        if now - ctl["polled"] >= 1.0:
+            ctl["polled"] = now
+            reply = self._panel.cmd("devices", reply=True, timeout=0.3) or ""
+            tok = reply.split()
+            vals = dict(zip(tok[1::2], tok[2::2]))
+            if tok[:1] == ["ok"] and "hmd" in vals:
+                ctl["r"] = {s: vals.get(s, "-") for s in ("left", "right")}
+            for s in sides:
+                r = ctl["r"].get(s)
+                if r is None or r == "200":
+                    ctl["bad_since"].pop(s, None)
+                else:
+                    ctl["bad_since"].setdefault(s, now)
+        lost = sorted(s for s, t in ctl["bad_since"].items() if s in sides and now - t > CONTROLLER_LOST_S)
+        if lost != ctl["lost"]:
+            ctl["lost"] = lost
+            self._event("feedback", controller={s: (None if ctl["r"].get(s) in (None, "-") else int(ctl["r"][s]))
+                                                for s in ("left", "right")}, controller_lost=lost)
+        notes = []
+        for s in lost:
+            if ctl["r"].get(s) == "-":
+                notes.append("I can't find the %s controller: is it on?" % s)
+            else:
+                notes.append("The %s controller lost tracking: turn your palm slightly toward you" % s)
+        return notes
+
+    # --- sections and takes
+    def _show(self, title=None, step=None, text=None):
+        if title is not None:
+            self._panel.set("title", "title " + clean_text(title))
+        if step is not None:
+            self._panel.set("step", "step " + clean_text(step))
+        if text is not None:
+            self._panel.set("text", "text " + clean_text(text))
+
+    def _view(self, p=None):
+        """The prompt's picture and where-to diagram, on the panel and in the status (sent with
+        the next _emit); none without a prompt."""
+        p = p or {}
+        path, mode, caption = ("", "", "") if p.get("cues") else pose_view(self._poses, p)
+        self._strip(p)
+        pos, dist = p.get("position") or "", p.get("distance") or ""
+        self._panel.set("image", "image %s%s" % (path, " " + mode if mode else "") if path else "image off")
+        self._panel.set("where", "where %s %s" % (clean_text(pos) or "-", clean_text(dist) or "-")
+                        if pos or dist else "where off")
+        self._status.update(image=path, image_mode=mode, caption=caption, position=pos, distance=dist)
+
+    def _cue_name(self, pose):
+        return clean_text((self.script.get("cue_names") or {}).get(pose) or pose.replace("-", " ").capitalize())
+
+    def _strip(self, p):
+        """A sweep's strip of pictures, the cue's highlighted (panel "strip", status strip and
+        cue), or none. One hand per picture, as both hands make the same shape: a left hand's
+        flipped, the rest as drawn."""
+        poses = list(dict.fromkeys(p.get("cues") or []))   # each once, in the step's order
+        if not poses:
+            self._panel.set("strip", "strip off")
+            self._status.update(strip=[], cue=-1)
+            return
+        items = []
+        for pose in poses:
+            path, mode, _ = pose_view(self._poses, {"pose": pose, "hands": p.get("hands")})
+            items.append({"image": path, "mode": "" if mode == "both" else mode, "label": self._cue_name(pose)})
+        cue = poses.index(p["pose"]) if p.get("pose") in poses else -1
+        self._panel.set("strip", "strip %d %s" % (cue, ";".join(
+            "%s|%s|%s" % (e["image"] or "-", e["mode"] or "-", e["label"].replace("|", "/").replace(";", ","))
+            for e in items)))
+        self._status.update(strip=items, cue=cue)
+
+    def _hints(self, action=True):
+        """The Next hint (with action) and the key line for what's there now: the headset button
+        leads when no mouse is connected. Looked at again for each step, so a mouse plugged in counts."""
+        button = bool(self._button and self._button.ok)
+        mouse = mouse_connected(self.input_devices)
+        text = (READY_BUTTON_MOUSE if mouse else READY_BUTTON) if button else READY_TEXT
+        keys = (KEYS_AUTO_BUTTON if self.auto else KEYS_STEP_BUTTON) if button else (KEYS_AUTO if self.auto else KEYS_STEP)
+        if action:
+            self._panel.set("action", "action " + text)
+        self._panel.set("keys", "keys " + keys)
+        self._status.update(ready_text=text, button=button, mouse=mouse)
+
+    def _await_next(self):
+        """Step mode: wait for Next (or the next_after test hook), handling the controls and the
+        hands chips. Nothing records meanwhile."""
+        with self._lock:
+            self._want["next"] = False   # one pressed during the hold doesn't skip this
+        self._waiting = True
+        self._hints()
+        self._emit(waiting=True, seconds_left=0.0)
+        t0 = time.monotonic()
+        try:
+            while True:
+                self._controls()
+                self._feedback()
+                with self._lock:
+                    go, self._want["next"] = self._want["next"], False
+                if go or (self.next_after is not None and time.monotonic() - t0 >= self.next_after):
+                    break
+                self._wake.wait(TICK_S)
+                self._wake.clear()
+        finally:
+            self._waiting = False
+            self._panel.set("action", "action ")
+        self._emit(waiting=False)
+
+    def _screen(self, state, screen, controls=True):
+        """A screen of its own (welcome, done): title, text, a few seconds, or in step mode
+        until Next. controls=False: the session's end, which reports its state once all is done."""
+        if not screen:
+            return
+        self._prompt = None
+        self._show(screen.get("title", ""), "", screen.get("text", ""))
+        self._view()
+        self._panel.set("countdown", "countdown off")
+        if controls:
+            self._emit(state=state, title=screen.get("title", ""), prompt=screen.get("text", "").replace("|", "\n"),
+                       section="", seconds_left=float(screen.get("seconds", 0)))
+            try:
+                if self.auto:
+                    self._wait(screen.get("seconds", 0), countdown=False)
+                else:
+                    self._await_next()
+            except _Skip:
+                pass
+        else:
+            end = time.monotonic() + screen.get("seconds", 0) / self.speed
+            while time.monotonic() < end and not self._want["stop"]:
+                time.sleep(TICK_S)
+
+    def _section(self, i, s):
+        step = "Section %d of %d" % (i + 1, len(self.plan))
+        status = {"section": s["id"], "title": s["title"], "section_index": i + 1, "section_count": len(self.plan),
+                  "step_index": 0, "step_count": section_steps(s) if not self.auto else 0, "can_redo": False}
+        try:
+            before = s.get("before")
+            self._prompt = None
+            self._view()
+            if self.auto:
+                if before or i > 0:
+                    text = before["text"] if before else "Next: %s" % s["title"]
+                    secs = before.get("seconds", 10) if before else self.script.get("between_s", 3)
+                    self._show("Get ready" if before else s["title"], step, text)
+                    self._emit(state="between", prompt=text.replace("|", "\n"), take=None, **status)
+                    self._wait(secs)
+                self._start_take(i, s)
+                self._status.update(state="intro", take=self._take["id"], **status)   # sent with the intro
+                self._run_prompt(s, {"id": s["id"] + "/intro", "text": s.get("intro", ""), "seconds": s["intro_s"],
+                                     "hands": "", "pose": "", "distance": "", "position": "", "object": "",
+                                     "controller": False, "controllers": []}, step, intro=True)
+            else:
+                # One screen before the section: what to get ready, and the intro. The take
+                # starts with the first step's countdown, so a section skipped here leaves none.
+                text = "|".join(t for t in ((before or {}).get("text", ""), s.get("intro", "")) if t)
+                self._show(s["title"], step, text)
+                self._panel.set("countdown", "countdown off")
+                self._emit(state="intro", prompt=text.replace("|", "\n"), take=None, seconds_left=0.0, **status)
+                self._await_next()
+            self._status["state"] = "running"   # sent with the first prompt
+            self._steps(i, s, step)
+            if self._take:
+                self._end_take("complete")
+        except _Skip:
+            self._log("skipped %s" % s["id"])
+            if self._take:
+                self._end_take("skipped")
+        except _Stop:
+            raise
+        finally:
+            self._redo_ok = False
+            self._status["big"] = ""
+            for key, c in (("bar", "bar off"), ("target", "target off"), ("big", "big "), ("action", "action ")):
+                self._panel.set(key, c)
+
+    def _start_take(self, i, s, record=True):
+        n = len(self._session_json["takes"]) + 1
+        take_id = "%02d-%s" % (n, s["id"])
+        d = os.path.join(self.session_dir, "takes", take_id)
+        os.makedirs(d)
+        self._take = {"id": take_id, "dir": d, "section": s, "part": 0,
+                      "prompts": open(os.path.join(d, "prompts.jsonl"), "a", buffering=1),
+                      "json": {"section": s["id"], "title": s["title"], "started_ns": mono_ns(), "ended_ns": None,
+                               "status": "stopped", "deleted": [], "notes": ""}}
+        write_json(os.path.join(d, "take.json"), self._take["json"])
+        self._session_json["takes"].append(take_id)
+        self._save_session()
+        self._event("take", section=s["id"], take=take_id)
+        if record:
+            self._start_recording()
+        self._log("take %s" % take_id)
+        self._emit(force=False, take=take_id)
+
+    def _start_recording(self):
+        t = self._take
+        t["part"] += 1
+        t["json"].setdefault("clock", []).append(clock_sample())
+        if not self.dry_run:
+            # a safety net only: the session ends the recording itself
+            remaining = section_seconds(t["section"], worst=True, auto=self.auto) / self.speed
+            self._recorder = Recorder(t["dir"], t["part"], remaining * 1.5 + 60, self.ring, self._log_file,
+                                      swap=self._sides_swapped())
+        self._recording = True
+        self._panel.cmd("poses start " + os.path.join(t["dir"], "poses.jsonl"))
+        self._panel.set("rec", "rec on")
+
+    def _stop_recording(self):
+        if not self._recording:
+            return
+        self._recording = False
+        self._panel.set("rec", "rec off")
+        self._panel.cmd("poses stop", reply=not self.dry_run, timeout=1.0)
+        if self._recorder:
+            rec, self._recorder = self._recorder, None
+            code = rec.stop()
+            self._log("recording part %d ended (%s)" % (rec.part, code))
+            if self._take:   # how this part's side cameras are named (sides.py)
+                self._take["json"].setdefault("parts", {})[rec.file] = {"names_swapped": rec.names_swapped}
+                self._take["json"].setdefault("clock", []).append(clock_sample())
+                write_json(os.path.join(self._take["dir"], "take.json"), self._take["json"])
+
+    def _end_take(self, status):
+        t = self._take
+        try:
+            self._stop_recording()
+        finally:
+            self._event("end", status=status)
+            self._take = None
+            t["prompts"].close()
+            t["json"]["ended_ns"] = mono_ns()
+            t["json"]["status"] = status
+            write_json(os.path.join(t["dir"], "take.json"), t["json"])
+            self._log("take %s %s" % (t["id"], status))
+
+    def _prompt_event(self, p):
+        extra = {"controllers": p["controllers"]} if p["controllers"] else {}
+        if p.get("cue"):   # a sweep's cue: the pose highlighted from now, within the step
+            extra.update(cue=True, step=p["step"])
+        return self._event("prompt", id=p["id"], text=p["text"], hands=p["hands"], pose=p["pose"],
+                           distance=p["distance"], position=p["position"], object=p["object"],
+                           controller=bool(p["controller"]), **extra)
+
+    def _begin_prompt(self, s, p, step, state="running"):
+        self._prompt = p
+        self._fb.pop("lost_key", None)
+        self._show(s["title"], step, p["text"])
+        self._view(p)
+        t = self._prompt_event(p)
+        if self._step_t0 is None:
+            self._step_t0 = t
+        self._emit(state=state, prompt=p["text"].replace("|", "\n"), seconds_left=float(p["seconds"]), countdown=0)
+        self._log("  %s" % p["id"])
+
+    def _run_prompt(self, s, p, step, intro=False):
+        if intro and not p["text"]:
+            return
+        self._begin_prompt(s, p, step, state="intro" if intro else "running")
+        self._wait(p["seconds"])
+
+    # --- steps: a section's prompts, bar heights and targets
+    def _step_list(self, s):
+        """[{"kind": "prompt"|"sweep"|"bar"|"target", "p": prompt, "ready": waits for Next in step mode, ...}]."""
+        out = []
+        defaults = s.get("defaults") or {}
+        if s["kind"] == "targets":
+            for k, pt in enumerate(s["targets"]):
+                p = {"id": "%s/%d" % (s["id"], k + 1), "text": s.get("text", ""), "seconds": float(s.get("timeout_s", 8)),
+                     "hands": defaults.get("hands", "any"), "pose": defaults.get("pose", "point"), "distance": "",
+                     "position": "", "object": "", "controller": False, "controllers": []}
+                out.append({"kind": "target", "p": p, "pt": pt, "ready": k == 0})
+        elif s["kind"] == "bar":
+            lead = float(s.get("lead_s", 3)) if self.auto else 0.0   # step mode: the countdown shows the bar at near
+            for h in s["heights"]:
+                p = {"id": "%s/%s" % (s["id"], h["id"]), "text": h["text"], "hands": defaults.get("hands", "both"),
+                     "pose": defaults.get("pose", "open"), "distance": "", "position": h["id"], "object": "",
+                     "picture": h.get("picture", defaults.get("picture", "")),
+                     "controller": bool(defaults.get("controller", False)),
+                     "controllers": list(defaults.get("controllers") or []),
+                     "seconds": lead + h["reps"] * float(s.get("period_s", 6))}
+                out.append({"kind": "bar", "p": p, "h": h, "lead": lead, "ready": True})
+        out += [{"kind": "sweep" if p.get("cues") else "prompt", "p": p, "ready": True} for p in s["prompts"]]
+        return out
+
+    def _steps(self, i, s, label):
+        """Run a section's steps. Step mode: each that's "ready" (and each to do again) shows
+        first and waits for Next; then the recorded countdown; the recording stops after a
+        step unless the next one follows straight on (the targets after the first). R: the
+        step running starts again; at a ready screen, the step before goes again. Either way
+        the range done before is marked with a "redo" event."""
+        steps = self._step_list(s)
+        done = []      # the steps finished in this take: (index, id, from_ns, to_ns), for R
+        again = set()  # steps to do again: they wait for Next too
+        retry = False  # after the no-hands stop: Next was pressed there, go straight to the countdown
+        k = 0
+        while k < len(steps):
+            st, p = steps[k], steps[k]["p"]
+            where = label if self.auto else "%s · step %d of %d" % (label, k + 1, len(steps))
+            self._status.update(step_index=k + 1, step_count=len(steps))
+            started, self._step_t0 = None, None
+            try:
+                if not self.auto and (st["ready"] or k in again):
+                    self._redo_ok = bool(done)
+                    self._ready(s, st, where, can_redo=bool(done))
+                    if not retry:
+                        self._await_next()
+                    retry = False
+                    self._redo_ok = True
+                    started = self._countdown(i, s, st)
+                else:
+                    retry = False
+                    self._redo_ok = True
+                    self._emit(force=False, can_redo=True)
+                check = self._read_hands and s["id"] == HANDS_CHECK_SECTION and k == 0 and st["kind"] in ("prompt", "sweep")
+                self._hold_watch = {"reads": 0, "published": 0, "seen": 0} if check else None
+                try:
+                    self._run_step(s, st, where)
+                finally:
+                    watch, self._hold_watch = self._hold_watch, None
+                if check and self._no_hands_seen(p, watch):
+                    self._no_hands(s, st, where, started if started is not None else self._step_t0, watch)
+                    again.add(k)
+                    retry = True
+                    continue
+                done.append((k, p["id"], started if started is not None else self._step_t0, mono_ns()))
+                if not self.auto and (k + 1 == len(steps) or steps[k + 1]["ready"] or k + 1 in again):
+                    self._hold_end()
+                again.discard(k)
+                k += 1
+            except _Redo:
+                self._redo_ok = False
+                from_ns = started if started is not None else self._step_t0
+                self._panel.set("target", "target off")
+                self._panel.set("bar", "bar off")
+                if from_ns is not None:   # R during the step: it starts again
+                    self._event("redo", id=p["id"], **{"from": from_ns, "to": mono_ns()})
+                    self._log("    redo %s" % p["id"])
+                    if not self.auto:
+                        self._hold_end()
+                    elif self._take and not self._recording:   # R ended a pause: record again
+                        self._event("resume")
+                        self._start_recording()
+                    again.add(k)
+                elif done:                # R at its ready screen: the step before goes again
+                    k, pid, a, b = done.pop()
+                    self._event("redo", id=pid, **{"from": a, "to": b})
+                    self._log("    redo %s" % pid)
+                    again.add(k)
+
+    def _no_hands_seen(self, p, w):
+        """The no-hands check's verdict on a hold (logged either way): True if the tracker
+        published through it and never saw a hand."""
+        enough = w["reads"] >= HANDS_CHECK_MIN_READS and w["published"] >= HANDS_CHECK_PUBLISHED * w["reads"]
+        if not enough:
+            self._log("    hands check %s: the tracker published in %d of %d reads: can't tell"
+                      % (p["id"], w["published"], w["reads"]))
+            return False
+        self._log("    hands check %s: a hand in %d of %d reads (%d published)"
+                  % (p["id"], w["seen"], w["reads"], w["published"]))
+        return w["seen"] == 0
+
+    def _no_hands(self, s, st, where, from_ns, w):
+        """The first step saw no hands at all: stop it (its range marked as redone, so it gets
+        no labels), run the camera check, say so, and wait. Next or R tries the step again; Stop
+        (Esc) ends the session with the camera check's result; S skips the section."""
+        p = st["p"]
+        if not self.auto:
+            self._hold_end()
+        elif self._recording:
+            self._stop_recording()
+            self._event("pause")
+        self._event("nohands", id=p["id"], reads=w["reads"], published=w["published"])
+        if from_ns is not None:
+            self._event("redo", id=p["id"], **{"from": from_ns, "to": mono_ns()})
+        cam = self.camera_check_fn() if self.check_cameras else None
+        cam_text = camera_text(cam)
+        summary = (cam or {}).get("summary", "not run")
+        self._log("    no hands seen in %s: asking to try again or stop; camera check: %s" % (p["id"], summary))
+        for line in (cam or {}).get("evidence", []):
+            self._log("      " + line)
+        text = "%s|%s|%s" % (NO_HANDS_TEXT, cam_text or "The camera check found nothing wrong (%s)." % summary,
+                             NO_HANDS_RETRY)
+        self._stop_note = "Stopped: no hands were seen in the first step. Camera check: %s." % summary
+        if cam_text:
+            self._stop_note += " " + cam_text
+        self._prompt = None
+        self._view()
+        self._show(NO_HANDS_TITLE, where, text)
+        for key, c in (("big", "big "), ("countdown", "countdown off"), ("bar", "bar off"), ("target", "target off"),
+                       ("note", "note "), ("hands", "hands off off")):
+            self._panel.set(key, c)
+        self._emit(state="nohands", prompt=text.replace("|", "\n"), camera=cam, nohands=True, can_redo=True,
+                   big="", countdown=0, seconds_left=0.0)
+        self._redo_ok = True
+        try:
+            self._await_next()
+        except _Redo:
+            pass   # R here is the same as Next: try again
+        except _Skip:
+            self._stop_note = ""
+            self._emit(nohands=False)
+            raise
+        self._stop_note = ""
+        self._log("    trying %s again" % p["id"])
+        self._emit(nohands=False)
+        if self.auto and self._take and not self._recording:
+            self._event("resume")
+            self._start_recording()
+
+    def _ready(self, s, st, where, can_redo):
+        """Step mode: show the step (text, picture, diagram) with "Ready?"."""
+        p = st["p"]
+        self._prompt = p   # the chips show which hands are seen while the person gets ready
+        self._fb.pop("lost_key", None)
+        self._show(s["title"], where, p["text"])
+        self._view(p)
+        for key, c in (("big", "big "), ("countdown", "countdown off"), ("bar", "bar off"), ("target", "target off")):
+            self._panel.set(key, c)
+        self._emit(state="ready", prompt=p["text"].replace("|", "\n"), seconds_left=float(p["seconds"]),
+                   can_redo=can_redo, countdown=0, big="")
+
+    def _countdown(self, i, s, st):
+        """Step mode: start recording and count 3-2-1 (logged as a "ready" event, so labels
+        cover only the hold), then make sure the recording has its first set. Returns the
+        ready event's time."""
+        p = st["p"]
+        if not self._take:
+            self._start_take(i, s, record=False)
+        t = self._event("ready", id=p["id"], seconds=COUNTDOWN_S)
+        self._step_t0 = t
+        self._start_recording()
+        tick = None
+        if st["kind"] == "bar":   # the bar at near, where the sweep starts
+            labels = "%s|%s" % (s.get("near_label", "Near"), s.get("far_label", "Far"))
+            near, far = float(s.get("near_m", 0.2)), float(s.get("far_m", 0.6))
+
+            def tick(dt):
+                self._panel.set("bar", "bar 0.000 %.3f %s" % (self._palm_share(near, far), labels))
+                return False
+        for n in range(COUNTDOWN_S, 0, -1):
+            self._panel.set("big", "big %d" % n)
+            self._emit(state="countdown", countdown=n, big=str(n), can_redo=True)
+            self._wait(1.0, tick, countdown=False)
+        self._first_set()
+        self._panel.set("big", "big " + s.get("go", "Go"))
+        self._status["big"] = s.get("go", "Go")   # sent with the prompt
+        return t
+
+    def _first_set(self):
+        """The hold starts once its recording has a set. ft-hands --record-only writes its first
+        within about 30 ms of starting, so the countdown covers it; this is a safety net."""
+        rec = self._recorder
+        if not rec:
+            return
+        end = time.monotonic() + FIRST_SET_S
+        while not rec.has_data():
+            if rec.exited():
+                raise _Fail("The recording stopped by itself: see session.log")
+            if self._want["stop"]:
+                raise _Stop()
+            if time.monotonic() > end:
+                self._log("recording part %d: no set yet after the countdown" % rec.part)
+                return
+            time.sleep(0.02)
+
+    def _hold_end(self):
+        """Step mode: the step is over. A "wait" event ends its labels and the recording stops
+        until the next countdown."""
+        self._event("wait")
+        self._stop_recording()
+        self._status["big"] = ""
+        for key, c in (("big", "big "), ("countdown", "countdown off"), ("bar", "bar off"), ("target", "target off")):
+            self._panel.set(key, c)
+
+    def _run_step(self, s, st, where):
+        if st["kind"] != "bar":
+            self._panel.set("bar", "bar off")
+        if st["kind"] == "target":
+            self._target(s, st, where)
+        elif st["kind"] == "bar":
+            self._bar(s, st, where)
+        elif st["kind"] == "sweep":
+            self._sweep(s, st, where)
+        else:
+            self._run_prompt(s, st["p"], where)
+
+    def _sweep(self, s, st, where):
+        """A sweep: the strip's pictures highlighted in turn, one every cue_s, while the hands
+        keep moving. Each cue is a prompt event of its own, with that pose, "cue": true and the
+        step's id, so the timeline tags each pose roughly; the time-left bar covers the step."""
+        p = st["p"]
+        cues, cue_s = p["cues"], p["cue_s"]
+        seen = {}
+
+        def cue_prompt(j):
+            pose = cues[j]
+            seen[pose] = seen.get(pose, 0) + 1
+            return dict(p, id="%s/%s%s" % (p["id"], pose, "#%d" % seen[pose] if seen[pose] > 1 else ""),
+                        pose=pose, cue=True, step=p["id"])
+
+        self._begin_prompt(s, cue_prompt(0), where)
+        state = {"t": 0.0, "j": 0}
+
+        def tick(dt):
+            state["t"] += dt
+            j = min(len(cues) - 1, int(state["t"] / cue_s + 1e-9))
+            if j != state["j"]:
+                state["j"] = j
+                cp = cue_prompt(j)
+                self._prompt = cp
+                self._strip(cp)
+                self._prompt_event(cp)
+                self._emit()
+                self._log("    cue %s" % cp["id"])
+            return False
+
+        self._wait(p["seconds"], tick)
+
+    def _target(self, s, st, where):
+        hold_s, timeout_s = float(s.get("hold_s", 1.0)), float(s.get("timeout_s", 8))
+        p, pt = st["p"], st["pt"]
+        self._begin_prompt(s, p, where)
+        xyz = "%.3f %.3f %.3f" % tuple(pt)
+        reply = self._panel.cmd("target %s show" % xyz, reply=True) or ""
+        self._panel.sent["target"] = "target %s show" % xyz
+        tok = reply.split()
+        room = [float(v) for v in tok[1:4]] if tok[:1] == ["ok"] and len(tok) >= 4 else None
+        target = {"id": p["id"], "head": list(pt), "room": room}
+        self._event("target", state="show", **target)
+        state = {"hold": 0.0, "sent": 0.0, "holding": False}
+
+        def tick(dt):
+            d = self._tip_distance(pt, room)
+            if d is not None and d <= TOUCH_M:
+                if not state["holding"]:
+                    state["holding"] = True
+                    self._event("target", state="hold", **target)
+                state["hold"] += dt
+            elif state["holding"]:
+                state["holding"], state["hold"] = False, 0.0
+                self._panel.set("target", "target %s show" % xyz)
+            if state["holding"]:
+                frac = min(1.0, state["hold"] / hold_s)
+                if time.monotonic() - state["sent"] >= 0.1 or frac >= 1:
+                    state["sent"] = time.monotonic()
+                    self._panel.set("target", "target %s hold %.2f" % (xyz, frac))
+            return state["hold"] >= hold_s
+
+        done = self._wait(timeout_s, tick)
+        result = "done" if done else "timeout"
+        if done:
+            self._panel.set("target", "target %s done" % xyz)
+        self._event("target", state=result, **target)
+        self._log("    %s %s" % (p["id"], result))
+        if done:
+            self._wait(0.6, countdown=False)
+        self._panel.set("target", "target off")
+
+    def _tip_distance(self, pt, room):
+        """The nearest seen index tip's distance from the target: in the room (with the head's
+        pose now) when the panel placed the target there, else in the head frame."""
+        live = self._live
+        if not live:
+            return None
+        tips = [live[s]["tip"] for s in ("left", "right") if live[s]]
+        if not tips:
+            return None
+        ref = pt
+        if room is not None:
+            reply = (self._panel.cmd("head", reply=True, timeout=0.1) or "").split()
+            if reply[:1] == ["ok"] and len(reply) == 13:
+                m = [float(v) for v in reply[1:]]
+                tips = [[m[4 * r] * t[0] + m[4 * r + 1] * t[1] + m[4 * r + 2] * t[2] + m[4 * r + 3] for r in range(3)]
+                        for t in tips]
+                ref = room
+        return min(math.dist(t, ref) for t in tips)
+
+    def _palm_share(self, near, far):
+        live = self._live
+        if not live:
+            return -1.0
+        ds = [live[s]["palm_m"] for s in ("left", "right") if live[s]]
+        if not ds:
+            return -1.0
+        return max(0.0, min(1.0, (sum(ds) / len(ds) - near) / (far - near)))
+
+    def _bar(self, s, st, where):
+        """One height of the push out and back: the target sweeps near to far and back."""
+        near, far = float(s.get("near_m", 0.2)), float(s.get("far_m", 0.6))
+        period, lead = float(s.get("period_s", 6)), st["lead"]
+        labels = "%s|%s" % (s.get("near_label", "Near"), s.get("far_label", "Far"))
+        p = st["p"]
+        self._begin_prompt(s, p, where)
+        state = {"t": 0.0, "sent": 0.0}
+
+        def tick(dt):
+            state["t"] += dt
+            sweep = state["t"] - lead
+            target = 0.0 if sweep <= 0 else 1 - abs(1 - 2 * ((sweep % period) / period))
+            if time.monotonic() - state["sent"] >= 0.1:
+                state["sent"] = time.monotonic()
+                cur = self._palm_share(near, far)
+                self._panel.set("bar", "bar %.3f %.3f %s" % (target, cur, labels))
+                if sweep > 0:
+                    self._event("bar", target=round(target, 3), current=None if cur < 0 else round(cur, 3))
+            return False
+
+        self._wait(p["seconds"], tick)
+
+
+# ------------------------------------------------------------------------------------------
+# The command line
+
+def main():
+    ap = argparse.ArgumentParser(description="Run a hand recording session (the hand recorder's session runner).")
+    ap.add_argument("--dry-run", action="store_true", help="run no processes; print the panel commands")
+    ap.add_argument("--speed", type=float, default=1.0, help="run the script this many times faster")
+    ap.add_argument("--ring", help="read frames from this ring (ft-ringplay's) instead of ft-camd's")
+    ap.add_argument("--no-start", action="store_true", help="start no ft-camd or tracking ft-hands")
+    ap.add_argument("--base", help="where sessions go (default %s; a temporary folder with --dry-run)" % BASE_DIR)
+    ap.add_argument("--objects", default="", help="ticked objects, comma-separated (unknown names are your own)")
+    ap.add_argument("--controllers", action="store_true", help="controllers with the straps")
+    ap.add_argument("--lighting", default="auto", choices=("auto", "dim", "room", "daylight"),
+                    help="this round's light (auto: indoor or daylight, from the cameras)")
+    ap.add_argument("--script", default=SCRIPT_PATH)
+    ap.add_argument("--panel", help="the panel program (default hands/rec/build/ft-handpanel)")
+    ap.add_argument("--hands-dir", help="where the hands file is (default /run/user/UID/frametop-hands)")
+    ap.add_argument("--plan", action="store_true", help="print the sections and their length, and exit")
+    ap.add_argument("--auto", action="store_true",
+                    help="advance by itself: each prompt for its time, no waiting for Next (the old timed flow)")
+    ap.add_argument("--next-after", type=float, metavar="S",
+                    help="test: press Next by itself after S seconds of waiting (real time)")
+    ap.add_argument("--poses", help="the pose pictures' folder, with poses.json (default hands/rec/poses)")
+    ap.add_argument("--no-headset-button", action="store_true",
+                    help="don't read the headset's button (gpio-keys KEY_SELECT: Next, pause, resume)")
+    ap.add_argument("--button-device", metavar="PATH",
+                    help="test: read the button from this event device or FIFO of input_event structs (also in a dry run)")
+    ap.add_argument("--quick", action="store_true",
+                    help="a quick round (about 3 min, for another lighting): hand size, the two-hand sweeps, touch, no hands")
+    ap.add_argument("--seed", type=int, help="the sweeps' shuffle (default: from the session's id; --plan: the script's order)")
+    ap.add_argument("--ignore-cameras", action="store_true",
+                    help="start even if the camera check (hands/camcheck.py) finds the upper cameras off")
+    a = ap.parse_args()
+
+    known = ("pencil", "phone", "cup", "keyboard", "mouse", "gamepad", "small")
+    names = [o.strip() for o in a.objects.split(",") if o.strip()]
+    checklist = {"objects": [o for o in names if o in known], "own_objects": [o for o in names if o not in known],
+                 "controllers": "straps" if a.controllers else "none", "sleeves": "", "rings": False,
+                 "watch": False, "notes": ""}
+    base = a.base
+    if not base and a.dry_run:
+        import tempfile
+        base = tempfile.mkdtemp(prefix="handrec-dry-")
+    base = base or BASE_DIR
+    profile = {}
+    try:
+        with open(os.path.join(base, "profile.json")) as f:
+            profile = json.load(f)
+    except (OSError, ValueError):
+        pass
+
+    t0 = time.monotonic()
+    last = {}
+
+    def on_status(st):
+        key = (st["state"], st["section"], st["prompt"], st["note"], st["take"], st["waiting"], st["countdown"],
+               st["hands"]["left"], st["hands"]["right"], st["error"])
+        if key == last.get("key"):
+            return
+        last["key"] = key
+        hands = "".join("%s%s" % (s[0].upper(), {True: "+", False: "-", None: "?"}[st["hands"][s]])
+                        for s in ("left", "right"))
+        state = "%s %d" % (st["state"], st["countdown"]) if st["state"] == "countdown" else st["state"]
+        line = "[%6.1f] %-11s %d/%d %-16s %s %s" % (time.monotonic() - t0, state, st["section_index"],
+                                                    st["section_count"], st["section"] or "-", hands,
+                                                    st["prompt"].replace("\n", " | "))
+        if st["image"]:
+            line += "  [%s%s]" % (os.path.basename(st["image"]), " " + st["image_mode"] if st["image_mode"] else "")
+        if st["waiting"]:
+            line += "  (waiting for Next)"
+        if st["note"]:
+            line += "  (%s)" % st["note"]
+        if st["error"]:
+            line += "  ERROR: %s" % st["error"]
+        print(line, flush=True)
+
+    s = Session(base, profile, checklist, a.lighting, a.script, ring=a.ring, start_processes=not a.no_start,
+                dry_run=a.dry_run, speed=a.speed, on_status=on_status, hands_dir=a.hands_dir, panel_bin=a.panel,
+                auto=a.auto, next_after=a.next_after, poses_dir=a.poses, button=not a.no_headset_button,
+                button_device=a.button_device, check_cameras=not a.ignore_cameras, quick=a.quick, seed=a.seed)
+    est = plan_seconds(s.script, s.plan, auto=a.auto)
+    worst = plan_seconds(s.script, s.plan, worst=True, auto=a.auto)
+    print("%d sections%s, %s mode: about %.1f min%s (at most %.1f)%s" % (
+        len(s.plan), " (a quick round)" if a.quick else "", "auto" if a.auto else "step", est / 60, "" if a.auto else " recorded", worst / 60,
+        ", %gx speed" % a.speed if a.speed != 1 else ""))
+    if not a.auto:
+        print("  %d steps wait for Next: add your reading time (at 5 s a step, %.1f min)"
+              % (plan_steps(s.plan), plan_steps(s.plan) * 5 / 60))
+    for sk in s.skipped:
+        print("  skipping %s: %s" % (sk["section"], sk["reason"]))
+    if a.plan:
+        for sec in s.plan:
+            print("  %-18s %-9s %3d prompts %3d steps %5.0f s" % (sec["id"], sec["kind"], len(sec["prompts"]),
+                                                                section_steps(sec), section_seconds(sec, auto=a.auto)))
+            for p in sec["prompts"]:
+                if p.get("cues"):
+                    print("      %-26s %-5s %3.0f s  %s" % (p["id"], p["hands"], p["seconds"], " ".join(p["cues"])))
+        return 0
+    if not a.dry_run and not a.ring:
+        cam = camera_check()
+        print("cameras: %s" % cam["summary"])
+        for line in cam.get("evidence", []):
+            print("  " + line)
+        if camera_text(cam):
+            print(camera_text(cam))
+            if not a.ignore_cameras:
+                print("Not starting (--ignore-cameras starts anyway).")
+                return 3
+    if not a.dry_run:
+        light = ring_lighting(a.ring)
+        match = similar_lighting(base, {"chosen": a.lighting, "ring": light}) if light else None
+        print("lighting: %s" % (json.dumps(light) if light else "no camera ring"))
+        if light:
+            print("  measured: %s (ambient IR %s)" % (classify_lighting(light) or "can't tell", ambient_ir(light)))
+        if match:
+            print("  about the same light as session %s (%s)" % match)
+
+    def on_signal(*_):
+        print("stopping", flush=True)
+        threading.Thread(target=s.stop, daemon=True).start()
+
+    signal.signal(signal.SIGINT, on_signal)
+    signal.signal(signal.SIGTERM, on_signal)
+    def keys():
+        # From a terminal, or lines piped in (a test); /dev/null ends at once.
+        if sys.stdin.isatty():
+            print("keys (then Enter): n or just Enter next, p pause/resume, r redo, s skip section, q stop", flush=True)
+        for line in sys.stdin:
+            c = line.strip()[:1].lower()
+            if c in ("n", ""):
+                s.next_step()
+            elif c == "p":
+                s.resume() if s.state == "paused" else s.pause()
+            elif c == "r":
+                s.redo()
+            elif c == "s":
+                s.skip()
+            elif c == "q":
+                s.stop(wait=0)
+    if sys.stdin is not None:
+        threading.Thread(target=keys, daemon=True).start()
+    s.start()
+    while s._thread.is_alive():
+        s.join(0.5)
+    print("session: %s" % s.session_dir)
+    return 0 if s.state in ("done", "stopped") else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/hands/rec/sides.py b/hands/rec/sides.py
new file mode 100644
index 0000000..5b91618
--- /dev/null
+++ b/hands/rec/sides.py
@@ -0,0 +1,128 @@
+"""Which side camera is which, in recordings: the rules every reader shares.
+
+ft-camd tells slam_left's buffers from slam_right's by the order XRService allocated them, and
+some XRService starts reverse it: then each side camera's images carry the other's name. A
+tracking ft-hands tells from the hands (hands/track/sides.h, HANDS_SWAP_SIDES=auto) and publishes
+what it found in /run/user/UID/frametop-hands/sides.json (read_live). Two things are recorded:
+
+  swapped         whether ft-camd's naming was backwards during the recording (the truth);
+                  None while nobody knows. A hand recorder session has it in session.json
+                  "sides": {"swapped", "decided_by", "evidence", ...}; an ft-hands --record
+                  recording in DIR/sides.json.
+  names_swapped   per recording file: whether the side cameras' names in it were exchanged from
+                  ft-camd's (ft-hands --sides 1). A session's take.json "parts": {"sets.bin":
+                  {"names_swapped": false}, "sets-2.bin": {...}}; DIR/sides.json "names_swapped":
+                  [[first set, bool], ...] (it can change inside a recording when ft-hands decides).
+
+A file's names are right when names_swapped == swapped. Readers rename slam_left <-> slam_right
+(and their _dk dark frames) where they differ (needs_rename). Exports always carry the right
+names, with names_swapped = swapped written next to them, so applying the rule again is harmless.
+
+Standard library only (the window, validate.py on Windows, the maintainer's tools).
+"""
+import json
+import os
+import struct
+import time
+
+HDR = struct.Struct("<8sII")       # fh_set_hdr_t (hands/track/record.h)
+CAM = struct.Struct("<16sIIQQ")    # fh_set_cam_t: name, width, height, capture_ns, dqbuf_ns
+SIDES = {"slam_left": "slam_right", "slam_right": "slam_left",
+         "slam_left_dk": "slam_right_dk", "slam_right_dk": "slam_left_dk"}
+LIVE_FRESH_S = 6.0   # ft-hands rewrites its sides.json at least every 2 s
+
+
+def other_name(name):
+    """slam_left <-> slam_right (and their dark frames); other names as they are."""
+    return SIDES.get(name, name)
+
+
+def needs_rename(swapped, names_swapped):
+    """True when a file's side cameras carry each other's names. Unknown truth: leave them."""
+    if swapped is None:
+        return False
+    return bool(names_swapped) != bool(swapped)
+
+
+def rename_record(record):
+    """One FHSET01 record (bytes) with slam_left and slam_right's names exchanged (and their
+    dark frames'). Only the 16-byte name fields change; pixels and lengths stay."""
+    out = bytearray(record)
+    ncams = HDR.unpack_from(out, 0)[1]
+    for k in range(ncams):
+        off = HDR.size + k * CAM.size
+        raw = bytes(out[off:off + 16])
+        name = raw.split(b"\0", 1)[0].decode(errors="replace")
+        new = other_name(name)
+        if new != name:
+            out[off:off + 16] = new.encode().ljust(16, b"\0")
+    return bytes(out)
+
+
+# ------------------------------------------------------------------ sessions and recordings
+
+def session_sides(session_json):
+    """A session.json's "sides" (a dict), or {"swapped": None} when it has none."""
+    s = (session_json or {}).get("sides")
+    return s if isinstance(s, dict) else {"swapped": None}
+
+
+def part_names_swapped(take_json, part):
+    """Whether a take's part file (e.g. "sets-2.bin") was recorded with exchanged names."""
+    parts = (take_json or {}).get("parts")
+    entry = parts.get(part) if isinstance(parts, dict) else None
+    return bool(entry.get("names_swapped")) if isinstance(entry, dict) else False
+
+
+def part_rename(session_json, take_json, part):
+    """Should a session take's part file have its side cameras renamed when read?"""
+    return needs_rename(session_sides(session_json).get("swapped"), part_names_swapped(take_json, part))
+
+
+def recording_runs(rec_dir):
+    """An ft-hands --record recording (DIR/sets.bin + DIR/sides.json): [(first set, rename)],
+    or [(0, False)] when it has no sides.json (recorded before there was one)."""
+    try:
+        with open(os.path.join(rec_dir, "sides.json")) as f:
+            s = json.load(f)
+    except (OSError, ValueError):
+        return [(0, False)]
+    runs = s.get("names_swapped") or [[0, False]]
+    return [(int(first), needs_rename(s.get("swapped"), sw)) for first, sw in runs]
+
+
+def rename_at(runs, i):
+    """recording_runs()'s answer for set i."""
+    out = False
+    for first, rename in runs:
+        if i >= first:
+            out = rename
+    return out
+
+
+# ------------------------------------------------------------------ the live decision
+
+def run_dir():
+    return "/run/user/%d/frametop-hands" % os.getuid()
+
+
+def read_live(path=None, ring_path=None, now_ns=None):
+    """The tracking ft-hands' sides.json, or None if there's none or it's stale (ft-hands
+    rewrites it every 2 s and removes it when it exits). With ring_path, also None when it
+    was written for another ft-camd run than the ring there now."""
+    path = path or os.path.join(run_dir(), "sides.json")
+    try:
+        with open(path) as f:
+            s = json.load(f)
+    except (OSError, ValueError):
+        return None
+    now = time.clock_gettime_ns(time.CLOCK_MONOTONIC) if now_ns is None else now_ns
+    if not isinstance(s, dict) or (now - int(s.get("updated_ns", 0))) / 1e9 > LIVE_FRESH_S:
+        return None
+    if ring_path:
+        try:
+            if os.stat(ring_path).st_ino != s.get("ring_ino"):
+                return None
+        except OSError:
+            return None
+    return s
diff --git a/hands/rec/takes.py b/hands/rec/takes.py
new file mode 100755
index 0000000..eeffe95
--- /dev/null
+++ b/hands/rec/takes.py
@@ -0,0 +1,647 @@
+#!/usr/bin/env python3
+"""The hand recorder's sessions and takes on disk: listing, review, deleting, export.
+
+Standard library only (no Qt, no NumPy), so the window and the command line share it.
+The layout is hands/rec/DESIGN.md's "Files":
+  BASE/profile.json
+  BASE/sessions/<YYYYMMDD-HHMMSS>/session.json, calibration.json
+  BASE/sessions/<id>/takes/<NN>-<section>/sets.bin (sets-2.bin, ... after pauses),
+                                          prompts.jsonl, poses.jsonl, take.json
+  BASE/exports/<session>/
+A take's recording is one or more FHSET01 files (hands/track/record.h): per set a header
+(magic, ncams, bytes), one fh_set_cam_t per camera, then each camera's 8-bit pixels.
+Deleted ranges live in take.json ("deleted": [[from_ns, to_ns], ...], CLOCK_MONOTONIC, the
+clock of dqbuf_ns); the files keep every set until export leaves them out.
+
+Side cameras (sides.py): a part recorded before the live tracker decided which side camera is
+which may carry slam_left's and slam_right's names the wrong way round. TakeIndex renames them as
+it reads (session.json "sides" against take.json "parts"), so review and export see the right
+names, and export writes them so: an export's files are always named right, its take.json says
+"parts": {"sets.bin": {"names_swapped": <the session's swapped>}}, and its manifest has each
+take's "sides". `takes.py sides SESSION` shows the decision; --set swapped|named records one by
+hand (e.g. from tools/check_sides.py on a session no live tracker decided).
+
+usage: takes.py [--base DIR] list | takes SESSION | export SESSION | sides SESSION [--set swapped|named]
+"""
+import argparse
+import datetime
+import hashlib
+import json
+import os
+import re
+import shutil
+import struct
+import subprocess
+import sys
+import threading
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import sides  # noqa: E402  (hands/rec/sides.py, next to this file)
+
+DEFAULT_BASE = os.path.expanduser("~/.local/share/frametop/hands/contrib")
+REPO = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+MAGIC = b"FHSET01"
+HDR = struct.Struct("<8sII")       # fh_set_hdr_t: magic, ncams, bytes (the whole record)
+CAM = struct.Struct("<16sIIQQ")    # fh_set_cam_t: name, width, height, capture_ns, dqbuf_ns
+MAX_CAMS = 16                      # SetReader's limit
+PART_RE = re.compile(r"^sets(?:-(\d+))?\.bin$")
+SESSION_RE = re.compile(r"^\d{8}-\d{6}(?:-\d+)?$")   # session.py adds -2, -3 to a second one in a second
+EXPORT_SCHEMA = 1
+# zstd as DESIGN.md has it: level 10, two threads, at the lowest CPU priority (CPU work while
+# someone is in VR makes the headset stutter).
+ZSTD_ARGS = ["-10", "-T2", "-q", "-c"]
+ZSTD_PATHS = ("/usr/bin/zstd", "/usr/local/bin/zstd", "/run/host/usr/bin/zstd")
+CHUNK = 1 << 20
+
+
+class Cancelled(Exception):
+    pass
+
+
+def read_json(path, default=None):
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (OSError, ValueError):
+        return {} if default is None else default
+
+
+def write_json(path, obj):
+    """Write through a temporary file, so a crash never leaves half a file."""
+    tmp = path + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump(obj, f, indent=2)
+        f.write("\n")
+    os.replace(tmp, path)
+
+
+def find_zstd():
+    """The zstd binary, or None. The dev container gets it from setup/dev-container.sh."""
+    found = shutil.which("zstd")
+    if found:
+        return found
+    return next((p for p in ZSTD_PATHS if os.access(p, os.X_OK)), None)
+
+
+def tool_version():
+    """ft-handrec plus the checkout's git describe, for session.json and the manifest."""
+    try:
+        out = subprocess.run(["git", "-C", REPO, "describe", "--always", "--dirty", "--tags"],
+                             capture_output=True, text=True, timeout=5)
+        described = out.stdout.strip()
+    except (OSError, subprocess.TimeoutExpired):
+        described = ""
+    return "ft-handrec " + (described or "unknown")
+
+
+def free_bytes(path):
+    """Free space on the file system that holds path (or its nearest existing parent)."""
+    while path and not os.path.exists(path):
+        path = os.path.dirname(path)
+    try:
+        return shutil.disk_usage(path or "/").free
+    except OSError:
+        return 0
+
+
+def tree_stat(path):
+    """(bytes, newest mtime) of the files under path."""
+    total, newest = 0, 0.0
+    for root, _, files in os.walk(path):
+        for name in files:
+            try:
+                st = os.lstat(os.path.join(root, name))
+            except OSError:
+                continue
+            total += st.st_size
+            newest = max(newest, st.st_mtime)
+    return total, newest
+
+
+def tree_bytes(path):
+    return tree_stat(path)[0]
+
+
+def in_ranges(t, ranges):
+    return any(a <= t <= b for a, b in ranges)
+
+
+def export_jsonl(src, dst, ranges, keep_controllers):
+    """Copy a take's poses.jsonl or prompts.jsonl for export:
+    - poses in the deleted ranges are left out, and the live tracker's feedback there (the
+      prompt timeline stays: it says what was asked, and shows nothing);
+    - without controllers (the checklist's "none"), the controllers' poses are null and feedback
+      carries no controller state: controllers lying about still get logged, and those poses
+      would read as hands' ground truth.
+    Lines that don't parse are copied as they are (validate.py reports them)."""
+    poses = os.path.basename(src) == "poses.jsonl"
+    with open(src, encoding="utf-8") as f, open(dst, "w", encoding="utf-8", newline="\n") as out:
+        for line in f:
+            try:
+                obj = json.loads(line)
+            except ValueError:
+                out.write(line)
+                continue
+            if not isinstance(obj, dict):
+                out.write(line)
+                continue
+            t = obj.get("t")
+            gone = isinstance(t, int) and in_ranges(t, ranges)
+            if poses:
+                if gone:
+                    continue
+                if not keep_controllers:
+                    obj["left"] = obj["right"] = None
+            elif obj.get("event") == "feedback":
+                if gone:
+                    continue
+                if not keep_controllers:
+                    obj.pop("controller", None)
+            out.write(json.dumps(obj, separators=(", ", ": ")) + "\n")
+
+
+def merge_ranges(ranges):
+    """Sorted, with overlapping or touching ranges joined."""
+    out = []
+    for a, b in sorted((min(a, b), max(a, b)) for a, b in ranges):
+        if out and a <= out[-1][1] + 1:
+            out[-1][1] = max(out[-1][1], b)
+        else:
+            out.append([a, b])
+    return out
+
+
+# ---------------------------------------------------------------- one take's recording
+
+class TakeIndex:
+    """Where each set of a take's recording is, without reading pixels. Sets are numbered
+    across the parts (sets.bin, sets-2.bin, ...) in order."""
+
+    def __init__(self, take_dir):
+        self.dir = take_dir
+        self.parts = self._parts(take_dir)
+        self.sets = []   # (part, offset, bytes, time_ns): time_ns is the cameras' earliest dqbuf_ns
+        self.part_starts = []   # index of each part's first set
+        self.cams = []   # the first set's [{name, width, height}], side cameras named right
+        # per part: are its side cameras named the wrong way round (sides.py)? read_set and
+        # read_raw rename them.
+        session = read_json(os.path.join(os.path.dirname(os.path.dirname(take_dir)), "session.json"))
+        take = read_json(os.path.join(take_dir, "take.json"))
+        self.swapped = sides.session_sides(session).get("swapped")
+        self.names_swapped = [sides.part_names_swapped(take, os.path.basename(p)) for p in self.parts]
+        self.rename = [sides.needs_rename(self.swapped, n) for n in self.names_swapped]
+        for p, path in enumerate(self.parts):
+            self.part_starts.append(len(self.sets))
+            self._index(p, path)
+
+    @staticmethod
+    def _parts(take_dir):
+        found = []
+        try:
+            names = os.listdir(take_dir)
+        except OSError:
+            return []
+        for name in names:
+            m = PART_RE.match(name)
+            if m:
+                found.append((int(m.group(1) or 1), os.path.join(take_dir, name)))
+        return [path for _, path in sorted(found)]
+
+    def _index(self, p, path):
+        try:
+            size = os.path.getsize(path)
+            f = open(path, "rb")
+        except OSError:
+            return
+        with f:
+            off = 0
+            while off + HDR.size <= size:
+                f.seek(off)
+                head = f.read(HDR.size)
+                if len(head) < HDR.size:
+                    break
+                magic, ncams, nbytes = HDR.unpack(head)
+                # A truncated last set (the recorder was killed mid-write) ends the part.
+                if magic[:7] != MAGIC or not 0 < ncams <= MAX_CAMS or nbytes < HDR.size or off + nbytes > size:
+                    break
+                cams = f.read(CAM.size * ncams)
+                if len(cams) < CAM.size * ncams:
+                    break
+                fields = [CAM.unpack_from(cams, i * CAM.size) for i in range(ncams)]
+                if not self.cams:
+                    self.cams = [{"name": self._name(p, n), "width": w, "height": h} for n, w, h, _, _ in fields]
+                self.sets.append((p, off, nbytes, min(c[4] for c in fields)))
+                off += nbytes
+
+    def _name(self, p, raw):
+        name = raw.split(b"\0", 1)[0].decode(errors="replace")
+        return sides.other_name(name) if self.rename[p] else name
+
+    def renamed_sets(self, keep=None):
+        """How many of the sets (all, or the indices in keep) read renamed."""
+        return sum(1 for i in (range(len(self.sets)) if keep is None else keep) if self.rename[self.sets[i][0]])
+
+    def __len__(self):
+        return len(self.sets)
+
+    def time_ns(self, i):
+        return self.sets[i][3]
+
+    def duration_s(self):
+        """Recorded time: each part's first to last set, so pauses don't count."""
+        total = 0
+        ends = self.part_starts[1:] + [len(self.sets)]
+        for start, end in zip(self.part_starts, ends):
+            if end > start:
+                total += self.sets[end - 1][3] - self.sets[start][3]
+        return total / 1e9
+
+    def bytes(self):
+        return sum(s[2] for s in self.sets)
+
+    def read_set(self, i, only=None):
+        """Set i's cameras: [{name, width, height, capture_ns, dqbuf_ns, pixels}], pixels as raw
+        8-bit grey bytes (width x height, packed). only: a camera name, to read just that one."""
+        p, off, nbytes, _ = self.sets[i]
+        with open(self.parts[p], "rb") as f:
+            f.seek(off)
+            ncams = HDR.unpack(f.read(HDR.size))[1]
+            heads = f.read(CAM.size * ncams)
+            out = []
+            px_off = off + HDR.size + CAM.size * ncams
+            for k in range(ncams):
+                name, w, h, capture_ns, dqbuf_ns = CAM.unpack_from(heads, k * CAM.size)
+                name = self._name(p, name)
+                if only is None or name == only:
+                    f.seek(px_off)
+                    out.append({"name": name, "width": w, "height": h, "capture_ns": capture_ns,
+                                "dqbuf_ns": dqbuf_ns, "pixels": f.read(w * h)})
+                px_off += w * h
+            return out
+
+    def read_raw(self, i):
+        """Set i's whole record, as it is in the file but with the side cameras named right."""
+        p, off, nbytes, _ = self.sets[i]
+        with open(self.parts[p], "rb") as f:
+            f.seek(off)
+            record = f.read(nbytes)
+        return sides.rename_record(record) if self.rename[p] else record
+
+
+_index_cache = {}
+_index_lock = threading.Lock()
+
+
+def take_index(take_dir):
+    """A TakeIndex, cached until one of the take's recording files, its take.json or its
+    session.json (the side cameras' decision) changes size or time."""
+    key_parts = []
+    meta = [os.path.join(take_dir, "take.json"), os.path.join(os.path.dirname(os.path.dirname(take_dir)), "session.json")]
+    for path in TakeIndex._parts(take_dir) + meta:
+        try:
+            st = os.stat(path)
+            key_parts.append((path, st.st_size, st.st_mtime_ns))
+        except OSError:
+            pass
+    key = tuple(key_parts)
+    with _index_lock:
+        cached = _index_cache.get(take_dir)
+        if cached and cached[0] == key:
+            return cached[1]
+    index = TakeIndex(take_dir)
+    with _index_lock:
+        _index_cache[take_dir] = (key, index)
+    return index
+
+
+# ---------------------------------------------------------------- the store
+
+class Store:
+    def __init__(self, base=DEFAULT_BASE):
+        self.base = os.path.abspath(os.path.expanduser(base))
+        self.sessions_dir = os.path.join(self.base, "sessions")
+        self.exports_dir = os.path.join(self.base, "exports")
+        self.profile_path = os.path.join(self.base, "profile.json")
+
+    # --- paths, checked: ids come from the window, so nothing may climb out of the base
+    def session_dir(self, session):
+        if not SESSION_RE.match(session or ""):
+            raise ValueError(f"not a session id: {session!r}")
+        return os.path.join(self.sessions_dir, session)
+
+    def take_dir(self, session, take):
+        if not take or "/" in take or take.startswith("."):
+            raise ValueError(f"not a take id: {take!r}")
+        return os.path.join(self.session_dir(session), "takes", take)
+
+    def export_dir(self, session):
+        self.session_dir(session)  # checks the id
+        return os.path.join(self.exports_dir, session)
+
+    def profile(self):
+        return read_json(self.profile_path)
+
+    # --- listing
+    def sessions(self):
+        """Newest first: [{id, started, takes, bytes, lighting, status, dry_run, contributor, exported,
+        export_stale (changed since), export_bytes}]."""
+        out = []
+        try:
+            names = os.listdir(self.sessions_dir)
+        except OSError:
+            return out
+        for sid in names:
+            path = os.path.join(self.sessions_dir, sid)
+            if not SESSION_RE.match(sid) or not os.path.isdir(path):
+                continue
+            meta = read_json(os.path.join(path, "session.json"))
+            size, changed = tree_stat(path)
+            manifest = os.path.join(self.export_dir(sid), "manifest.json")
+            exported = os.path.getmtime(manifest) if os.path.isfile(manifest) else 0.0
+            out.append({"id": sid, "started": meta.get("started", ""), "takes": len(self.take_ids(sid)),
+                        "bytes": size, "contributor": meta.get("contributor", ""),
+                        "lighting": (meta.get("lighting") or {}).get("chosen", ""),
+                        "status": meta.get("status", ""), "dry_run": bool(meta.get("dry_run")),
+                        "exported": bool(exported), "export_stale": bool(exported) and changed > exported,
+                        "export_bytes": tree_bytes(self.export_dir(sid)) if exported else 0})
+        return sorted(out, key=lambda s: s["id"], reverse=True)
+
+    def take_ids(self, session):
+        try:
+            names = os.listdir(os.path.join(self.session_dir(session), "takes"))
+        except OSError:
+            return []
+        return sorted(n for n in names if not n.startswith(".")
+                      and os.path.isdir(os.path.join(self.session_dir(session), "takes", n)))
+
+    def takes(self, session):
+        """[{id, section, title, status, sets, deleted_sets, ranges, duration_s, bytes, cams}]."""
+        out = []
+        for tid in self.take_ids(session):
+            path = self.take_dir(session, tid)
+            meta = read_json(os.path.join(path, "take.json"))
+            index = take_index(path)
+            ranges = merge_ranges(meta.get("deleted") or [])
+            out.append({"id": tid, "section": meta.get("section", tid.split("-", 1)[-1]),
+                        "title": meta.get("title") or tid, "status": meta.get("status", "recording"),
+                        "sets": len(index), "parts": len(index.parts),
+                        "deleted_sets": sum(1 for s in index.sets if in_ranges(s[3], ranges)),
+                        "ranges": ranges, "duration_s": index.duration_s(), "bytes": index.bytes(),
+                        "cams": [c["name"] for c in index.cams]})
+        return out
+
+    def take_meta(self, session, take):
+        return read_json(os.path.join(self.take_dir(session, take), "take.json"))
+
+    # --- deleted ranges
+    def ranges(self, session, take):
+        return merge_ranges(self.take_meta(session, take).get("deleted") or [])
+
+    def _set_ranges(self, session, take, ranges):
+        path = os.path.join(self.take_dir(session, take), "take.json")
+        meta = read_json(path)
+        meta["deleted"] = merge_ranges(ranges)
+        write_json(path, meta)
+        return meta["deleted"]
+
+    def delete_range(self, session, take, from_ns, to_ns):
+        """Leave sets from from_ns to to_ns (dqbuf_ns, inclusive) out of the export."""
+        return self._set_ranges(session, take, self.ranges(session, take) + [[int(from_ns), int(to_ns)]])
+
+    def restore_range(self, session, take, i):
+        """Take deleted range i (in ranges()' order) back."""
+        ranges = self.ranges(session, take)
+        if 0 <= i < len(ranges):
+            del ranges[i]
+        return self._set_ranges(session, take, ranges)
+
+    # --- deleting files
+    def delete_take(self, session, take):
+        path = self.take_dir(session, take)
+        if os.path.isdir(path):
+            shutil.rmtree(path)
+        meta_path = os.path.join(self.session_dir(session), "session.json")
+        meta = read_json(meta_path)
+        if take in (meta.get("takes") or []):
+            meta["takes"] = [t for t in meta["takes"] if t != take]
+            meta.setdefault("deleted_takes", []).append(take)
+            write_json(meta_path, meta)
+
+    def delete_session(self, session):
+        """The session and its export, if any."""
+        for path in (self.session_dir(session), self.export_dir(session)):
+            if os.path.isdir(path):
+                shutil.rmtree(path)
+
+    def delete_export(self, session):
+        path = self.export_dir(session)
+        if os.path.isdir(path):
+            shutil.rmtree(path)
+
+    # --- export
+    def sides(self, session, swapped=None):
+        """session.json's side camera decision (sides.py) plus each take's parts; with swapped
+        (True/False), record that by hand first ("decided_by": "manual"). No set is rewritten:
+        reading and export rename."""
+        path = os.path.join(self.session_dir(session), "session.json")
+        meta = read_json(path)
+        if not meta:
+            raise RuntimeError(f"no session {session}")
+        if swapped is not None:
+            old = sides.session_sides(meta)
+            new = {"swapped": bool(swapped), "decided_by": "manual",
+                   "decided_at": datetime.datetime.now().astimezone().isoformat(timespec="seconds")}
+            if old.get("swapped") is not None:
+                new["replaced"] = old
+            meta["sides"] = new
+            write_json(path, meta)
+        out = {"sides": sides.session_sides(meta), "takes": {}}
+        for tid in self.take_ids(session):
+            index = take_index(self.take_dir(session, tid))
+            out["takes"][tid] = {os.path.basename(p): {"names_swapped": n, "renamed_when_read": r}
+                                 for p, n, r in zip(index.parts, index.names_swapped, index.rename)}
+        return out
+
+    def export(self, session, progress=None, cancel=None, keep_notes=False, low_priority=True):
+        """Write exports/<session>/ (DESIGN.md "Export"): manifest.json, calibration.json, per
+        take prompts.jsonl, poses.jsonl, take.json and sets.bin.zst (sets in deleted ranges
+        left out), then SHA256SUMS. progress(fraction 0..1, text) is called as it goes;
+        cancel() (or cancel.is_set()) returning true stops it, raising Cancelled. Nothing is
+        left behind on failure or cancel. Returns the export's path.
+        low_priority: run this thread at nice 19 as well as zstd (Linux nice is per thread)."""
+        zstd = find_zstd()
+        if not zstd:
+            raise RuntimeError("zstd isn't installed (in the dev container: sudo dnf install zstd)")
+        cancelled = getattr(cancel, "is_set", cancel) or (lambda: False)
+        report = progress or (lambda fraction, text: None)
+        src = self.session_dir(session)
+        if not os.path.isdir(src):
+            raise RuntimeError(f"no session {session}")
+        if low_priority:
+            try:
+                os.setpriority(os.PRIO_PROCESS, threading.get_native_id(), 19)
+            except OSError:
+                pass
+        final = self.export_dir(session)
+        work = final + ".partial"
+        if os.path.isdir(work):
+            shutil.rmtree(work)
+        os.makedirs(work)
+        try:
+            self._export(session, src, work, zstd, report, cancelled, keep_notes)
+            if os.path.isdir(final):
+                shutil.rmtree(final)
+            os.replace(work, final)
+        except BaseException:
+            shutil.rmtree(work, ignore_errors=True)
+            raise
+        report(1.0, "Done")
+        return final
+
+    def _export(self, session, src, work, zstd, report, cancelled, keep_notes):
+        profile = self.profile()
+        meta = read_json(os.path.join(src, "session.json"))
+        meta.pop("uploads", None)   # earlier uploads' records (hub.py) aren't part of the contribution
+        takes = self.takes(session)
+        total = sum(t["bytes"] for t in takes) or 1
+        done = 0
+        take_entries = []
+        keep_controllers = (meta.get("checklist") or {}).get("controllers") == "straps"
+        for t in takes:
+            if cancelled():
+                raise Cancelled()
+            tdir = self.take_dir(session, t["id"])
+            out = os.path.join(work, "takes", t["id"])
+            os.makedirs(out)
+            ranges = t["ranges"]
+            for name in ("prompts.jsonl", "poses.jsonl"):
+                if os.path.isfile(os.path.join(tdir, name)):
+                    export_jsonl(os.path.join(tdir, name), os.path.join(out, name), ranges, keep_controllers)
+            index = take_index(tdir)
+            keep = [i for i in range(len(index)) if not in_ranges(index.time_ns(i), ranges)]
+            # one file, named right where the decision is known (sides.py): its names_swapped is
+            # then the session's swapped; unknown, it's the parts' own (None if they differ)
+            if index.swapped is not None:
+                names_swapped = bool(index.swapped)
+            else:
+                names_swapped = index.names_swapped[0] if len(set(index.names_swapped)) == 1 else None
+            take_meta = read_json(os.path.join(tdir, "take.json"))
+            if take_meta:
+                take_meta["parts"] = {"sets.bin": {"names_swapped": names_swapped}}
+                write_json(os.path.join(out, "take.json"), take_meta)
+            entry = {"id": t["id"], "section": t["section"], "title": t["title"], "status": t["status"],
+                     "sets": len(keep), "sets_deleted": len(index) - len(keep), "cameras": index.cams,
+                     "duration_s": round(t["duration_s"], 2), "file": None,
+                     "sides": {"names_swapped": names_swapped, "renamed_sets": index.renamed_sets(keep)}}
+            done += index.bytes() - sum(index.sets[i][2] for i in keep)   # deleted sets count as done
+            if keep:
+                entry["file"] = "takes/%s/sets.bin.zst" % t["id"]
+
+                def step(nbytes, title=t["title"]):
+                    nonlocal done
+                    done += nbytes
+                    report(min(done / total, 0.99), f"Compressing {title}")
+                entry["raw_bytes"] = self._compress(index, keep, zstd, os.path.join(out, "sets.bin.zst"),
+                                                    step, cancelled)
+            take_entries.append(entry)
+        if cancelled():
+            raise Cancelled()
+        for name in ("calibration.json", "device.json"):
+            if os.path.isfile(os.path.join(src, name)):
+                shutil.copyfile(os.path.join(src, name), os.path.join(work, name))
+        shown_profile = json.loads(json.dumps(profile))
+        if not keep_notes and isinstance(shown_profile.get("optional"), dict):
+            shown_profile["optional"].pop("notes", None)
+        manifest = {"schema": EXPORT_SCHEMA, "tool": tool_version(),
+                    "exported": datetime.datetime.now().astimezone().isoformat(timespec="seconds"),
+                    "session_id": session, "contributor": profile.get("contributor", meta.get("contributor", "")),
+                    "consent_version": (profile.get("consent") or {}).get("version", ""),
+                    "profile": shown_profile, "session": meta, "takes": take_entries}
+        write_json(os.path.join(work, "manifest.json"), manifest)
+        report(0.995, "Writing checksums")
+        sums = []
+        for root, _, files in os.walk(work):
+            for name in files:
+                path = os.path.join(root, name)
+                sums.append((os.path.relpath(path, work), sha256_file(path, cancelled)))
+        with open(os.path.join(work, "SHA256SUMS"), "w") as f:
+            for rel, digest in sorted(sums):
+                f.write(f"{digest}  {rel}\n")
+
+    @staticmethod
+    def _compress(index, keep, zstd, dest, step, cancelled):
+        """Stream the kept sets through zstd into dest. Returns the uncompressed size."""
+        raw = 0
+        with open(dest, "wb") as out:
+            proc = subprocess.Popen(["nice", "-n", "19", zstd] + ZSTD_ARGS, stdin=subprocess.PIPE, stdout=out,
+                                    stderr=subprocess.PIPE)
+            try:
+                for i in keep:
+                    if cancelled():
+                        raise Cancelled()
+                    record = index.read_raw(i)
+                    proc.stdin.write(record)
+                    raw += len(record)
+                    step(len(record))
+                proc.stdin.close()
+                err = proc.stderr.read().decode(errors="replace").strip()
+                if proc.wait() != 0:
+                    raise RuntimeError(f"zstd failed: {err or proc.returncode}")
+            except BaseException:
+                proc.kill()
+                proc.wait()
+                raise
+            finally:
+                proc.stderr.close()
+        return raw
+
+
+def sha256_file(path, cancelled=lambda: False):
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while chunk := f.read(CHUNK):
+            if cancelled():
+                raise Cancelled()
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def human_bytes(n):
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1000 or unit == "GB":
+            return f"{n:.0f} {unit}" if unit == "B" else f"{n:.1f} {unit}"
+        n /= 1000
+    return f"{n:.1f} TB"
+
+
+def main():
+    ap = argparse.ArgumentParser(description="List, check and export hand recorder sessions.")
+    ap.add_argument("--base", default=DEFAULT_BASE)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("list")
+    sub.add_parser("takes").add_argument("session")
+    sub.add_parser("export").add_argument("session")
+    sp = sub.add_parser("sides", help="show (or record) which way round the side cameras were")
+    sp.add_argument("session")
+    sp.add_argument("--set", choices=("swapped", "named"),
+                    help="record the decision by hand (e.g. from tools/check_sides.py on a take)")
+    a = ap.parse_args()
+    store = Store(a.base)
+    if a.cmd == "list":
+        for s in store.sessions():
+            print(f"{s['id']}  {s['takes']} takes  {human_bytes(s['bytes'])}  {s['lighting'] or '-'}"
+                  + ("  exported" if s["exported"] else ""))
+    elif a.cmd == "takes":
+        for t in store.takes(a.session):
+            print(f"{t['id']}  {t['status']}  {t['sets']} sets ({t['deleted_sets']} deleted)  "
+                  f"{t['duration_s']:.1f} s  {human_bytes(t['bytes'])}")
+    elif a.cmd == "sides":
+        print(json.dumps(store.sides(a.session, None if a.set is None else a.set == "swapped"), indent=1))
+    else:
+        path = store.export(a.session, progress=lambda f, text: print(f"\r{f * 100:5.1f}% {text:40.40}", end="",
+                                                                       flush=True))
+        print(f"\n{path}  {human_bytes(tree_bytes(path))}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/hands/rec/tests/test_nohands.py b/hands/rec/tests/test_nohands.py
new file mode 100644
index 0000000..93a409c
--- /dev/null
+++ b/hands/rec/tests/test_nohands.py
@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""Tests for the session's camera check: the preflight that keeps a session from starting
+with the upper cameras off, and the early no-hands stop in the hand-size section's first step
+(dry runs with a made-up hands file; no processes, no real cameras).
+
+  python3 hands/rec/tests/test_nohands.py
+"""
+import json
+import os
+import sys
+import threading
+import unittest
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.dirname(HERE))
+sys.path.insert(0, HERE)
+import session  # noqa: E402
+import camcheck  # noqa: E402  (session.py put hands/ on the path)
+from test_session import SessionBase  # noqa: E402
+
+SCRIPT = {
+    "version": 1, "intro_s": 1, "between_s": 1,
+    "welcome": {"title": "Test", "seconds": 1, "text": "A test."},
+    "done": {"title": "Done", "seconds": 0, "text": "Done."},
+    "stopped": {"title": "Stopped", "seconds": 0, "text": "Stopped."},
+    "sections": [
+        {"id": "hand-size", "title": "Hand size", "intro": "Hand size.", "go": "Hold",
+         "defaults": {"hands": "both"},
+         "prompts": [{"text": "Both hands flat.", "seconds": 6, "pose": "flat"},
+                     {"text": "Backs.", "seconds": 2, "pose": "flat-back"}]}]}
+
+HAND = {"palm": [0.0, 0.0, -0.4], "palm_m": 0.4, "tip": [0.0, 0.05, -0.45]}
+DEGRADED = {"status": "degraded", "reason": camcheck.VCINT_REASON, "summary": camcheck.DEGRADED_VCINT,
+            "evidence": ["17:02:47 Failed to load VCINT FPGA image when passthrough cameras are connected"]}
+OK = {"status": "ok", "reason": "4 tracking cameras running", "summary": "ok", "evidence": []}
+
+
+class FakeHands:
+    """Stands in for the hands file: what read() gives can change mid-session."""
+
+    def __init__(self, value):
+        self.value = value
+        self.lock = threading.Lock()
+
+    def set(self, value):
+        with self.lock:
+            self.value = value
+
+    def read(self):
+        with self.lock:
+            return None if self.value is None else dict(self.value)
+
+
+class NoHandsTest(SessionBase):
+    def setUp(self):
+        super().setUp()
+        with open(self.script, "w") as f:
+            json.dump(SCRIPT, f)
+
+    def events(self, s):
+        with open(os.path.join(s.session_dir, "takes", "01-hand-size", "prompts.jsonl")) as f:
+            # feedback lines (twice a second, as the tracker publishes) aren't what's tested here
+            return [e for e in map(json.loads, f) if e["event"] != "feedback"]
+
+    def run_to_first_hold(self, hands, camera=DEGRADED, **kw):
+        s = self.session(hands_reader=hands, speed=3, **kw)
+        s.camera_check_fn = lambda: camera
+        s.start()
+        self.waiting(s, "starting")
+        s.next_step()
+        self.waiting(s, "intro")
+        s.next_step()
+        self.waiting(s, "ready", "Both hands flat.")
+        s.next_step()
+        return s
+
+    def session_json(self, s):
+        with open(os.path.join(s.session_dir, "session.json")) as f:
+            return json.load(f)
+
+    def log(self, s):
+        with open(os.path.join(s.session_dir, "session.log")) as f:
+            return f.read()
+
+    def test_no_hands_then_redo(self):
+        hands = FakeHands({"left": None, "right": None})   # the tracker publishes, sees nothing
+        s = self.run_to_first_hold(hands)
+        st = self.wait_for(s, lambda st: st["state"] == "nohands" and st["waiting"], "the no-hands stop")
+        self.assertTrue(st["nohands"])
+        self.assertTrue(st["can_redo"])
+        self.assertEqual(st["camera"]["status"], "degraded")
+        self.assertIn(camcheck.USER_TEXT, st["prompt"])
+        self.assertIn("panel: title " + session.NO_HANDS_TITLE, self.panel)
+        hands.set({"left": HAND, "right": HAND})
+        s.next_step()   # try again: straight to the countdown, no second ready wait
+        self.wait_for(s, lambda st: st["state"] == "countdown", "the countdown again")
+        self.waiting(s, "ready", "Backs.")
+        s.next_step()
+        s.join(20)
+        self.assertEqual(s.state, "done")
+        ev = self.events(s)
+        names = [e["event"] for e in ev]
+        self.assertEqual(names, ["take", "ready", "prompt", "wait", "nohands", "redo",
+                                 "ready", "prompt", "wait", "ready", "prompt", "wait", "end"])
+        nohands, redo = ev[4], ev[5]
+        self.assertGreaterEqual(nohands["reads"], session.HANDS_CHECK_MIN_READS)
+        self.assertEqual(redo["from"], ev[1]["t"])   # the failed try gets no labels
+        self.assertTrue(ev[2]["t"] < redo["to"])
+        # the retry wasn't stopped: a hand was seen
+        self.assertRegex(self.log(s), r"hands check hand-size/flat/both: a hand in [1-9][0-9]* of")
+        self.assertNotIn("stop_reason", self.session_json(s))
+
+    def test_no_hands_then_stop(self):
+        s = self.run_to_first_hold(FakeHands({"left": None, "right": None}))
+        self.wait_for(s, lambda st: st["state"] == "nohands" and st["waiting"], "the no-hands stop")
+        s.stop(wait=10)
+        self.assertEqual(s.state, "stopped")
+        sj = self.session_json(s)
+        self.assertIn("no hands were seen", sj["stop_reason"])
+        self.assertIn(camcheck.DEGRADED_VCINT, sj["stop_reason"])
+        self.assertIn(camcheck.USER_TEXT, s._status["prompt"])
+        self.assertIn("camera check: " + camcheck.DEGRADED_VCINT, self.log(s))
+
+    def test_redo_key_and_skip(self):
+        hands = FakeHands({"left": None, "right": None})
+        s = self.run_to_first_hold(hands, camera=OK)
+        st = self.wait_for(s, lambda st: st["state"] == "nohands" and st["waiting"], "the no-hands stop")
+        self.assertIn("The camera check found nothing wrong", st["prompt"])
+        s.redo()   # R is the same as Next there
+        self.wait_for(s, lambda st: st["state"] == "countdown", "the countdown again")
+        self.wait_for(s, lambda st: st["state"] == "nohands" and st["waiting"], "no hands again")
+        s.skip()   # S skips the section; the no-hands note doesn't stick
+        s.join(20)
+        self.assertEqual(s.state, "done")
+        self.assertNotIn("stop_reason", self.session_json(s))
+        self.assertEqual([e["event"] for e in self.events(s)].count("nohands"), 2)
+
+    def test_hand_seen_sometimes(self):
+        hands = FakeHands({"left": None, "right": None})
+        s = self.run_to_first_hold(hands)
+        self.wait_for(s, lambda st: st["state"] == "running", "the hold")
+        hands.set({"left": HAND, "right": None})   # one hand, for part of the hold: fine
+        self.waiting(s, "ready", "Backs.")
+        s.next_step()
+        s.join(20)
+        self.assertEqual(s.state, "done")
+        self.assertNotIn("nohands", [e["event"] for e in self.events(s)])
+
+    def test_no_tracker_cant_tell(self):
+        s = self.run_to_first_hold(FakeHands(None))   # nothing published: can't tell, go on
+        self.waiting(s, "ready", "Backs.")
+        s.next_step()
+        s.join(20)
+        self.assertEqual(s.state, "done")
+        self.assertNotIn("nohands", [e["event"] for e in self.events(s)])
+        self.assertIn("can't tell", self.log(s))
+
+    def test_only_the_first_step(self):
+        hands = FakeHands({"left": HAND, "right": HAND})
+        s = self.run_to_first_hold(hands)
+        self.wait_for(s, lambda st: st["state"] == "running", "the hold")
+        self.waiting(s, "ready", "Backs.")
+        hands.set({"left": None, "right": None})   # gone in step 2: notes, but no stop
+        s.next_step()
+        s.join(20)
+        self.assertEqual(s.state, "done")
+        self.assertNotIn("nohands", [e["event"] for e in self.events(s)])
+
+    def test_auto_mode(self):
+        hands = FakeHands({"left": None, "right": None})
+        s = self.session(hands_reader=hands, speed=3, auto=True)
+        s.camera_check_fn = lambda: DEGRADED
+        s.start()
+        self.wait_for(s, lambda st: st["state"] == "nohands" and st["waiting"], "the no-hands stop")
+        hands.set({"left": HAND, "right": HAND})
+        s.next_step()
+        s.join(20)
+        self.assertEqual(s.state, "done")
+        names = [e["event"] for e in self.events(s)]
+        self.assertEqual(names, ["take", "prompt", "prompt", "pause", "nohands", "redo", "resume", "prompt",
+                                 "prompt", "end"])
+
+
+class PreflightTest(SessionBase):
+    def test_degraded_stops_before_anything(self):
+        s = self.session()
+        s.dry_run = False            # as a real session; the check is the only step run
+        s.camera_check_fn = lambda: DEGRADED
+        self.assertTrue(s._preflight())
+        self.assertEqual(s.state, "error")
+        self.assertEqual(s._status["error"], camcheck.USER_TEXT)
+        self.assertEqual(s.session_dir, "")   # no session folder made
+        self.assertFalse(os.path.exists(os.path.join(self.tmp, "base", "sessions")))
+
+    def test_other_degraded_text(self):
+        r = dict(DEGRADED, reason="only 3 of 4 tracking cameras running")
+        self.assertIn("only 3 of 4", session.camera_text(r))
+        self.assertEqual(session.camera_text(OK), "")
+        self.assertEqual(session.camera_text({"status": "unknown"}), "")
+        self.assertEqual(session.camera_text(None), "")
+
+    def test_ok_unknown_ignored(self):
+        for result in (OK, {"status": "unknown", "summary": "unknown: x", "evidence": []}):
+            s = self.session()
+            s.dry_run = False
+            s.camera_check_fn = lambda: result
+            self.assertFalse(s._preflight())
+        s = self.session(check_cameras=False)
+        s.dry_run = False
+        s.camera_check_fn = lambda: DEGRADED
+        self.assertFalse(s._preflight())   # --ignore-cameras
+        s = self.session(ring="/tmp/some-ring")
+        s.dry_run = False
+        s.camera_check_fn = lambda: DEGRADED
+        self.assertFalse(s._preflight())   # ft-ringplay's frames: no headset cameras involved
+
+    def test_camera_check_never_raises(self):
+        orig = camcheck.check
+        try:
+            camcheck.check = lambda: 1 / 0
+            r = session.camera_check()
+        finally:
+            camcheck.check = orig
+        self.assertEqual(r["status"], "unknown")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/hands/rec/tests/test_qml_backend.py b/hands/rec/tests/test_qml_backend.py
new file mode 100644
index 0000000..66fab3a
--- /dev/null
+++ b/hands/rec/tests/test_qml_backend.py
@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""main.qml against ft_handrec.Backend: every backend.name(...) the window calls is a slot, and
+every backend.name it reads is a property or a slot. A method that lost its @Slot shows up in
+QML only as "is not a function" when its button is pressed (2026-10-03: Export did nothing).
+Needs PySide6 (the dev container); skipped without it.
+
+  python3 hands/rec/tests/test_qml_backend.py
+"""
+import os
+import re
+import sys
+import unittest
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+REC = os.path.dirname(HERE)
+sys.path.insert(0, REC)
+
+
+class QmlBackendTest(unittest.TestCase):
+    def setUp(self):
+        try:
+            import ft_handrec
+        except ImportError as e:
+            self.skipTest(f"no PySide6: {e}")
+        meta = self.meta = ft_handrec.Backend.staticMetaObject
+        self.slots = {bytes(meta.method(i).name()).decode() for i in range(meta.methodCount())}
+        self.props = {meta.property(i).name() for i in range(meta.propertyCount())}
+        with open(os.path.join(REC, "main.qml")) as f:
+            self.qml = f.read()
+
+    def test_calls_are_slots(self):
+        called = set(re.findall(r"\bbackend\.(\w+)\s*\(", self.qml))
+        self.assertTrue(called)
+        self.assertEqual(sorted(called - self.slots), [], "called from main.qml but not a slot")
+
+    def test_call_arity(self):
+        """Each backend.name(a, b) call passes as many arguments as some slot of that name takes
+        (a decorator left at the old count fails only when the button is pressed)."""
+        arity = {}
+        meta = self.meta
+        for i in range(meta.methodCount()):
+            mm = meta.method(i)
+            arity.setdefault(bytes(mm.name()).decode(), set()).add(mm.parameterCount())
+        bad = []
+        for m in re.finditer(r"\bbackend\.(\w+)\s*\(", self.qml):
+            depth, args, k, seen = 1, 0, m.end(), False
+            while depth and k < len(self.qml):
+                c = self.qml[k]
+                if c in "([{":
+                    depth += 1
+                elif c in ")]}":
+                    depth -= 1
+                elif c == "," and depth == 1:
+                    args += 1
+                elif not c.isspace() and depth >= 1:
+                    seen = True
+                k += 1
+            n = args + 1 if seen else 0
+            if m.group(1) in arity and n not in arity[m.group(1)]:
+                bad.append("%s: %d arguments, slots take %s" % (m.group(1), n, sorted(arity[m.group(1)])))
+        self.assertEqual(bad, [])
+
+    def test_reads_exist(self):
+        read = set(re.findall(r"\bbackend\.(\w+)\b(?!\s*\()", self.qml))
+        self.assertTrue(read)
+        self.assertEqual(sorted(read - self.props - self.slots), [], "read in main.qml but not on Backend")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/hands/rec/tests/test_session.py b/hands/rec/tests/test_session.py
new file mode 100644
index 0000000..037b33d
--- /dev/null
+++ b/hands/rec/tests/test_session.py
@@ -0,0 +1,634 @@
+#!/usr/bin/env python3
+"""Tests for session.py's step mode (dry runs, no processes): the ready, countdown and hold
+timeline in prompts.jsonl, R (redo), the timed flow (--auto), the pose pictures' display rule,
+the length estimates, and a take recorded in many parts through review, export and validate.
+
+  python3 hands/rec/tests/test_session.py
+"""
+import json
+import os
+import shutil
+import sys
+import tempfile
+import struct
+import time
+import unittest
+from unittest import mock
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.dirname(HERE))
+import session  # noqa: E402
+import takes  # noqa: E402
+import validate  # noqa: E402
+from test_validate import fhset, make_session, SESSION  # noqa: E402
+
+SCRIPT = {
+    "version": 1, "intro_s": 1, "between_s": 1,
+    "welcome": {"title": "Test", "seconds": 1, "text": "A test."},
+    "done": {"title": "Done", "seconds": 0, "text": "Done."},
+    "stopped": {"title": "Stopped", "seconds": 0, "text": "Stopped."},
+    "sections": [
+        {"id": "poses", "title": "Poses", "intro": "Some poses.", "go": "Hold",
+         "prompts": [{"text": "Fist.", "seconds": 4, "hands": "left", "pose": "fist", "distance": "near",
+                      "position": "left"},
+                     {"text": "Open.", "seconds": 4, "hands": "both", "pose": "open"}]}]}
+
+
+class SessionBase(unittest.TestCase):
+    """Dry-run sessions of SCRIPT, steered from the test."""
+
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp(prefix="handrec-session-test-")
+        self.script = os.path.join(self.tmp, "script.json")
+        with open(self.script, "w") as f:
+            json.dump(SCRIPT, f)
+        self.panel = []
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def session(self, **kw):
+        kw.setdefault("speed", 10)
+        s = session.Session(os.path.join(self.tmp, "base"), {}, {}, "room", self.script, dry_run=True,
+                            poses_dir=os.path.join(self.tmp, "no-poses"), **kw)
+        s.print = self.panel.append
+        return s
+
+    def wait_for(self, s, pred, what, timeout=10):
+        end = time.monotonic() + timeout
+        while time.monotonic() < end:
+            st = dict(s._status)
+            if pred(st):
+                return st
+            time.sleep(0.005)
+        self.fail("timed out waiting for %s: %s" % (what, s._status))
+
+    def waiting(self, s, state, prompt=None):
+        return self.wait_for(s, lambda st: st["state"] == state and st["waiting"]
+                             and (prompt is None or st["prompt"] == prompt), "%s %s" % (state, prompt or ""))
+
+    def events(self, s):
+        with open(os.path.join(s.session_dir, "takes", "01-poses", "prompts.jsonl")) as f:
+            return [json.loads(line) for line in f]
+
+
+
+class SessionTest(SessionBase):
+    def test_step_flow(self):
+        s = self.session(next_after=0.0)
+        s.start()
+        s.join(20)
+        self.assertEqual(s.state, "done")
+        ev = self.events(s)
+        self.assertEqual([e["event"] for e in ev],
+                         ["take", "ready", "prompt", "wait", "ready", "prompt", "wait", "end"])
+        self.assertEqual(ev[1]["id"], ev[2]["id"])
+        self.assertEqual(ev[1]["seconds"], session.COUNTDOWN_S)
+        self.assertTrue(ev[1]["t"] < ev[2]["t"] < ev[3]["t"] < ev[4]["t"])
+        # the countdown is recorded (3 s at 10x speed), and the hold after it
+        self.assertGreater(ev[2]["t"] - ev[1]["t"], 0.25e9)
+        with open(os.path.join(s.session_dir, "session.json")) as f:
+            self.assertEqual(json.load(f)["mode"], "step")
+        # a clock sample as each part starts (2 steps: 2 parts), for capture_ns (RAW) -> MONOTONIC
+        with open(os.path.join(s.session_dir, "takes", "01-poses", "take.json")) as f:
+            clock = json.load(f)["clock"]
+        self.assertEqual(len(clock), 2)
+        self.assertTrue(all(len(c) == 2 and all(isinstance(v, int) for v in c) for c in clock))
+        self.assertLess(clock[0][0], clock[1][0])
+        # the panel: Ready?, then the countdown, then the section's word for the hold, the diagram
+        self.assertIn("panel: action " + session.READY_TEXT, self.panel)
+        self.assertLess(self.panel.index("panel: big 3"), self.panel.index("panel: big 1"))
+        self.assertIn("panel: big Hold", self.panel)
+        self.assertIn("panel: where left near", self.panel)
+        self.assertIn("panel: rec on", self.panel)
+
+    def test_redo(self):
+        s = self.session()
+        s.start()
+        self.waiting(s, "starting")
+        s.next_step()
+        self.waiting(s, "intro")
+        s.redo()   # nothing to do again yet: dropped
+        s.next_step()
+        st = self.waiting(s, "ready", "Fist.")
+        self.assertFalse(st["can_redo"])
+        s.next_step()
+        self.wait_for(s, lambda st: st["state"] == "running", "the hold")
+        s.redo()   # during the hold: it starts again
+        self.waiting(s, "ready", "Fist.")
+        s.next_step()
+        st = self.waiting(s, "ready", "Open.")
+        self.assertTrue(st["can_redo"])
+        s.redo()   # at the next step's ready screen: the one before goes again
+        self.waiting(s, "ready", "Fist.")
+        s.next_step()
+        self.waiting(s, "ready", "Open.")
+        s.next_step()
+        s.join(20)
+        self.assertEqual(s.state, "done")
+        ev = self.events(s)
+        names = [e["event"] for e in ev]
+        self.assertEqual(names, ["take", "ready", "prompt", "redo", "wait", "ready", "prompt", "wait", "redo",
+                                 "ready", "prompt", "wait", "ready", "prompt", "wait", "end"])
+        first, second = ev[3], ev[8]
+        self.assertEqual(first["id"], "poses/fist/left/near/left")
+        self.assertEqual(first["from"], ev[1]["t"])          # from its countdown
+        self.assertTrue(ev[2]["t"] < first["to"] <= ev[4]["t"])
+        self.assertEqual((second["from"], second["id"]), (ev[5]["t"], first["id"]))
+        self.assertTrue(ev[6]["t"] < second["to"] <= ev[7]["t"])
+        # what labels keep: prompts outside every redo range
+        kept = [e["id"] for e in ev if e["event"] == "prompt"
+                and not any(r["from"] <= e["t"] <= r["to"] for r in ev if r["event"] == "redo")]
+        self.assertEqual(kept, ["poses/fist/left/near/left", "poses/open/both"])
+
+    def test_pause_while_waiting(self):
+        s = self.session()
+        s.start()
+        self.waiting(s, "starting")
+        s.next_step()
+        self.waiting(s, "intro")
+        s.next_step()
+        self.waiting(s, "ready", "Fist.")
+        s.pause()
+        self.wait_for(s, lambda st: st["state"] == "paused", "paused")
+        s.next_step()   # ignored while paused
+        s.resume()
+        st = self.waiting(s, "ready", "Fist.")
+        s.stop(wait=10)
+        self.assertEqual(s.state, "stopped")
+        # nothing recorded: no take
+        self.assertEqual(os.listdir(os.path.join(s.session_dir, "takes")), [])
+
+    def test_auto(self):
+        s = self.session(auto=True, speed=20)
+        s.start()
+        s.join(20)
+        self.assertEqual(s.state, "done")
+        ev = self.events(s)
+        self.assertEqual([e["event"] for e in ev], ["take", "prompt", "prompt", "prompt", "end"])
+        self.assertEqual(ev[1]["id"], "poses/intro")
+
+    def test_auto_redo_after_pause(self):
+        s = self.session(auto=True)
+        s.start()
+        self.wait_for(s, lambda st: st["state"] == "running" and st["prompt"] == "Fist.", "the first prompt")
+        s.pause()
+        self.wait_for(s, lambda st: st["state"] == "paused", "paused")
+        s.redo()   # ends the pause; the prompt starts again, recording again
+        s.join(20)
+        self.assertEqual(s.state, "done")
+        names = [e["event"] for e in self.events(s)]
+        self.assertEqual(names, ["take", "prompt", "prompt", "pause", "redo", "resume", "prompt", "prompt", "end"])
+
+    def test_pose_view(self):
+        d = os.path.join(self.tmp, "poses")
+        os.makedirs(d)
+        for name in ("fist.png", "cross.png"):
+            open(os.path.join(d, name), "wb").close()
+        with open(os.path.join(d, "poses.json"), "w") as f:
+            json.dump({"fist": {"file": "fist.png", "two_hands": False, "caption": "A fist"},
+                       "cross": {"file": "../cross.png", "two_hands": True, "caption": ""},
+                       "ok": {"file": "ok.png", "two_hands": False}}, f)
+        poses = session.load_poses(d)
+        fist = os.path.join(d, "fist.png")
+        self.assertEqual(session.pose_view(poses, {"pose": "fist", "hands": "right"}), (fist, "", "A fist"))
+        self.assertEqual(session.pose_view(poses, {"pose": "fist", "hands": "left"})[1], "mirror")
+        self.assertEqual(session.pose_view(poses, {"pose": "fist", "hands": "both"})[1], "both")
+        self.assertEqual(session.pose_view(poses, {"pose": "fist", "hands": "any"})[1], "")
+        # two hands drawn already; the file stays in the folder
+        self.assertEqual(session.pose_view(poses, {"pose": "cross", "hands": "both"})[:2],
+                         (os.path.join(d, "cross.png"), ""))
+        self.assertEqual(session.pose_view(poses, {"pose": "ok", "hands": "both"}), ("", "", ""))   # no file
+        self.assertEqual(session.pose_view(poses, {"pose": "claw", "hands": "both"}), ("", "", ""))
+        self.assertEqual(session.load_poses(os.path.join(self.tmp, "none")), {})
+
+    def test_plan(self):
+        plan, _ = session.build_plan(SCRIPT, {})
+        self.assertEqual(session.plan_steps(plan), 2)
+        self.assertEqual(session.plan_seconds(SCRIPT, plan, auto=False), 2 * session.COUNTDOWN_S + 8)
+        self.assertEqual(session.plan_seconds(SCRIPT, plan, auto=True), 1 + 1 + 8)
+        self.assertIn("2 steps", session.plan_summary(SCRIPT, plan))
+
+
+SWEEP_SCRIPT = {
+    "version": 1, "intro_s": 1, "between_s": 1,
+    "welcome": {"title": "Test", "seconds": 1, "text": "A test."},
+    "done": {"title": "Done", "seconds": 0, "text": "Done."},
+    "stopped": {"title": "Stopped", "seconds": 0, "text": "Stopped."},
+    "cue_names": {"thumbs-up": "Thumbs up"},
+    "sections": [
+        {"id": "sweeps", "title": "Poses", "kind": "sweep", "intro": "Keep moving.", "quick": True,
+         "cue_s": 2, "step_s": 6,
+         "groups": [["open", "fist"], ["ok", "thumbs-up", "claw"]],
+         "sweeps": [{"hands": "both", "group": "next", "text": "Both hands."},
+                    {"hands": "left", "group": "any", "quick": False, "text": "Left hand."}]}]}
+
+
+class SweepTest(SessionBase):
+    def setUp(self):
+        super().setUp()
+        with open(self.script, "w") as f:
+            json.dump(SWEEP_SCRIPT, f)
+
+    def events(self, s):
+        with open(os.path.join(s.session_dir, "takes", "01-sweeps", "prompts.jsonl")) as f:
+            return [json.loads(line) for line in f]
+
+    def test_sweep_flow(self):
+        s = self.session(next_after=0.0, speed=10, seed=1)
+        s.start()
+        s.join(20)
+        self.assertEqual(s.state, "done")
+        ev = self.events(s)
+        names = [e["event"] for e in ev]
+        self.assertEqual(names, ["take", "ready", "prompt", "prompt", "prompt", "wait",
+                                 "ready", "prompt", "prompt", "prompt", "wait", "end"])
+        plan = {p["id"]: p["cues"] for p in s.plan[0]["prompts"]}
+        for step, first in (("sweeps/both-1", 2), ("sweeps/left-1", 7)):
+            cues = [e for e in ev[first:first + 3]]
+            self.assertEqual([e["pose"] for e in cues], plan[step])          # one prompt per cue, in order
+            self.assertTrue(all(e["cue"] and e["step"] == step for e in cues))
+            self.assertTrue(all(e["distance"] == e["position"] == "" for e in cues))
+            self.assertEqual(ev[first - 1], dict(ev[first - 1], event="ready", id=step))
+            gaps = [(b["t"] - a["t"]) / 1e9 for a, b in zip(cues, cues[1:])]
+            self.assertTrue(all(0.15 < g < 0.4 for g in gaps), gaps)          # cue_s 2 at 10x speed
+        # a cue repeated within a step (6 s of 2 s cues from a group of 2) gets its own id
+        both = [e["id"] for e in ev[2:5]]
+        self.assertEqual(len(set(both)), 3)
+        # the strip: every picture of the step, the cue lit
+        strips = [c for c in self.panel if c.startswith("panel: strip ")]
+        self.assertIn("panel: strip off", strips)
+        self.assertTrue(any(c.startswith("panel: strip 1 ") for c in strips))
+        with open(os.path.join(s.session_dir, "session.json")) as f:
+            meta = json.load(f)
+        self.assertEqual(meta["shuffle"]["seed"], 1)
+        self.assertEqual({x["id"]: x["cues"] for x in meta["shuffle"]["sweeps"]["sweeps"]}, plan)
+        self.assertFalse(meta["quick"])
+
+    def test_seed_from_session_id(self):
+        s = self.session(next_after=0.0, speed=20)
+        s.start()
+        s.join(20)
+        with open(os.path.join(s.session_dir, "session.json")) as f:
+            meta = json.load(f)
+        sid = os.path.basename(s.session_dir)
+        self.assertEqual(meta["shuffle"]["seed"], session.session_seed(sid))
+        again, _ = session.build_plan(SWEEP_SCRIPT, {}, seed=meta["shuffle"]["seed"])   # reproducible
+        self.assertEqual(session.plan_record(again), meta["shuffle"]["sweeps"])
+
+    def test_quick_session(self):
+        s = self.session(next_after=0.0, speed=20, quick=True)
+        s.start()
+        s.join(20)
+        self.assertEqual(s.state, "done")
+        self.assertEqual([e["event"] for e in self.events(s)].count("ready"), 1)   # the left sweep left out
+        with open(os.path.join(s.session_dir, "session.json")) as f:
+            self.assertTrue(json.load(f)["quick"])
+
+    def test_auto(self):
+        s = self.session(auto=True, speed=20)
+        s.start()
+        s.join(20)
+        self.assertEqual(s.state, "done")
+        names = [e["event"] for e in self.events(s)]
+        self.assertEqual(names, ["take", "prompt"] + ["prompt"] * 6 + ["end"])   # intro, 3 cues a step
+
+
+class ShuffleTest(unittest.TestCase):
+    def setUp(self):
+        self.script = session.load_script(session.SCRIPT_PATH)
+
+    def cues(self, seed, quick=False, checklist=None):
+        plan, _ = session.build_plan(self.script, checklist or {}, seed=seed, quick=quick)
+        return session.plan_record(plan)
+
+    def test_deterministic(self):
+        self.assertEqual(self.cues(42), self.cues(42))
+        self.assertNotEqual(self.cues(42)["pose-sweeps"], self.cues(43)["pose-sweeps"])
+        self.assertEqual(session.session_seed("20261002-202734"), session.session_seed("20261002-202734"))
+        self.assertNotEqual(session.session_seed("20261002-202734"), session.session_seed("20261002-202735"))
+
+    def test_groups(self):
+        groups = [sorted(g) for g in self.script["sections"][1]["groups"]]
+        for seed in range(20):
+            steps = self.cues(seed)["pose-sweeps"]
+            self.assertEqual([x["hands"] for x in steps], ["both", "both", "both", "left", "right"])
+            used = [sorted(set(x["cues"])) for x in steps]
+            self.assertEqual(sorted(used[:3]), sorted(groups))       # each group once with both hands
+            self.assertTrue(all(u in groups for u in used[3:]))
+            self.assertNotEqual(used[3], used[4])                    # the one-hand sweeps differ
+            self.assertTrue(all(len(x["cues"]) == 5 for x in steps))  # 20 s of 4 s cues
+        # unshuffled: the script's order
+        steps = self.cues(None)["pose-sweeps"]
+        self.assertEqual(steps[0]["cues"], ["open", "fist", "point", "pinch", "open"])
+        # gestures and hand size keep their order
+        for seed in (1, 2, 3):
+            self.assertEqual([x["cues"] for x in self.cues(seed)["gestures"]],
+                             [["pinch-tap", "pinch-drag"], ["grab", "cross", "overlap"], ["near-face", "screen-point"]])
+            self.assertEqual(self.cues(seed)["hand-size"][0]["cues"], ["flat", "flat-back", "spread"])
+
+    def test_plans(self):
+        full, skipped = session.build_plan(self.script, {}, seed=5)
+        self.assertEqual([s["id"] for s in full],
+                         ["hand-size", "pose-sweeps", "gestures", "desk-work", "touch", "bare-push", "no-hands"])
+        self.assertEqual(session.plan_steps(full), 15)
+        self.assertLess(session.plan_seconds(self.script, full, auto=False), 6 * 60)
+        everything, _ = session.build_plan(self.script, {"objects": ["pencil", "keyboard", "mouse"],
+                                                         "controllers": "straps"}, seed=5)
+        self.assertEqual(len(everything), 10)
+        quick, skipped = session.build_plan(self.script, {"objects": ["pencil"], "controllers": "straps"},
+                                            seed=5, quick=True)
+        self.assertEqual([s["id"] for s in quick], ["hand-size", "pose-sweeps", "touch", "no-hands"])
+        self.assertEqual([p["hands"] for p in quick[1]["prompts"]], ["both"] * 3)
+        self.assertEqual(len(quick[2]["targets"]), 6)
+        self.assertLess(session.plan_seconds(self.script, quick, auto=False), 150)
+        self.assertIn({"section": "objects", "reason": "not in a quick round"}, skipped)
+        # desk work: the mouse-and-keyboard step only with both ticked
+        desk = [s for s in everything if s["id"] == "desk-work"][0]["prompts"]
+        self.assertEqual([p.get("cues") for p in desk], [None, ["mouse", "switch"]])
+
+
+class StripPanelTest(unittest.TestCase):
+    """The panel's strip command on ft-handpanel --no-vr (skipped if it isn't built)."""
+
+    def test_strip(self):
+        import subprocess
+        binary = session.PANEL_BIN
+        if not os.access(binary, os.X_OK):
+            self.skipTest("ft-handpanel isn't built")
+        name = "hrtest-strip-%d" % os.getpid()
+        proc = subprocess.Popen([binary, "--no-vr", "--socket", name], stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                                text=True)
+        try:
+            panel = session.Panel(name=name)
+            for _ in range(50):
+                if panel.cmd("ping", reply=True, timeout=0.1):
+                    break
+                if proc.poll() is not None:
+                    self.skipTest("ft-handpanel doesn't run here: " + proc.stderr.read().strip()[-200:])
+                time.sleep(0.1)
+            else:
+                self.fail("ft-handpanel --no-vr doesn't answer")
+            poses = session.POSES_DIR
+            ok = panel.cmd("strip 1 %s/fist.png|mirror|Fist;-|-|No picture;%s/ok.png|-|OK" % (poses, poses), reply=True)
+            bad = panel.cmd("strip 1", reply=True)
+            missing = panel.cmd("strip 0 /nonexistent.png|-|Gone", reply=True)
+            panel.cmd("show", reply=True)
+            panel.cmd("strip off", reply=True)
+            panel.close()
+        finally:
+            proc.terminate()
+            out = proc.communicate(timeout=5)[0]
+        self.assertEqual(ok, "ok")
+        self.assertTrue(bad.startswith("error usage: strip"))
+        self.assertTrue(missing.startswith("error can't read"))
+        self.assertIn("strip: cue 0: Gone(/nonexistent.png)", out)
+        self.assertIn("strip: off", out)
+
+
+# /proc/bus/input/devices as the Frame has it (2026-10-02), trimmed, plus a USB mouse.
+DEVICES = """I: Bus=0019 Vendor=0001 Product=0001 Version=0100
+N: Name="gpio-keys"
+P: Phys=gpio-keys/input0
+S: Sysfs=/devices/platform/gpio-keys/input/input3
+U: Uniq=
+H: Handlers=kbd kbd event3 qcom_pon_combo_timer_listener 
+B: PROP=0
+B: EV=3
+B: KEY=100000000000 0 0 0 0 200000000 0 0 0 0 0
+
+I: Bus=0006 Vendor=4d44 Product=0001 Version=0001
+N: Name="frametop virtual mouse"
+P: Phys=
+S: Sysfs=/devices/virtual/input/input4
+U: Uniq=
+H: Handlers=event4 qcom_pon_combo_timer_listener 
+B: PROP=0
+B: EV=7
+B: KEY=ffffff 0 0 0 0
+B: REL=ffff
+
+I: Bus=0003 Vendor=0001 Product=0001 Version=0001
+N: Name="frame-voice keyboard"
+P: Phys=py-evdev-uinput
+S: Sysfs=/devices/virtual/input/input7
+U: Uniq=
+H: Handlers=kbd sysrq kbd event7 qcom_pon_combo_timer_listener 
+B: PROP=0
+B: EV=200003
+B: KEY=1ffffffffffffff ffffffffffffffff ffffffffffffffff fffffffffffffffe
+
+I: Bus=0005 Vendor=214e Product=0035 Version=0001
+N: Name="Z3 Keyboard"
+P: Phys=90:82:c3:5f:4a:a7
+S: Sysfs=/devices/virtual/misc/uhid/0005:214E:0035.0005/input/input27
+U: Uniq=da:ef:2f:d2:be:e2
+H: Handlers=kbd sysrq kbd event9 qcom_pon_combo_timer_listener 
+B: PROP=0
+B: EV=10001f
+B: KEY=300000000000 33eff 0 0 483ffff17aff32d bfd4444600000000 1 130ff38b17c007 ffff7bfad9415fff feb2ffdfffefffff fffffffffffffffe
+B: REL=1040
+B: MSC=10
+"""
+BT_MOUSE = """
+I: Bus=0005 Vendor=214e Product=0035 Version=0001
+N: Name="Z3 Mouse"
+P: Phys=90:82:c3:5f:4a:a7
+S: Sysfs=/devices/virtual/misc/uhid/0005:214E:0035.0005/input/input26
+U: Uniq=da:ef:2f:d2:be:e2
+H: Handlers=event8 qcom_pon_combo_timer_listener 
+B: PROP=0
+B: EV=17
+B: KEY=ffff0000 0 0 0 0
+B: REL=1943
+B: MSC=10
+"""
+USB_MOUSE = """
+I: Bus=0003 Vendor=046d Product=c077 Version=0111
+N: Name="Logitech USB Optical Mouse"
+P: Phys=usb-xhci-hcd.1.auto-1/input0
+S: Sysfs=/devices/platform/soc@0/a600000.usb/xhci-hcd.1.auto/usb1/1-1/1-1:1.0/0003:046D:C077.0001/input/input40
+U: Uniq=
+H: Handlers=mouse0 event13
+B: PROP=0
+B: EV=17
+B: KEY=70000 0 0 0 0
+B: REL=903
+B: MSC=10
+"""
+
+
+def event(etype, code, value):
+    return session.INPUT_EVENT.pack(1, 2, etype, code, value)
+
+
+PRESS = event(session.EV_KEY, session.KEY_SELECT, 1) + event(0, 0, 0)
+RELEASE = event(session.EV_KEY, session.KEY_SELECT, 0) + event(0, 0, 0)
+
+
+class InputTest(unittest.TestCase):
+    def test_devices(self):
+        devs = session.parse_input_devices(DEVICES)
+        self.assertEqual([d["name"] for d in devs], ["gpio-keys", "frametop virtual mouse", "frame-voice keyboard",
+                                                     "Z3 Keyboard"])
+        self.assertEqual(session.find_button(devs), "/dev/input/event3")
+        self.assertFalse(any(session.real_mouse(d) for d in devs))   # the virtual mouse, keyboards with wheels
+        for extra, name in ((BT_MOUSE, "Z3 Mouse"), (USB_MOUSE, "Logitech USB Optical Mouse")):
+            mice = [d["name"] for d in session.parse_input_devices(DEVICES + extra) if session.real_mouse(d)]
+            self.assertEqual(mice, [name])
+        # another gpio-keys without KEY_SELECT isn't the button
+        self.assertIsNone(session.find_button(session.parse_input_devices(DEVICES.replace("200000000", "0"))))
+
+    def test_presses(self):
+        data = (PRESS + event(session.EV_KEY, session.KEY_SELECT, 2) * 3   # autorepeat: not presses
+                + RELEASE + event(session.EV_KEY, 115, 1) + PRESS)        # another key
+        self.assertEqual(session.button_presses(data), (2, b""))
+        n, rest = session.button_presses(PRESS + PRESS[:10])
+        self.assertEqual((n, rest), (1, PRESS[:10]))   # half an event waits for the rest
+        self.assertEqual(session.button_presses(rest + PRESS[10:])[0], 1)
+
+    def test_reader_fifo(self):
+        tmp = tempfile.mkdtemp(prefix="handrec-button-test-")
+        try:
+            fifo = os.path.join(tmp, "button")
+            os.mkfifo(fifo)
+            presses = []
+            reader = session.ButtonReader(fifo, lambda: presses.append(time.monotonic()), debounce_s=0.3).start()
+            with open(fifo, "wb", buffering=0) as w:
+                w.write(PRESS + RELEASE)
+                w.write(PRESS[:7])                       # a press split across writes, a bounce
+                time.sleep(0.05)
+                w.write(PRESS[7:] + RELEASE)
+                time.sleep(0.4)
+                w.write(PRESS + RELEASE)
+                time.sleep(0.2)
+            with open(fifo, "wb", buffering=0) as w:     # the writer comes back: read again
+                time.sleep(0.4)
+                w.write(PRESS)
+                time.sleep(0.3)
+            reader.stop()
+            self.assertEqual(len(presses), 3)
+            self.assertTrue(reader.ok)
+        finally:
+            shutil.rmtree(tmp, ignore_errors=True)
+
+    def test_missing_device(self):
+        logs = []
+        reader = session.ButtonReader("/nonexistent/event99", lambda: None, log=logs.append).start()
+        time.sleep(0.1)
+        reader.stop()
+        self.assertFalse(reader.ok)
+        self.assertIn("can't open", logs[0])
+
+
+class ButtonSessionTest(SessionBase):
+    """A dry run steered with a simulated headset button (a FIFO), with no mouse, then one."""
+
+    def test_button(self):
+        fifo = os.path.join(self.tmp, "button")
+        os.mkfifo(fifo)
+        procfile = os.path.join(self.tmp, "devices")
+        with open(procfile, "w") as f:
+            f.write(DEVICES)
+        writer = os.open(fifo, os.O_RDWR)   # kept open, so the reader never sees the end
+        press = lambda: os.write(writer, PRESS + RELEASE)
+        try:
+            with mock.patch.object(session, "BUTTON_DEBOUNCE_S", 0.0):
+                s = self.session(speed=4, button_device=fifo)
+                s.input_devices = procfile
+                s.start()
+                st = self.waiting(s, "starting")
+                self.assertEqual((st["button"], st["mouse"], st["ready_text"]), (True, False, session.READY_BUTTON))
+                self.assertIn("panel: action " + session.READY_BUTTON, self.panel)
+                self.assertIn("panel: keys " + session.KEYS_STEP_BUTTON, self.panel)
+                press()
+                self.waiting(s, "intro")
+                press()
+                self.waiting(s, "ready", "Fist.")
+                press()                                       # Next
+                self.wait_for(s, lambda st: st["state"] == "running", "the hold")
+                press()                                       # pause
+                self.wait_for(s, lambda st: st["state"] == "paused", "paused")
+                with open(procfile, "a") as f:                # a mouse arrives
+                    f.write(BT_MOUSE)
+                press()                                       # resume
+                st = self.waiting(s, "ready", "Open.")
+                self.assertEqual((st["mouse"], st["ready_text"]), (True, session.READY_BUTTON_MOUSE))
+                press()
+                s.join(20)
+            self.assertEqual(s.state, "done")
+            names = [e["event"] for e in self.events(s)]
+            self.assertEqual(names, ["take", "ready", "prompt", "pause", "resume", "wait", "ready", "prompt", "wait",
+                                     "end"])
+        finally:
+            os.close(writer)
+
+    def test_no_button(self):
+        s = self.session(next_after=0.0, button=False, button_device="/nonexistent")
+        s.start()
+        s.join(20)
+        self.assertEqual(s.state, "done")
+        self.assertIn("panel: action " + session.READY_TEXT, self.panel)
+        self.assertIn("panel: keys " + session.KEYS_STEP, self.panel)
+
+
+class LightingTest(unittest.TestCase):
+    """The measured lighting label: the mono cameras' ambient infrared."""
+
+    def ring(self, slam, upper):
+        return {"slam_left": {"mean": 70.0, "dark_mean": slam}, "slam_right": {"mean": 80.0, "dark_mean": slam},
+                "upper_left": {"mean": 50.0, "dark_mean": upper}, "upper_right": {"mean": 20.0, "dark_mean": upper}}
+
+    def test_indoor_and_daylight(self):
+        self.assertEqual(session.classify_lighting(self.ring(3.0, 0.5)), "indoor")    # one lamp, 2026-10-02
+        self.assertEqual(session.classify_lighting(self.ring(3.7, 0.7)), "indoor")    # a lamp-lit room
+        self.assertEqual(session.classify_lighting(self.ring(20.0, 8.0)), "daylight")
+        self.assertEqual(session.classify_lighting(self.ring(0.0, 0.0)), "")          # no dark frames yet
+        self.assertEqual(session.classify_lighting(None), "")
+        self.assertEqual(session.ambient_ir(self.ring(3.0, 0.5)), 1.75)
+
+    def test_record(self):
+        rec = session.lighting_record("auto", self.ring(3.0, 0.5))
+        self.assertEqual((rec["chosen"], rec["source"], rec["measured"]), ("indoor", "measured", "indoor"))
+        rec = session.lighting_record("dim", self.ring(3.0, 0.5))
+        self.assertEqual((rec["chosen"], rec["source"], rec["measured"]), ("dim", "picked", "indoor"))
+        rec = session.lighting_record("auto", None)
+        self.assertEqual((rec["chosen"], rec["source"], rec["ring"]), ("", "measured", {}))
+
+
+class ManyPartsTest(unittest.TestCase):
+    """A take recorded in 40 parts (step mode stops the recording between steps): review reads
+    them in order, export makes one stream, validate passes."""
+
+    def setUp(self):
+        if not takes.find_zstd():
+            self.skipTest("no zstd")
+        self.tmp = tempfile.mkdtemp(prefix="handrec-parts-test-")
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def test_parts(self):
+        make_session(self.tmp)
+        tdir = os.path.join(self.tmp, "sessions", SESSION, "takes", "01-hand-size")
+        t0 = 5 * 10 ** 12
+        for part in range(1, 41):
+            name = "sets.bin" if part == 1 else "sets-%d.bin" % part
+            with open(os.path.join(tdir, name), "wb") as f:
+                for i in range(3):   # 3 sets a part, 10 s apart between parts
+                    f.write(fhset(t0 + part * 10 ** 10 + i * 10 ** 8, part))
+        store = takes.Store(self.tmp)
+        index = takes.take_index(tdir)
+        self.assertEqual(len(index.parts), 40)
+        self.assertEqual(len(index), 120)
+        times = [index.time_ns(i) for i in range(len(index))]
+        self.assertEqual(times, sorted(times))   # sets-10.bin after sets-9.bin
+        self.assertAlmostEqual(index.duration_s(), 40 * 0.2)   # the gaps between parts don't count
+        path = store.export(SESSION, low_priority=False)
+        r = validate.validate(path)
+        self.assertEqual(r.errors, [])
+        self.assertEqual(r.summary["sets"], 120 + 30)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/hands/rec/tests/test_sides.py b/hands/rec/tests/test_sides.py
new file mode 100644
index 0000000..bd36e8b
--- /dev/null
+++ b/hands/rec/tests/test_sides.py
@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""Tests for the side cameras' naming in recordings (sides.py) and its readers: takes.py's
+review and export, validate.py, and session.py's live decision and recording parts.
+
+  python3 hands/rec/tests/test_sides.py
+"""
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+from unittest import mock
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.dirname(HERE))
+import session  # noqa: E402
+import sides  # noqa: E402
+import takes  # noqa: E402
+import validate  # noqa: E402
+from test_validate import fhset, make_session, SESSION  # noqa: E402
+
+
+def names(record):
+    ncams = sides.HDR.unpack_from(record, 0)[1]
+    return [sides.CAM.unpack_from(record, sides.HDR.size + k * sides.CAM.size)[0].split(b"\0")[0].decode()
+            for k in range(ncams)]
+
+
+class RulesTest(unittest.TestCase):
+    def test_rename_record(self):
+        rec = fhset(10 ** 9, 3)
+        out = sides.rename_record(rec)
+        self.assertEqual(names(rec), ["slam_left", "slam_right"])
+        self.assertEqual(names(out), ["slam_right", "slam_left"])
+        self.assertEqual(len(out), len(rec))
+        head = sides.HDR.size + 2 * sides.CAM.size
+        self.assertEqual(out[head:], rec[head:])   # pixels untouched
+        self.assertEqual(sides.rename_record(out), rec)
+
+    def test_other_name(self):
+        self.assertEqual(sides.other_name("slam_left_dk"), "slam_right_dk")
+        self.assertEqual(sides.other_name("upper_left"), "upper_left")
+
+    def test_needs_rename(self):
+        self.assertTrue(sides.needs_rename(True, False))
+        self.assertFalse(sides.needs_rename(True, True))
+        self.assertTrue(sides.needs_rename(False, True))
+        self.assertFalse(sides.needs_rename(None, True))   # unknown: leave the names
+
+    def test_part_rename(self):
+        sess = {"sides": {"swapped": True}}
+        take = {"parts": {"sets.bin": {"names_swapped": False}, "sets-2.bin": {"names_swapped": True}}}
+        self.assertTrue(sides.part_rename(sess, take, "sets.bin"))
+        self.assertFalse(sides.part_rename(sess, take, "sets-2.bin"))
+        self.assertTrue(sides.part_rename(sess, {}, "sets-3.bin"))   # no record: as ft-camd named them
+        self.assertFalse(sides.part_rename({}, take, "sets.bin"))    # no decision
+
+    def test_recording_runs(self):
+        d = tempfile.mkdtemp()
+        try:
+            self.assertEqual(sides.recording_runs(d), [(0, False)])
+            with open(os.path.join(d, "sides.json"), "w") as f:
+                json.dump({"swapped": True, "decided_by": "auto", "names_swapped": [[0, False], [37, True]]}, f)
+            runs = sides.recording_runs(d)
+            self.assertEqual(runs, [(0, True), (37, False)])
+            self.assertTrue(sides.rename_at(runs, 36))
+            self.assertFalse(sides.rename_at(runs, 37))
+        finally:
+            shutil.rmtree(d)
+
+    def test_read_live(self):
+        d = tempfile.mkdtemp()
+        try:
+            path, ring = os.path.join(d, "sides.json"), os.path.join(d, "cam-ring")
+            open(ring, "w").close()
+            now = time.clock_gettime_ns(time.CLOCK_MONOTONIC)
+            live = {"pid": 1, "ring_ino": os.stat(ring).st_ino, "swapped": True, "decided_by": "auto",
+                    "state": "decided", "updated_ns": now}
+            with open(path, "w") as f:
+                json.dump(live, f)
+            self.assertEqual(sides.read_live(path, ring)["swapped"], True)
+            self.assertIsNone(sides.read_live(path, ring, now_ns=now + 10 * 10 ** 9))   # stale
+            os.remove(ring)
+            open(ring, "w").close()   # a new ft-camd: a new ring file
+            if os.stat(ring).st_ino != live["ring_ino"]:
+                self.assertIsNone(sides.read_live(path, ring))
+            self.assertIsNone(sides.read_live(os.path.join(d, "none.json")))
+        finally:
+            shutil.rmtree(d)
+
+
+class TakesTest(unittest.TestCase):
+    """A swapped session: one take's parts recorded before the decision (ft-camd's names) and
+    after it (named right)."""
+
+    def setUp(self):
+        if not takes.find_zstd():
+            self.skipTest("no zstd")
+        self.tmp = tempfile.mkdtemp(prefix="handrec-sides-test-")
+        make_session(self.tmp)
+        self.sdir = os.path.join(self.tmp, "sessions", SESSION)
+        meta = takes.read_json(os.path.join(self.sdir, "session.json"))
+        meta["sides"] = {"swapped": True, "decided_by": "auto", "state": "confirmed"}
+        takes.write_json(os.path.join(self.sdir, "session.json"), meta)
+        self.tdir = os.path.join(self.sdir, "takes", "01-hand-size")
+        with open(os.path.join(self.tdir, "sets-2.bin"), "wb") as f:   # after the decision: --sides 1
+            for i in range(5):
+                f.write(sides.rename_record(fhset(9 * 10 ** 12 + i * 10 ** 8, i)))
+        tj = takes.read_json(os.path.join(self.tdir, "take.json"))
+        tj["parts"] = {"sets.bin": {"names_swapped": False}, "sets-2.bin": {"names_swapped": True}}
+        takes.write_json(os.path.join(self.tdir, "take.json"), tj)
+        self.store = takes.Store(self.tmp)
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def test_review_reads_right_names(self):
+        index = takes.take_index(self.tdir)
+        self.assertEqual(index.rename, [True, False])
+        self.assertEqual([c["name"] for c in index.cams], ["slam_right", "slam_left"])
+        self.assertEqual([c["name"] for c in index.read_set(0)], ["slam_right", "slam_left"])
+        self.assertEqual([c["name"] for c in index.read_set(len(index) - 1)], ["slam_right", "slam_left"])
+        # the same pixels under the other name
+        raw = takes.TakeIndex(self.tdir).read_set(0, only="slam_right")[0]["pixels"]
+        self.assertEqual(raw, fhset(10 ** 12, 0)[sides.HDR.size + 2 * sides.CAM.size:][:32 * 24])
+        self.assertEqual(index.renamed_sets(), 30)
+        # the other take has no parts record: recorded as ft-camd named them, renamed too
+        other = takes.take_index(os.path.join(self.sdir, "takes", "02-no-hands"))
+        self.assertEqual(other.rename, [True])
+
+    def test_export_writes_right_names(self):
+        path = self.store.export(SESSION, low_priority=False)
+        r = validate.validate(path)
+        self.assertEqual(r.errors, [])
+        self.assertEqual(r.warnings, [])
+        m = takes.read_json(os.path.join(path, "manifest.json"))
+        t = m["takes"][0]
+        self.assertEqual(t["sides"], {"names_swapped": True, "renamed_sets": 30})
+        self.assertEqual(m["session"]["sides"]["swapped"], True)
+        self.assertEqual(takes.read_json(os.path.join(path, "takes", t["id"], "take.json"))["parts"],
+                         {"sets.bin": {"names_swapped": True}})
+        # every exported set: right names (the rule applied again changes nothing)
+        data = subprocess.run([takes.find_zstd(), "-dc", os.path.join(path, t["file"])],
+                              capture_output=True, check=True).stdout
+        off, seen = 0, 0
+        while off < len(data):
+            nbytes = sides.HDR.unpack_from(data, off)[2]
+            self.assertEqual(names(data[off:off + nbytes]), ["slam_right", "slam_left"])
+            off, seen = off + nbytes, seen + 1
+        self.assertEqual(seen, 35)
+
+    def test_validate_catches_wrong_names(self):
+        path = self.store.export(SESSION, low_priority=False)
+        mpath = os.path.join(path, "manifest.json")
+        m = takes.read_json(mpath)
+        m["takes"][0]["sides"]["names_swapped"] = False
+        takes.write_json(mpath, m)
+        report = validate.Report(path)
+        validate.check_manifest(m, report, path)
+        self.assertTrue(any("aren't named right" in e for e in report.errors), report.errors)
+
+    def test_undecided_warns(self):
+        meta = takes.read_json(os.path.join(self.sdir, "session.json"))
+        meta["sides"] = {"swapped": None}
+        takes.write_json(os.path.join(self.sdir, "session.json"), meta)
+        path = self.store.export(SESSION, low_priority=False)
+        r = validate.validate(path)
+        self.assertEqual(r.errors, [])
+        self.assertTrue(any("wasn't decided" in w for w in r.warnings), r.warnings)
+        m = takes.read_json(os.path.join(path, "manifest.json"))
+        self.assertIsNone(m["takes"][0]["sides"]["names_swapped"])   # the parts differ
+        self.assertEqual(m["takes"][0]["sides"]["renamed_sets"], 0)
+
+    def test_sides_command(self):
+        out = self.store.sides(SESSION)
+        self.assertTrue(out["sides"]["swapped"])
+        self.assertEqual(out["takes"]["01-hand-size"]["sets-2.bin"], {"names_swapped": True, "renamed_when_read": False})
+        out = self.store.sides(SESSION, False)
+        self.assertEqual(out["sides"]["decided_by"], "manual")
+        self.assertTrue(out["sides"]["replaced"]["swapped"])
+        self.assertTrue(out["takes"]["01-hand-size"]["sets-2.bin"]["renamed_when_read"])
+        self.assertEqual(takes.take_index(self.tdir).rename, [False, True])   # the cache saw session.json change
+
+
+class SessionSidesTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp(prefix="handrec-sides-session-")
+        self.script = os.path.join(self.tmp, "script.json")
+        with open(self.script, "w") as f:
+            json.dump({"version": 1, "sections": [{"id": "a", "title": "A", "prompts": [{"text": "x", "seconds": 1}]}]},
+                      f)
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def live(self, **kw):
+        d = dict(pid=1, ring_ino=0, mode="auto", state="decided", swapped=True, decided_by="auto",
+                 evidence={"as_named": 0, "swapped": 10}, updated_ns=time.clock_gettime_ns(time.CLOCK_MONOTONIC))
+        d.update(kw)
+        with open(os.path.join(self.tmp, "sides.json"), "w") as f:
+            json.dump(d, f)
+
+    def test_read_sides(self):
+        s = session.Session(os.path.join(self.tmp, "base"), {}, {}, "room", self.script, dry_run=True,
+                            hands_dir=self.tmp)
+        s.session_dir = self.tmp
+        s._session_json = {"sides": {"swapped": None}}
+        s._read_sides(force=True)
+        self.assertIsNone(s._sides_swapped())   # no file
+        self.live(swapped=None, state="deciding", decided_by=None)
+        s._read_sides(force=True)
+        self.assertIsNone(s._sides_swapped())
+        self.live()
+        s._read_sides(force=True)
+        self.assertTrue(s._sides_swapped())
+        self.assertEqual(s._session_json["sides"]["evidence"]["swapped"], 10)
+        self.live(state="confirmed")
+        s._read_sides(force=True)
+        self.assertEqual(s._session_json["sides"]["state"], "confirmed")
+        self.live(swapped=False, state="decided, reversed")
+        s._read_sides(force=True)
+        self.assertFalse(s._sides_swapped())
+        self.assertTrue(s._session_json["sides"]["reversed_from"]["swapped"])
+        self.assertFalse(takes.read_json(os.path.join(self.tmp, "session.json"))["sides"]["swapped"])
+
+    def test_recorder_parts(self):
+        calls = []
+
+        class FakeProc:
+            returncode = 0
+
+            def __init__(self, argv, **kw):
+                calls.append(argv)
+
+            def poll(self):
+                return 0
+
+        take = os.path.join(self.tmp, "take")
+        os.makedirs(take)
+        with mock.patch.object(session.subprocess, "Popen", FakeProc):
+            r1 = session.Recorder(take, 1, 10, None, None)
+            r2 = session.Recorder(take, 2, 10, None, None, swap=True)
+            r3 = session.Recorder(take, 3, 10, None, None, swap=False)
+        argv = [c[c.index("--sides") + 1] for c in calls]
+        self.assertEqual(argv, ["auto", "1", "0"])
+        # ft-hands' DIR/sides.json goes into names_swapped and away
+        os.makedirs(r2.dir, exist_ok=True)
+        with open(os.path.join(r2.dir, "sets.bin"), "wb") as f:
+            f.write(fhset(10 ** 9, 0))
+        with open(os.path.join(r2.dir, "sides.json"), "w") as f:
+            json.dump({"swapped": None, "names_swapped": [[0, True]]}, f)
+        r2.stop()
+        self.assertTrue(r2.names_swapped)
+        self.assertEqual(r2.file, "sets-2.bin")
+        self.assertTrue(os.path.isfile(os.path.join(take, "sets-2.bin")))
+        self.assertFalse(os.path.exists(r2.dir))
+        with open(os.path.join(take, "sides.json"), "w") as f:
+            json.dump({"swapped": None, "names_swapped": [[0, False]]}, f)
+        r1.stop()
+        self.assertFalse(r1.names_swapped)
+        self.assertFalse(os.path.exists(os.path.join(take, "sides.json")))
+        self.assertFalse(r3.names_swapped)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/hands/rec/tests/test_validate.py b/hands/rec/tests/test_validate.py
new file mode 100644
index 0000000..ae163f1
--- /dev/null
+++ b/hands/rec/tests/test_validate.py
@@ -0,0 +1,556 @@
+#!/usr/bin/env python3
+"""Tests for validate.py and hub.py (no network): a good export, and broken ones.
+
+  python3 hands/rec/tests/test_validate.py     (in the dev container, or anywhere with zstd)
+"""
+import hashlib
+import json
+import os
+import shutil
+import struct
+import sys
+import tempfile
+import unittest
+import uuid
+from unittest import mock
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.dirname(HERE))
+import hub  # noqa: E402
+import session  # noqa: E402
+import takes  # noqa: E402
+import validate  # noqa: E402
+
+SESSION = "20261002-101500"
+DEVICE = {"cv": {"cad_from_cal": {"method": "FrontAndUpperCamPositions", "plus_x": [0.63, -0.77, 0.02],
+                                  "plus_z": [-0.45, -0.35, 0.82], "position": [-0.05, -0.02, 0.04]}},
+          "head": {"plus_x": [-1, 0, 0], "plus_z": [0, 0, -1], "position": [0, 0, 0]}}
+CAMS = [("slam_left", 32, 24), ("slam_right", 32, 24)]
+
+
+def fhset(t_ns, seed):
+    """One FHSET01 record: header, camera headers, pixels."""
+    pixels = b"".join(bytes((seed + i) % 256 for i in range(w * h)) for _, w, h in CAMS)
+    size = validate.HDR.size + validate.CAM.size * len(CAMS) + len(pixels)
+    out = validate.HDR.pack(b"FHSET01\0", len(CAMS), size)
+    for name, w, h in CAMS:
+        out += validate.CAM.pack(name.encode(), w, h, t_ns - 1000, t_ns)
+    return out + pixels
+
+
+def write_sums(export):
+    sums = []
+    for root, _, files in os.walk(export):
+        for name in files:
+            rel = os.path.relpath(os.path.join(root, name), export)
+            if rel != "SHA256SUMS":
+                with open(os.path.join(root, name), "rb") as f:
+                    sums.append((rel, hashlib.sha256(f.read()).hexdigest()))
+    with open(os.path.join(export, "SHA256SUMS"), "w") as f:
+        for rel, digest in sorted(sums):
+            f.write(f"{digest}  {rel}\n")
+
+
+def make_session(base, contributor=None, sid=None, device=True):
+    """A small recorded session in base, as session.py leaves it."""
+    contributor = contributor or str(uuid.uuid4())
+    os.makedirs(base, exist_ok=True)
+    takes.write_json(os.path.join(base, "profile.json"), {
+        "schema": 1, "contributor": contributor,
+        "consent": {"version": "2026-10-02", "accepted": "2026-10-02T10:00:00+00:00", "adult": True},
+        "optional": {"handedness": "right", "notes": ""}})
+    sdir = os.path.join(base, "sessions", sid or SESSION)
+    os.makedirs(os.path.join(sdir, "takes"))
+    takes.write_json(os.path.join(sdir, "session.json"), {
+        "schema": 1, "tool": "ft-handrec test", "started": "2026-10-02T10:15:00+0000", "contributor": contributor,
+        "lighting": {"chosen": "room", "ring": {}},
+        "checklist": {"objects": ["pencil"], "own_objects": ["stapler"], "controllers": "none", "sleeves": "",
+                      "rings": False, "watch": False, "notes": ""},
+        "device": {"steamos": "3.8", "steamvr": "r25358740+28b72a4f-1", "cameras": [{"name": n, "width": w, "height": h}
+                                                                 for n, w, h in CAMS]},
+        "calibration_removed": ["serial"], "takes": ["01-hand-size", "02-no-hands"], "status": "done",
+        "sides": {"swapped": False, "decided_by": "auto", "state": "confirmed"}})
+    takes.write_json(os.path.join(sdir, "calibration.json"),
+                     {"cameras": [{"name": "slam_left", "intrinsics": [1.0, 2.0, 3.0]}]})
+    if device:
+        takes.write_json(os.path.join(sdir, "device.json"), DEVICE)
+    for k, tid in enumerate(("01-hand-size", "02-no-hands")):
+        tdir = os.path.join(sdir, "takes", tid)
+        os.makedirs(tdir)
+        t0 = 10 ** 12 * (k + 1)
+        with open(os.path.join(tdir, "sets.bin"), "wb") as f:
+            for i in range(30):
+                f.write(fhset(t0 + i * 100_000_000, i))
+        with open(os.path.join(tdir, "prompts.jsonl"), "w") as f:
+            f.write(json.dumps({"t": t0, "event": "take", "section": tid[3:], "take": tid}) + "\n")
+            f.write(json.dumps({"t": t0 + 5, "event": "end", "status": "complete"}) + "\n")
+        with open(os.path.join(tdir, "poses.jsonl"), "w") as f:
+            for i in range(10):
+                f.write(json.dumps({"t": t0 + i, "hmd": {"m": [0.0] * 12, "r": 200, "ok": True},
+                                    "left": None, "right": None}) + "\n")
+        takes.write_json(os.path.join(tdir, "take.json"), {"section": tid[3:], "title": tid, "started_ns": t0,
+                                                            "ended_ns": t0 + 3 * 10 ** 9, "status": "complete",
+                                                            "deleted": [], "notes": ""})
+    return contributor
+
+
+class ValidateTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        if not takes.find_zstd():
+            raise unittest.SkipTest("no zstd")
+        cls.tmp = tempfile.mkdtemp(prefix="handrec-validate-test-")
+        cls.base = os.path.join(cls.tmp, "base")
+        cls.contributor = make_session(cls.base)
+        cls.store = takes.Store(cls.base)
+        # One deleted range, so the export leaves sets out.
+        index = takes.take_index(cls.store.take_dir(SESSION, "01-hand-size"))
+        cls.store.delete_range(SESSION, "01-hand-size", index.time_ns(3), index.time_ns(5))
+        cls.export = cls.store.export(SESSION, low_priority=False)
+
+    @classmethod
+    def tearDownClass(cls):
+        shutil.rmtree(cls.tmp, ignore_errors=True)
+
+    def copy(self):
+        d = tempfile.mkdtemp(dir=self.tmp)
+        dest = os.path.join(d, SESSION)
+        shutil.copytree(self.export, dest)
+        return dest
+
+    def assertError(self, report, text):
+        self.assertTrue(any(text in e for e in report.errors), f"no error with {text!r}: {report.errors}")
+
+    def test_good(self):
+        r = validate.validate(self.export)
+        self.assertEqual(r.errors, [])
+        self.assertEqual(r.warnings, [])
+        self.assertTrue(os.path.isfile(os.path.join(self.export, "device.json")))
+        self.assertEqual(r.summary["takes"], 2)
+        self.assertEqual(r.summary["sets"], 57)
+        self.assertEqual(r.summary["consent_version"], "2026-10-02")
+        self.assertEqual(r.summary["contributor"], self.contributor)
+
+    def test_extra_file(self):
+        d = self.copy()
+        with open(os.path.join(d, "notes.txt"), "w") as f:
+            f.write("hello\n")
+        os.makedirs(os.path.join(d, "takes", "01-hand-size", "extra"))
+        r = validate.validate(d)
+        self.assertError(r, "notes.txt: not an allowed file")
+        self.assertError(r, "not in SHA256SUMS: notes.txt")
+        self.assertError(r, "extra/: not an allowed folder")
+
+    def test_symlink(self):
+        d = self.copy()
+        os.symlink("/etc/hostname", os.path.join(d, "takes", "01-hand-size", "take.json.link"))
+        self.assertError(validate.validate(d), "a symlink")
+
+    def test_bad_checksum(self):
+        d = self.copy()
+        path = os.path.join(d, "takes", "02-no-hands", "poses.jsonl")
+        with open(path, "r+b") as f:
+            f.seek(5)
+            f.write(b"9")   # "t": 2... becomes "t": 9...: still valid JSON
+        r = validate.validate(d)
+        self.assertError(r, "checksum mismatch: takes/02-no-hands/poses.jsonl")
+        self.assertEqual(len(r.errors), 1, r.errors)
+
+    def test_calibration_serial(self):
+        d = self.copy()
+        takes.write_json(os.path.join(d, "calibration.json"),
+                         {"cameras": [{"name": "slam_left", "serial": "X", "label": "unit 4H2K19A7731"}]})
+        write_sums(d)
+        r = validate.validate(d)
+        self.assertError(r, "calibration.json: identifying fields left in")
+        self.assertIn("cameras[0].serial", r.errors[0])
+        self.assertIn("cameras[0].label", r.errors[0])
+        self.assertEqual(len(r.errors), 1, r.errors)
+
+    def test_truncated_zst(self):
+        d = self.copy()
+        path = os.path.join(d, "takes", "01-hand-size", "sets.bin.zst")
+        os.truncate(path, os.path.getsize(path) // 2)
+        write_sums(d)
+        r = validate.validate(d)
+        self.assertTrue(any("sets.bin.zst" in e and ("cut short" in e or "set " in e or "decompress" in e)
+                            for e in r.errors), r.errors)
+
+    def test_truncated_zst_command(self):
+        """The same with the zstd program (Python before 3.14)."""
+        d = self.copy()
+        path = os.path.join(d, "takes", "01-hand-size", "sets.bin.zst")
+        os.truncate(path, os.path.getsize(path) // 2)
+        with mock.patch.object(validate, "_zstd", None):
+            r = validate.validate(d)
+            self.assertTrue(any("sets.bin.zst" in e and "checksum" not in e for e in r.errors), r.errors)
+            self.assertEqual(validate.validate(self.export).errors, [])
+
+    def test_garbage_records(self):
+        d = self.copy()
+        rec = bytearray(fhset(10 ** 9, 0))
+        rec[validate.HDR.size:validate.HDR.size + 16] = b"slam left!\0\0\0\0\0\0"
+        zst = os.path.join(d, "takes", "02-no-hands", "sets.bin.zst")
+        with open(zst + ".raw", "wb") as f:
+            f.write(bytes(rec))
+        os.system(f"zstd -q -f {zst}.raw -o {zst} && rm {zst}.raw")
+        write_sums(d)
+        self.assertError(validate.validate(d), "a camera name that isn't one")
+
+    def test_manifest(self):
+        d = self.copy()
+        path = os.path.join(d, "manifest.json")
+        with open(path) as f:
+            m = json.load(f)
+        m["contributor"] = m["profile"]["contributor"] = str(uuid.uuid1())
+        m["consent_version"] = ""
+        m["profile"]["consent"]["version"] = ""
+        m["takes"][0]["sets"] += 1
+        m["session"]["dry_run"] = True
+        m["session"]["device"]["serial_number"] = "x"
+        del m["exported"]
+        takes.write_json(path, m)
+        with open(os.path.join(d, "takes", "02-no-hands", "prompts.jsonl"), "a") as f:
+            f.write("{not json\n")
+        write_sums(d)
+        r = validate.validate(d)
+        self.assertError(r, "isn't a random uuid4")
+        self.assertError(r, "the consent version is empty")
+        self.assertError(r, "27 sets, the manifest says 28")
+        self.assertError(r, "dry-run session")
+        self.assertError(r, "identifying fields: session.device.serial_number")
+        self.assertError(r, "exported is missing")
+        self.assertError(r, "prompts.jsonl line 3: not valid JSON")
+
+    def test_region(self):
+        """From consent 2026-10-03, the residency confirmation must be there."""
+        d = self.copy()
+        path = os.path.join(d, "manifest.json")
+        with open(path) as f:
+            m = json.load(f)
+        m["consent_version"] = m["profile"]["consent"]["version"] = "2026-10-03"
+        takes.write_json(path, m)
+        write_sums(d)
+        self.assertError(validate.validate(d), "Illinois, Texas or Washington")
+        m["profile"]["consent"]["region_ok"] = True
+        takes.write_json(path, m)
+        write_sums(d)
+        self.assertEqual(validate.validate(d).errors, [])
+
+    def test_device(self):
+        d = self.copy()
+        bad = json.loads(json.dumps(DEVICE))
+        bad["device_serial_number"] = "X"
+        bad["head"]["position"] = [0, 0]
+        takes.write_json(os.path.join(d, "device.json"), bad)
+        write_sums(d)
+        r = validate.validate(d)
+        self.assertError(r, "expected cv and head only")
+        self.assertError(r, "head.position isn't 3 numbers")
+        self.assertError(r, "device.json: identifying fields: device_serial_number")
+
+    def test_no_device(self):
+        """Sessions from before device.json still pass, with a warning."""
+        d = self.copy()
+        os.remove(os.path.join(d, "device.json"))
+        write_sums(d)
+        r = validate.validate(d)
+        self.assertEqual(r.errors, [])
+        self.assertTrue(any("no device.json" in w for w in r.warnings), r.warnings)
+
+    def test_zstandard(self):
+        """The zstandard package's path (the maintainer's Windows PC), good and truncated."""
+        if validate._zstandard is None:
+            self.skipTest("no zstandard")
+        with mock.patch.object(validate, "_zstd", None):
+            self.assertEqual(validate.validate(self.export).errors, [])
+            d = self.copy()
+            path = os.path.join(d, "takes", "01-hand-size", "sets.bin.zst")
+            os.truncate(path, os.path.getsize(path) // 2)
+            write_sums(d)
+            self.assertError(validate.validate(d), "sets.bin.zst: the zstd stream is cut short")
+
+    def test_frames(self):
+        """Several zstd frames one after another (zstd -T2 can write them) read as one stream."""
+        if validate._zstd is None and validate._zstandard is None:
+            self.skipTest("no compression.zstd or zstandard")
+        d = self.copy()
+        zst = os.path.join(d, "takes", "02-no-hands", "sets.bin.zst")
+        with open(zst, "rb") as f:
+            one = f.read()
+        with open(zst, "ab") as f:
+            f.write(one)
+        with open(os.path.join(d, "manifest.json")) as f:
+            m = json.load(f)
+        m["takes"][1]["sets"] *= 2
+        m["takes"][1]["raw_bytes"] *= 2
+        takes.write_json(os.path.join(d, "manifest.json"), m)
+        write_sums(d)
+        r = validate.validate(d)
+        self.assertEqual([e for e in r.errors if "go back" not in e], [])
+
+    def test_cli(self):
+        self.assertEqual(os.system(f"{sys.executable} {validate.__file__} {self.export} --json >/dev/null"), 0)
+        d = self.copy()
+        os.remove(os.path.join(d, "manifest.json"))
+        self.assertNotEqual(os.system(f"{sys.executable} {validate.__file__} {d} >/dev/null"), 0)
+
+
+class ExportJsonlTest(unittest.TestCase):
+    """takes.export_jsonl: deleted ranges and the controllers when the checklist says none."""
+
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp(prefix="handrec-jsonl-test-")
+        ctrl = {"m": [0.0] * 12, "r": 200, "ok": True}
+        with open(os.path.join(self.tmp, "poses.jsonl"), "w") as f:
+            for t in range(10):
+                f.write(json.dumps({"t": t, "hmd": ctrl, "left": ctrl, "right": ctrl}) + "\n")
+        with open(os.path.join(self.tmp, "prompts.jsonl"), "w") as f:
+            for e in ({"t": 1, "event": "prompt", "id": "a"}, {"t": 4, "event": "feedback", "left": True},
+                      {"t": 7, "event": "feedback", "left": True, "controller": {"left": "ok"}}):
+                f.write(json.dumps(e) + "\n")
+        os.makedirs(os.path.join(self.tmp, "out"))
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def run_export(self, name, keep):
+        out = os.path.join(self.tmp, "out", name)
+        takes.export_jsonl(os.path.join(self.tmp, name), out, [[3, 5]], keep)
+        with open(out) as f:
+            return [json.loads(line) for line in f]
+
+    def test_no_controllers(self):
+        poses = self.run_export("poses.jsonl", False)
+        self.assertEqual([p["t"] for p in poses], [0, 1, 2, 6, 7, 8, 9])   # 3-5 deleted
+        self.assertTrue(all(p["left"] is None and p["right"] is None and p["hmd"] for p in poses))
+        prompts = self.run_export("prompts.jsonl", False)
+        self.assertEqual([e["t"] for e in prompts], [1, 7])   # the feedback at 4 was in a deleted range
+        self.assertNotIn("controller", prompts[1])
+
+    def test_with_controllers(self):
+        poses = self.run_export("poses.jsonl", True)
+        self.assertTrue(all(p["left"] and p["right"] for p in poses))
+        self.assertIn("controller", self.run_export("prompts.jsonl", True)[1])
+
+
+class SessionFilesTest(unittest.TestCase):
+    """session.py's device.json, and session ids with a suffix."""
+
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp(prefix="handrec-session-test-")
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def test_write_device(self):
+        full = dict(json.loads(json.dumps(DEVICE)), device_serial_number="ABC12345678", display_edid="00ff",
+                    model_number="Frame")
+        src = os.path.join(self.tmp, "device_config.json")
+        takes.write_json(src, full)
+        s = session.Session.__new__(session.Session)
+        s.session_dir, s._log = self.tmp, lambda text: None
+        with mock.patch.object(session, "host_path", lambda p: src if p.endswith("device_config.json") else None):
+            self.assertEqual(s._write_device(), [])
+        with open(os.path.join(self.tmp, "device.json")) as f:
+            self.assertEqual(json.load(f), DEVICE)
+        with mock.patch.object(session, "host_path", lambda p: None):
+            self.assertEqual(s._write_device(), [])
+
+    def test_suffix_id(self):
+        if not takes.find_zstd():
+            self.skipTest("no zstd")
+        sid = SESSION + "-2"
+        make_session(self.tmp, sid=sid)
+        store = takes.Store(self.tmp)
+        self.assertEqual([x["id"] for x in store.sessions()], [sid])
+        path = store.export(sid, low_priority=False)
+        self.assertEqual(validate.validate(path).errors, [])
+
+
+class LoginTest(unittest.TestCase):
+    """hub.login: the link and code go out first, the token is saved by huggingface_hub and never
+    passed on, and a refused login is a "login" error. huggingface_hub's helpers are faked."""
+
+    def setUp(self):
+        try:
+            import huggingface_hub._login
+            import huggingface_hub.utils._oauth_device
+        except ImportError as e:
+            self.skipTest(f"no huggingface_hub browser login: {e}")
+        self.login_mod = huggingface_hub._login
+        self.device = huggingface_hub.utils._oauth_device
+
+    def test_code_then_saved(self):
+        told, saved = [], []
+        info = {"verification_uri_complete": "https://hf.co/oauth/device", "user_code": "ABCD-1234", "expires_in": 300}
+        with mock.patch.object(self.device, "request_device_code", return_value=info), \
+                mock.patch.object(self.device, "poll_device_token", return_value={"access_token": "secret"}), \
+                mock.patch.object(self.login_mod, "_save_oauth_token", side_effect=saved.append), \
+                mock.patch.object(hub, "whoami", return_value={"name": "someone", "role": ""}):
+            who = hub.login(lambda phase, text, **extra: told.append(dict(extra, phase=phase)))
+        self.assertEqual(told, [{"phase": "code", "url": info["verification_uri_complete"], "code": "ABCD-1234",
+                                 "expires_in": 300}])
+        self.assertEqual(saved, [{"access_token": "secret"}])
+        self.assertEqual(who["name"], "someone")
+        self.assertNotIn("secret", json.dumps(told) + json.dumps(who))
+
+    def test_refused(self):
+        from huggingface_hub.errors import DeviceCodeError
+        info = {"verification_uri_complete": "u", "user_code": "c", "expires_in": 300}
+        with mock.patch.object(self.device, "request_device_code", return_value=info), \
+                mock.patch.object(self.device, "poll_device_token", side_effect=DeviceCodeError("access_denied")):
+            with self.assertRaises(hub.HubError) as cm:
+                hub.login()
+        self.assertEqual(cm.exception.kind, "login")
+
+
+class HubTest(unittest.TestCase):
+    """hub.py without the network: the dry run, the draft gate, upload records."""
+
+    def setUp(self):
+        if not takes.find_zstd():
+            self.skipTest("no zstd")
+        self.tmp = tempfile.mkdtemp(prefix="handrec-hub-test-")
+        self.contributor = make_session(self.tmp)
+        self.store = takes.Store(self.tmp)
+        self.store.export(SESSION, low_priority=False)
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def test_dry_run(self):
+        logged = []
+        with mock.patch.dict(os.environ, {hub.DATASET_ENV: "someone/test-hands"}):
+            result = hub.upload(self.store, SESSION, dry_run=True, log=logged.append)
+        self.assertTrue(result["dry_run"])
+        self.assertEqual(result["repo"], "someone/test-hands")
+        self.assertEqual(result["path_in_repo"], f"contributions/{self.contributor}/{SESSION}")
+        self.assertIn("- Takes: 2", result["commit_description"])
+        self.assertIn("- Consent version: 2026-10-02", result["commit_description"])
+        self.assertIn("- Objects: pencil (+1 of their own)", result["commit_description"])
+        self.assertTrue(any("manifest.json" in line for line in logged))
+        self.assertEqual(hub.uploads(self.store, SESSION), [])   # a dry run records nothing
+
+    def test_dataset_env(self):
+        self.assertEqual(hub.dataset_id(), hub.HF_DATASET)
+        with mock.patch.dict(os.environ, {hub.DATASET_ENV: "not a repo"}):
+            self.assertRaises(hub.HubError, hub.dataset_id)
+
+    def test_draft_gate(self):
+        with mock.patch.object(hub, "texts_draft", return_value=True), \
+                mock.patch.dict(os.environ, {hub.ALLOW_ENV: ""}):
+            with self.assertRaises(hub.HubError) as cm:
+                hub.upload(self.store, SESSION)
+            self.assertEqual(cm.exception.kind, "closed")
+            self.assertFalse(hub.upload_allowed())
+        with mock.patch.object(hub, "texts_draft", return_value=True), \
+                mock.patch.dict(os.environ, {hub.ALLOW_ENV: "1"}):
+            self.assertTrue(hub.upload_allowed())
+
+    def test_invalid_blocks(self):
+        with open(os.path.join(self.store.export_dir(SESSION), "extra.bin"), "w") as f:
+            f.write("x")
+        with self.assertRaises(hub.HubError) as cm:
+            hub.upload(self.store, SESSION, dry_run=True)
+        self.assertEqual(cm.exception.kind, "invalid")
+        self.assertTrue(cm.exception.errors)
+
+    def test_record_and_duplicate(self):
+        export = self.store.export_dir(SESSION)
+        sha = hub.export_sha(export)
+        self.assertEqual(len(sha), 64)
+        hub.record_upload(self.store, SESSION, {"repo": "a/b", "pr_url": "https://huggingface.co/datasets/a/b/discussions/1",
+                                                "uploaded": hub.now_iso(), "export_sha": sha})
+        # The upload record doesn't make the export look out of date...
+        self.assertFalse(self.store.sessions()[0]["export_stale"])
+        # ...and the next upload of the same export stops, unless asked again.
+        with self.assertRaises(hub.HubError) as cm:
+            hub.upload(self.store, SESSION, dry_run=True)
+        self.assertEqual(cm.exception.kind, "duplicate")
+        self.assertTrue(hub.upload(self.store, SESSION, dry_run=True, again=True)["dry_run"])
+        # A new export leaves the records out of its manifest.
+        self.store.export(SESSION, low_priority=False)
+        with open(os.path.join(export, "manifest.json")) as f:
+            self.assertNotIn("uploads", json.load(f)["session"])
+
+    def test_pull_request_first(self):
+        """The pull request opens before the files go; a retry goes on in it."""
+        calls = []
+
+        class Pr:
+            def __init__(self, num, status="draft"):
+                self.num, self.status, self.is_pull_request = num, status, True
+                self.url = f"https://huggingface.co/datasets/a/b/discussions/{num}"
+
+        class Api:
+            fail = True
+            status = "draft"
+
+            def whoami(self):
+                return {"name": "someone", "auth": {"accessToken": {"role": "write"}}}
+
+            def auth_check(self, repo, repo_type=None):
+                pass
+
+            def create_pull_request(self, repo, title, description=None, repo_type=None):
+                calls.append("create")
+                return Pr(7)
+
+            def get_discussion_details(self, repo, num, repo_type=None):
+                return Pr(num, Api.status)
+
+            def upload_folder(self, **kw):
+                calls.append(("upload", kw["revision"], kw.get("create_pr")))
+                if Api.fail:
+                    raise ConnectionResetError("reset")
+
+            def change_discussion_status(self, repo, num, status, repo_type=None):
+                calls.append(("status", num, status))
+
+        fake = mock.Mock(HfApi=Api)
+        seen = []
+        env = {hub.DATASET_ENV: "a/b", hub.ALLOW_ENV: "1"}
+        with mock.patch.dict(os.environ, env), mock.patch.object(hub, "_hf", return_value=fake):
+            with self.assertRaises(hub.HubError):
+                hub.upload(self.store, SESSION, progress=lambda phase, text, fraction=None, **extra: seen.append(
+                    (phase, extra.get("pr_url"))))
+            self.assertIn(("opened", "https://huggingface.co/datasets/a/b/discussions/7"), seen)
+            [rec] = hub.uploads(self.store, SESSION)
+            self.assertEqual((rec["status"], rec["pr_num"]), ("started", 7))
+            self.assertIsNone(hub.previous_upload(self.store, SESSION, rec["export_sha"]))   # not a duplicate
+            Api.fail = False
+            result = hub.upload(self.store, SESSION)
+        self.assertEqual(calls, ["create", ("upload", "refs/pr/7", None), ("upload", "refs/pr/7", None),
+                                 ("status", 7, "open")])   # the retry reused #7
+        self.assertEqual(result["pr_url"], "https://huggingface.co/datasets/a/b/discussions/7")
+        [rec] = hub.uploads(self.store, SESSION)
+        self.assertEqual(rec["status"], "done")
+        with mock.patch.dict(os.environ, env), self.assertRaises(hub.HubError) as cm:
+            hub.upload(self.store, SESSION, dry_run=True)
+        self.assertEqual(cm.exception.kind, "duplicate")
+
+    def test_explain(self):
+        try:
+            import httpx
+            from huggingface_hub import errors as hf
+        except ImportError:
+            self.skipTest("no huggingface_hub")
+
+        def response(code):
+            return httpx.Response(code, request=httpx.Request("POST", "https://huggingface.co/api/x"))
+        cases = [(hf.GatedRepoError("gated", response=response(403)), "terms"),
+                 (hf.RepositoryNotFoundError("nope", response=response(404)), "not-found"),
+                 (hf.HfHubHTTPError("no", response=response(403)), "permission"),
+                 (hf.HfHubHTTPError("bad token", response=response(401)), "login"),
+                 (hf.LocalTokenNotFoundError("none"), "login"),
+                 (httpx.ConnectError("down"), "network"),
+                 (ConnectionResetError("reset"), "network")]
+        for exc, kind in cases:
+            e = hub.explain(exc, "a/b")
+            self.assertEqual(e.kind, kind, exc)
+        self.assertIn("https://huggingface.co/datasets/a/b", hub.explain(cases[0][0], "a/b").link)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/hands/rec/validate.py b/hands/rec/validate.py
new file mode 100755
index 0000000..df14332
--- /dev/null
+++ b/hands/rec/validate.py
@@ -0,0 +1,768 @@
+#!/usr/bin/env python3
+"""Check a hand recorder export before it's uploaded, or when it's received (DESIGN.md "Upload").
+
+The window runs it before an upload and refuses on errors; the maintainer runs it on each
+submission. Standard library only. Given an export folder (takes.py's exports/<session>/), it
+checks:
+  - SHA256SUMS: every file listed and matching, nothing missing from it;
+  - an allow-list of files: anything else (or a symlink) is an error;
+  - manifest.json: the schema, required keys and types, and that it agrees with the files;
+  - the consent version is there, the contributor id is a random uuid4, the contributor is an adult;
+  - calibration.json has nothing session.py's strip_calibration would still remove;
+  - device.json (the rig's pose in the CAD frame) holds only cv.cad_from_cal and head, as
+    plus_x, plus_z and position; sessions recorded before it existed get a warning;
+  - each sets.bin.zst decompresses to the end (so a truncated one fails) and parses as FHSET01:
+    every set's header is checked (camera names, sizes, record length) and counted against the
+    manifest; the pixels themselves aren't looked at;
+  - every .jsonl line parses, and take.json does;
+  - the side cameras (sides.py): the session's "sides" decision, and each take's files named
+    right by it (a warning when it wasn't decided: the maintainer's check tells then);
+  - the total size.
+It runs on Linux and Windows, with Python 3.12 or later. It reports errors (don't upload or accept this) and warnings (look at it).
+
+usage: validate.py DIR [--json]      exit status 0: no errors, 1: errors, 2: not an export
+"""
+import argparse
+import hashlib
+import json
+import math
+import os
+import re
+import shutil
+import struct
+import subprocess
+import sys
+import uuid
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+from session import _key_identifies, strip_calibration  # noqa: E402  (standard library only, next to this file)
+
+# Decompression, the first that's there: Python 3.14's compression.zstd, the zstandard package
+# (pip install zstandard: the maintainer's Windows PC), the zstd program.
+try:
+    from compression import zstd as _zstd
+except ImportError:
+    _zstd = None
+try:
+    import zstandard as _zstandard
+except ImportError:
+    _zstandard = None
+
+EXPORT_SCHEMA = 1
+TOP_FILES = {"manifest.json", "calibration.json", "device.json", "SHA256SUMS"}
+REGION_CONSENT = "2026-10-03"   # the consent version that added the residency confirmation
+TAKE_FILES = {"prompts.jsonl", "poses.jsonl", "take.json", "sets.bin.zst"}
+TAKE_RE = re.compile(r"^\d{2}-[a-z0-9][a-z0-9-]*$")
+SESSION_RE = re.compile(r"^\d{8}-\d{6}(?:-\d+)?$")
+SUM_RE = re.compile(r"^([0-9a-f]{64})  (\S.*)$")
+CAM_NAME_RE = re.compile(r"^[a-z][a-z0-9_]{0,15}$")
+TAKE_STATUSES = ("complete", "stopped", "skipped")
+HDR = struct.Struct("<8sII")       # fh_set_hdr_t: magic, ncams, bytes (hands/track/record.h)
+CAM = struct.Struct("<16sIIQQ")    # fh_set_cam_t: name, width, height, capture_ns, dqbuf_ns
+MAX_CAMS = 16
+MIN_SIDE, MAX_SIDE = 16, 4096
+# One round is about 10 GB before compression (ft_handrec.ROUND_BYTES), a few GB after it.
+WARN_BYTES = 15 * 1000 ** 3
+MAX_BYTES = 40 * 1000 ** 3
+CHUNK = 1 << 20
+OUT_CHUNK = 8 << 20
+# zstandard's decompressobj has no output limit: it gets the input this much at a time, so even a
+# stream made to inflate hugely gives out a few hundred MB at most per call.
+ZSTANDARD_PIECE = 8 << 10
+MAX_LISTED = 10   # removed calibration paths and the like: list this many, then "and N more"
+
+
+class Cancelled(Exception):
+    pass
+
+
+class Report:
+    def __init__(self, path):
+        self.path = path
+        self.errors = []
+        self.warnings = []
+        self.summary = {}
+        self.bytes = 0
+
+    def error(self, text):
+        self.errors.append(text)
+
+    def warn(self, text):
+        self.warnings.append(text)
+
+    @property
+    def ok(self):
+        return not self.errors
+
+    def as_dict(self):
+        return {"path": self.path, "ok": self.ok, "errors": self.errors, "warnings": self.warnings,
+                "summary": self.summary, "bytes": self.bytes}
+
+
+def listed(items):
+    items = list(items)
+    more = len(items) - MAX_LISTED
+    return ", ".join(items[:MAX_LISTED]) + (f" and {more} more" if more > 0 else "")
+
+
+def is_uuid4(s):
+    try:
+        u = uuid.UUID(s)
+    except (TypeError, ValueError, AttributeError):
+        return False
+    return u.version == 4 and str(u) == s
+
+
+def sha256_file(path, step=None, cancelled=lambda: False):
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while chunk := f.read(CHUNK):
+            if cancelled():
+                raise Cancelled()
+            h.update(chunk)
+            if step:
+                step(len(chunk))
+    return h.hexdigest()
+
+
+# ---------------------------------------------------------------- the files
+
+def walk_files(root, report):
+    """The export's files as relative paths, and allow-list errors on the way."""
+    files = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        rel_dir = os.path.relpath(dirpath, root).replace(os.sep, "/")
+        rel_dir = "" if rel_dir == "." else rel_dir
+        depth = 0 if not rel_dir else rel_dir.count("/") + 1
+        for d in list(dirnames):
+            rel = f"{rel_dir}/{d}" if rel_dir else d
+            ok = (depth == 0 and d == "takes") or (depth == 1 and rel_dir == "takes" and TAKE_RE.match(d))
+            if os.path.islink(os.path.join(dirpath, d)):
+                report.error(f"{rel}: a symlink, not allowed in an export")
+                dirnames.remove(d)
+            elif not ok:
+                report.error(f"{rel}/: not an allowed folder")
+                dirnames.remove(d)
+        for name in filenames:
+            rel = f"{rel_dir}/{name}" if rel_dir else name
+            full = os.path.join(dirpath, name)
+            if os.path.islink(full) or not os.path.isfile(full):
+                report.error(f"{rel}: a symlink or special file, not allowed in an export")
+                continue
+            if not ((depth == 0 and name in TOP_FILES) or (depth == 2 and name in TAKE_FILES)):
+                report.error(f"{rel}: not an allowed file")
+            files.append(rel)
+    return sorted(files)
+
+
+def check_sums(root, files, report, step, cancelled):
+    path = os.path.join(root, "SHA256SUMS")
+    if not os.path.isfile(path):
+        report.error("SHA256SUMS is missing")
+        return
+    sums = {}
+    with open(path, encoding="utf-8", errors="replace") as f:
+        for n, line in enumerate(f, 1):
+            line = line.rstrip("\n")
+            m = SUM_RE.match(line)
+            if not m:
+                report.error(f"SHA256SUMS line {n}: not \"<sha256>  <path>\"")
+                continue
+            digest, rel = m.groups()
+            if rel.startswith("/") or ".." in rel.split("/") or rel == "SHA256SUMS":
+                report.error(f"SHA256SUMS line {n}: a path that doesn't belong: {rel}")
+                continue
+            if rel in sums:
+                report.error(f"SHA256SUMS lists {rel} twice")
+            sums[rel] = digest
+    present = set(files) - {"SHA256SUMS"}
+    missing = sorted(set(sums) - present)
+    if missing:
+        report.error(f"in SHA256SUMS but missing: {listed(missing)}")
+    unlisted = sorted(present - set(sums))
+    if unlisted:
+        report.error(f"not in SHA256SUMS: {listed(unlisted)}")
+    bad = []
+    for rel in sorted(set(sums) & present):
+        if sha256_file(os.path.join(root, rel), step, cancelled) != sums[rel]:
+            bad.append(rel)
+    if bad:
+        report.error(f"checksum mismatch: {listed(bad)}")
+
+
+def read_json_file(path, rel, report):
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except OSError as e:
+        report.error(f"{rel}: can't read it: {e.strerror or e}")
+    except ValueError as e:
+        report.error(f"{rel}: not valid JSON: {e}")
+    return None
+
+
+def check_jsonl(path, rel, report, cancelled):
+    """Every line a JSON object with a time "t"."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            for n, line in enumerate(f, 1):
+                if n % 50000 == 0 and cancelled():
+                    raise Cancelled()
+                if not line.strip():
+                    continue
+                try:
+                    obj = json.loads(line)
+                except ValueError as e:
+                    report.error(f"{rel} line {n}: not valid JSON: {e}")
+                    return
+                if not isinstance(obj, dict) or not isinstance(obj.get("t"), int):
+                    report.error(f"{rel} line {n}: not an object with a time \"t\"")
+                    return
+    except UnicodeDecodeError:
+        report.error(f"{rel}: not UTF-8 text")
+    except OSError as e:
+        report.error(f"{rel}: can't read it: {e.strerror or e}")
+
+
+# ---------------------------------------------------------------- FHSET01 inside the zstd stream
+
+class SetParser:
+    """Feed it the decompressed stream in pieces: it checks each set's header and skips the
+    pixels. problem holds the first thing wrong (parsing stops there)."""
+
+    def __init__(self):
+        self.buf = bytearray()
+        self.skip = 0           # pixel bytes of the current set still to pass over
+        self.sets = 0
+        self.raw = 0
+        self.cams = {}          # name -> (width, height), every camera seen
+        self.first = None       # the first set's cameras, [{name, width, height}]
+        self.last_t = 0
+        self.backwards = 0      # sets whose earliest dqbuf_ns went back in time
+        self.problem = ""
+
+    def feed(self, data):
+        if self.problem:
+            return
+        self.raw += len(data)
+        view = memoryview(data)
+        while len(view) and not self.problem:
+            if self.skip:
+                n = min(self.skip, len(view))
+                self.skip -= n
+                view = view[n:]
+                continue
+            self.buf += view
+            view = view[len(view):]
+            self._parse()
+
+    def _parse(self):
+        while not self.problem and not self.skip:
+            if len(self.buf) < HDR.size:
+                return
+            magic, ncams, nbytes = HDR.unpack_from(self.buf, 0)
+            where = f"set {self.sets + 1}"
+            if magic != b"FHSET01\0":
+                self.problem = f"{where}: not an FHSET01 record"
+                return
+            if not 0 < ncams <= MAX_CAMS:
+                self.problem = f"{where}: {ncams} cameras"
+                return
+            head = HDR.size + CAM.size * ncams
+            if len(self.buf) < head:
+                return
+            pixels, cams, times = 0, [], []
+            for k in range(ncams):
+                raw_name, w, h, _, dqbuf_ns = CAM.unpack_from(self.buf, HDR.size + k * CAM.size)
+                name_bytes, _, pad = raw_name.partition(b"\0")
+                name = name_bytes.decode("ascii", errors="replace")
+                if pad.strip(b"\0") or not CAM_NAME_RE.match(name):
+                    self.problem = f"{where}: a camera name that isn't one: {raw_name!r}"
+                    return
+                if not (MIN_SIDE <= w <= MAX_SIDE and MIN_SIDE <= h <= MAX_SIDE):
+                    self.problem = f"{where}: camera {name} is {w}x{h}"
+                    return
+                if self.cams.setdefault(name, (w, h)) != (w, h):
+                    self.problem = f"{where}: camera {name} changed size to {w}x{h}"
+                    return
+                pixels += w * h
+                cams.append({"name": name, "width": w, "height": h})
+                times.append(dqbuf_ns)
+            if nbytes != head + pixels:
+                self.problem = f"{where}: {nbytes} bytes, but its cameras need {head + pixels}"
+                return
+            if self.first is None:
+                self.first = cams
+            t = min(times)
+            if t < self.last_t:
+                self.backwards += 1
+            self.last_t = t
+            self.sets += 1
+            rest = len(self.buf) - head
+            if rest >= pixels:
+                del self.buf[:head + pixels]
+            else:
+                self.skip = pixels - rest
+                self.buf.clear()
+
+    def finish(self):
+        """After the stream's end: a set cut short is a problem."""
+        if not self.problem and (self.skip or self.buf):
+            self.problem = f"the stream ends inside set {self.sets + 1}"
+
+
+def find_zstd():
+    found = shutil.which("zstd")
+    if found:
+        return found
+    return next((p for p in ("/usr/bin/zstd", "/run/host/usr/bin/zstd") if os.access(p, os.X_OK)), None)
+
+
+class Frames:
+    """A zstd stream, decompressed piece by piece with compression.zstd or zstandard, frame after
+    frame (zstd -T2 may write several). feed(data) yields the output; complete is false while a
+    frame is unfinished, which at the end of the input means the stream was cut short."""
+
+    def __init__(self):
+        self.dec = self._new()
+        self.fed = False   # the current decompressor has had input
+
+    @staticmethod
+    def _new():
+        return _zstd.ZstdDecompressor() if _zstd is not None else _zstandard.ZstdDecompressor().decompressobj()
+
+    @property
+    def complete(self):
+        return self.dec.eof or not self.fed
+
+    def feed(self, data):
+        while data:
+            if self.dec.eof:   # another frame follows the one that ended
+                self.dec, self.fed = self._new(), False
+            if _zstd is not None:
+                out = self.dec.decompress(data, max_length=OUT_CHUNK)
+                data = b""
+                self.fed = True
+                yield out
+                # More output may wait without more input.
+                while not self.dec.eof and not self.dec.needs_input:
+                    yield self.dec.decompress(b"", max_length=OUT_CHUNK)
+            else:
+                piece, data = data[:ZSTANDARD_PIECE], data[ZSTANDARD_PIECE:]
+                self.fed = True
+                out = self.dec.decompress(piece)
+                if out:
+                    yield out
+            if self.dec.eof:
+                data = self.dec.unused_data + data
+
+
+def check_sets(path, rel, entry, report, step, cancelled):
+    """Decompress rel as a stream and parse it. entry: its take in the manifest, or None."""
+    parser = SetParser()
+    try:
+        if _zstd is not None or _zstandard is not None:
+            frames = Frames()
+            with open(path, "rb") as f:
+                while not parser.problem and (data := f.read(CHUNK)):
+                    if cancelled():
+                        raise Cancelled()
+                    step(len(data))
+                    for out in frames.feed(data):
+                        parser.feed(out)
+                        if parser.problem:
+                            break
+            if not parser.problem and not frames.complete:
+                report.error(f"{rel}: the zstd stream is cut short")
+                return
+        else:
+            zstd = find_zstd()
+            if not zstd:
+                report.warn(f"{rel}: not checked: no zstd (Python 3.14's compression.zstd, the zstandard "
+                            "package or the zstd program)")
+                return
+            argv = [zstd, "-dcq", path]
+            if os.name == "posix" and shutil.which("nice"):
+                argv = ["nice", "-n", "19"] + argv
+            proc = subprocess.Popen(argv, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
+            try:
+                while not parser.problem and (data := proc.stdout.read(CHUNK)):
+                    if cancelled():
+                        raise Cancelled()
+                    parser.feed(data)
+            except BaseException:
+                proc.kill()
+                proc.wait()
+                proc.stdout.close()
+                raise
+            if parser.problem:
+                proc.kill()
+            code = proc.wait()
+            proc.stdout.close()
+            step(os.path.getsize(path))
+            if not parser.problem and code != 0:
+                report.error(f"{rel}: doesn't decompress (zstd exit {code})")
+                return
+    except Cancelled:
+        raise
+    except Exception as e:   # OSError, compression.zstd.ZstdError
+        report.error(f"{rel}: doesn't decompress: {e}")
+        return
+    parser.finish()
+    if parser.problem:
+        report.error(f"{rel}: not a valid FHSET01 recording: {parser.problem}")
+        return
+    if parser.sets == 0:
+        report.error(f"{rel}: holds no frame sets")
+    if parser.backwards:
+        report.warn(f"{rel}: {parser.backwards} sets go back in time")
+    if entry is not None:
+        if entry.get("sets") != parser.sets:
+            report.error(f"{rel}: {parser.sets} sets, the manifest says {entry.get('sets')}")
+        if "raw_bytes" in entry and entry.get("raw_bytes") != parser.raw:
+            report.error(f"{rel}: {parser.raw} bytes uncompressed, the manifest says {entry.get('raw_bytes')}")
+        if isinstance(entry.get("cameras"), list) and parser.first is not None and entry["cameras"] != parser.first:
+            report.error(f"{rel}: its cameras don't match the manifest's")
+    return parser
+
+
+# ---------------------------------------------------------------- the manifest
+
+def need(obj, key, types, where, report, required=True):
+    """obj[key] if it's of the given type(s); an error otherwise."""
+    if not isinstance(obj, dict) or key not in obj:
+        if required:
+            report.error(f"manifest: {where}{key} is missing")
+        return None
+    v = obj[key]
+    allowed = types if isinstance(types, tuple) else (types,)
+    if not isinstance(v, allowed) or (isinstance(v, bool) and bool not in allowed):
+        report.error(f"manifest: {where}{key} has the wrong type ({type(v).__name__})")
+        return None
+    return v
+
+
+def check_pose(pose, where, report, extra=()):
+    """A pose as device_config.json has it: plus_x, plus_z, position, each 3 finite numbers."""
+    if not isinstance(pose, dict):
+        report.error(f"device.json: {where} isn't an object")
+        return
+    for key in ("plus_x", "plus_z", "position"):
+        v = pose.get(key)
+        if not (isinstance(v, list) and len(v) == 3 and all(isinstance(x, (int, float)) and not isinstance(x, bool)
+                                                            and math.isfinite(x) for x in v)):
+            report.error(f"device.json: {where}.{key} isn't 3 numbers")
+    unknown = set(pose) - {"plus_x", "plus_z", "position"} - set(extra)
+    if unknown:
+        report.error(f"device.json: {where} has unexpected keys: {listed(sorted(unknown))}")
+
+
+def check_device(dev, report):
+    """device.json: only cv.cad_from_cal and head (session.py's _write_device)."""
+    if not isinstance(dev, dict):
+        report.error("device.json: not a JSON object")
+        return
+    if set(dev) != {"cv", "head"}:
+        report.error(f"device.json: keys {listed(sorted(dev))}, expected cv and head only")
+    cv = dev.get("cv")
+    if not isinstance(cv, dict) or set(cv) != {"cad_from_cal"}:
+        report.error("device.json: cv should hold cad_from_cal only")
+    else:
+        check_pose(cv["cad_from_cal"], "cv.cad_from_cal", report, extra=("method",))
+        if not isinstance(cv["cad_from_cal"].get("method", ""), str):
+            report.error("device.json: cv.cad_from_cal.method isn't text")
+    if "head" in dev:
+        check_pose(dev["head"], "head", report)
+    _, removed = strip_calibration(dev)
+    if removed:
+        report.error(f"device.json: identifying fields: {listed(removed)}")
+
+
+def identifying_keys(o, path):
+    """Paths of keys under o that name a serial, uuid, mac or id (session.py's rule)."""
+    out = []
+    if isinstance(o, dict):
+        for k, v in o.items():
+            p = f"{path}.{k}"
+            out += [p] if _key_identifies(k) else identifying_keys(v, p)
+    elif isinstance(o, list):
+        for i, v in enumerate(o):
+            out += identifying_keys(v, f"{path}[{i}]")
+    return out
+
+
+def check_manifest(m, report, root):
+    """The manifest's keys and types. Returns {take id: entry} for the file checks."""
+    if not isinstance(m, dict):
+        report.error("manifest: not a JSON object")
+        return {}
+    if m.get("schema") != EXPORT_SCHEMA:
+        report.error(f"manifest: schema {m.get('schema')!r}, expected {EXPORT_SCHEMA}")
+    tool = need(m, "tool", str, "", report)
+    if tool is not None and not tool.startswith("ft-handrec"):
+        report.warn(f"manifest: tool is {tool!r}")
+    need(m, "exported", str, "", report)
+    sid = need(m, "session_id", str, "", report)
+    if sid is not None and not SESSION_RE.match(sid):
+        report.error(f"manifest: session_id {sid!r} isn't a session id")
+    if sid and SESSION_RE.match(os.path.basename(root)) and os.path.basename(root) != sid:
+        report.warn(f"the folder is named {os.path.basename(root)}, the manifest's session is {sid}")
+    contributor = need(m, "contributor", str, "", report)
+    if contributor is not None and not is_uuid4(contributor):
+        report.error(f"manifest: the contributor id {contributor!r} isn't a random uuid4")
+    parent = os.path.basename(os.path.dirname(root))
+    if contributor and is_uuid4(parent) and parent != contributor:
+        report.error(f"the export sits under contributor {parent}, but its manifest says {contributor}")
+    consent = need(m, "consent_version", str, "", report)
+    if consent is not None and not consent.strip():
+        report.error("manifest: the consent version is empty")
+
+    profile = need(m, "profile", dict, "", report)
+    if profile is not None:
+        if profile.get("contributor") != contributor:
+            report.error("manifest: profile.contributor differs from contributor")
+        pc = need(profile, "consent", dict, "profile.", report)
+        if pc is not None:
+            if pc.get("version") != consent:
+                report.error("manifest: profile.consent.version differs from consent_version")
+            if pc.get("adult") is not True:
+                report.error("manifest: the contributor didn't confirm being 18 or older")
+            # from consent 2026-10-03: not living in Illinois, Texas or Washington (CONSENT.md)
+            if str(pc.get("version") or "") >= REGION_CONSENT and pc.get("region_ok") is not True:
+                report.error("manifest: the contributor didn't confirm not living in Illinois, Texas or Washington")
+            need(pc, "accepted", str, "profile.consent.", report)
+        optional = profile.get("optional")
+        if isinstance(optional, dict) and str(optional.get("notes") or "").strip():
+            report.warn("the profile's notes are included: check they hold nothing private")
+        extra = set(profile) - {"schema", "contributor", "consent", "optional"}
+        if extra:
+            report.error(f"manifest: the profile has unexpected keys: {listed(sorted(extra))}")
+
+    session = need(m, "session", dict, "", report)
+    if session is not None:
+        if session.get("contributor") not in (contributor, ""):
+            report.error("manifest: session.contributor differs from contributor")
+        for key, t in (("started", str), ("lighting", dict), ("checklist", dict), ("device", dict),
+                       ("takes", list)):
+            need(session, key, t, "session.", report)
+        if session.get("dry_run"):
+            report.error("this is a dry-run session: it has no real recordings")
+        if "uploads" in session:
+            report.warn("manifest: session.uploads is included (earlier uploads' links)")
+        if not isinstance(session.get("calibration_removed", []), list):
+            report.error("manifest: session.calibration_removed isn't a list")
+        checklist = session.get("checklist")
+        if isinstance(checklist, dict) and str(checklist.get("notes") or "").strip():
+            report.warn("the checklist's notes are included: check they hold nothing private")
+        # Keys only: version strings like SteamVR's "r25358740+28b72a4f-1" look like serials.
+        keys = identifying_keys(session.get("device"), "session.device")
+        if keys:
+            report.error(f"manifest: identifying fields: {listed(keys)}")
+    if "/home/" in json.dumps(m):
+        report.warn("manifest: it mentions a home folder path (a username may show)")
+
+    entries = {}
+    takes = need(m, "takes", list, "", report)
+    for i, t in enumerate(takes or []):
+        where = f"takes[{i}]."
+        if not isinstance(t, dict):
+            report.error(f"manifest: takes[{i}] isn't an object")
+            continue
+        tid = need(t, "id", str, where, report)
+        if tid is None:
+            continue
+        if not TAKE_RE.match(tid):
+            report.error(f"manifest: take id {tid!r} isn't one")
+            continue
+        if tid in entries:
+            report.error(f"manifest: take {tid} is listed twice")
+        entries[tid] = t
+        for key, typ in (("section", str), ("title", str), ("status", str), ("sets", int),
+                         ("sets_deleted", int), ("cameras", list), ("duration_s", (int, float))):
+            need(t, key, typ, where, report)
+        if t.get("status") not in TAKE_STATUSES:
+            report.warn(f"manifest: take {tid} has status {t.get('status')!r}")
+        f = t.get("file")
+        if f is None:
+            if t.get("sets"):
+                report.error(f"manifest: take {tid} has {t.get('sets')} sets but no file")
+        elif f != f"takes/{tid}/sets.bin.zst":
+            report.error(f"manifest: take {tid}'s file is {f!r}")
+        elif not isinstance(t.get("raw_bytes"), int):
+            report.error(f"manifest: take {tid} has a file but no raw_bytes")
+    check_sides(m, entries, report)
+    return entries
+
+
+def check_sides(m, entries, report):
+    """Which side camera is which (sides.py): session.sides.swapped is true, false or null, and
+    every take's files carry names_swapped equal to it (export renames them so)."""
+    session = m.get("session") if isinstance(m.get("session"), dict) else {}
+    s = session.get("sides")
+    if s is None:
+        report.warn("manifest: no session.sides (recorded before the side cameras were checked): "
+                    "the maintainer's check tells which way round they are")
+        return
+    if not isinstance(s, dict) or s.get("swapped") not in (True, False, None):
+        report.error("manifest: session.sides isn't {\"swapped\": true|false|null, ...}")
+        return
+    swapped = s["swapped"]
+    if swapped is None:
+        report.warn("the side cameras' naming wasn't decided while recording (no live tracker): "
+                    "the maintainer's check tells which way round they are")
+    for tid, t in entries.items():
+        ts = t.get("sides")
+        if ts is None:
+            continue
+        if not isinstance(ts, dict) or ts.get("names_swapped") not in (True, False, None):
+            report.error(f"manifest: take {tid}'s sides isn't {{\"names_swapped\": true|false|null, ...}}")
+        elif swapped is not None and ts["names_swapped"] != swapped:
+            report.error(f"take {tid}: its side cameras aren't named right (names_swapped "
+                         f"{ts['names_swapped']}, the session's swapped {swapped}): export it again")
+
+
+def summarize(m):
+    """What a pull request's description says about the export: takes, minutes, lighting,
+    objects, controllers, the consent and tool versions."""
+    if not isinstance(m, dict):
+        return {}
+    session = m.get("session") if isinstance(m.get("session"), dict) else {}
+    checklist = session.get("checklist") if isinstance(session.get("checklist"), dict) else {}
+    lighting = session.get("lighting") if isinstance(session.get("lighting"), dict) else {}
+    takes = [t for t in m.get("takes") or [] if isinstance(t, dict)]
+    seconds = sum(t.get("duration_s") or 0 for t in takes if isinstance(t.get("duration_s"), (int, float)))
+    return {"session": m.get("session_id", ""), "contributor": m.get("contributor", ""),
+            "takes": sum(1 for t in takes if t.get("file")), "takes_listed": len(takes),
+            "sets": sum(t.get("sets") or 0 for t in takes if isinstance(t.get("sets"), int)),
+            "minutes": round(seconds / 60, 1), "lighting": lighting.get("chosen", ""),
+            "objects": list(checklist.get("objects") or []), "own_objects": len(checklist.get("own_objects") or []),
+            "controllers": checklist.get("controllers", ""), "consent_version": m.get("consent_version", ""),
+            "tool": m.get("tool", "")}
+
+
+# ---------------------------------------------------------------- all of it
+
+def validate(root, progress=None, cancel=None):
+    """Check the export at root. progress(fraction 0..1, text) is called as it goes; cancel()
+    (or cancel.is_set()) returning true raises Cancelled. Returns a Report."""
+    root = os.path.abspath(root)
+    report = Report(root)
+    cancelled = getattr(cancel, "is_set", cancel) or (lambda: False)
+    tell = progress or (lambda fraction, text: None)
+    if not os.path.isdir(root):
+        report.error(f"{root}: no such folder")
+        return report
+    files = walk_files(root, report)
+    sizes = {rel: os.path.getsize(os.path.join(root, rel)) for rel in files}
+    report.bytes = sum(sizes.values())
+    # Work: each file's checksum, plus reading each sets.bin.zst again to decompress it.
+    total = max(1, report.bytes + sum(n for rel, n in sizes.items() if rel.endswith(".zst")))
+    done = 0
+
+    def step(n, text):
+        nonlocal done
+        done += n
+        tell(min(done / total, 0.999), text)
+
+    tell(0.0, "Checking checksums")
+    check_sums(root, files, report, lambda n: step(n, "Checking checksums"), cancelled)
+
+    manifest = None
+    if "manifest.json" in files:
+        manifest = read_json_file(os.path.join(root, "manifest.json"), "manifest.json", report)
+    else:
+        report.error("manifest.json is missing")
+    entries = check_manifest(manifest, report, root) if manifest is not None else {}
+    report.summary = summarize(manifest)
+
+    if "calibration.json" in files:
+        cal = read_json_file(os.path.join(root, "calibration.json"), "calibration.json", report)
+        if cal is not None:
+            if not isinstance(cal, dict):
+                report.error("calibration.json: not a JSON object")
+            else:
+                _, removed = strip_calibration(cal)
+                if removed:
+                    report.error(f"calibration.json: identifying fields left in: {listed(removed)}")
+    else:
+        report.warn("no calibration.json: the recordings can't be used in 3D without it")
+    if "device.json" in files:
+        dev = read_json_file(os.path.join(root, "device.json"), "device.json", report)
+        if dev is not None:
+            check_device(dev, report)
+    else:
+        report.warn("no device.json (a session from before it was recorded): the labeller falls back to "
+                    "another unit's head frame")
+
+    take_dirs = sorted({rel.split("/")[1] for rel in files if rel.startswith("takes/") and rel.count("/") == 2})
+    for tid in take_dirs:
+        if tid not in entries:
+            report.error(f"takes/{tid}/ isn't in the manifest")
+    for tid, entry in entries.items():
+        if tid not in take_dirs:
+            report.error(f"take {tid} is in the manifest but has no folder")
+    for tid in take_dirs:
+        if cancelled():
+            raise Cancelled()
+        base = f"takes/{tid}/"
+        title = (entries.get(tid) or {}).get("title") or tid
+        for name in ("prompts.jsonl", "poses.jsonl"):
+            rel = base + name
+            if rel in sizes:
+                check_jsonl(os.path.join(root, rel), rel, report, cancelled)
+            else:
+                report.warn(f"{rel} is missing")
+        if base + "take.json" in sizes:
+            tj = read_json_file(os.path.join(root, base + "take.json"), base + "take.json", report)
+            if tj is not None and not isinstance(tj, dict):
+                report.error(f"{base}take.json: not a JSON object")
+        else:
+            report.warn(f"{base}take.json is missing")
+        rel = base + "sets.bin.zst"
+        entry = entries.get(tid)
+        if rel in sizes:
+            check_sets(os.path.join(root, rel), rel, entry, report,
+                       lambda n, title=title: step(n, f"Checking {title}"), cancelled)
+        elif entry is not None and entry.get("file"):
+            report.error(f"{rel} is missing")
+
+    if report.bytes > MAX_BYTES:
+        report.error(f"the export is {report.bytes / 1000 ** 3:.1f} GB, over the {MAX_BYTES / 1000 ** 3:.0f} GB limit")
+    elif report.bytes > WARN_BYTES:
+        report.warn(f"the export is large: {report.bytes / 1000 ** 3:.1f} GB")
+    tell(1.0, "Checked")
+    return report
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Check a hand recorder export (an exports/<session>/ folder).")
+    ap.add_argument("dir")
+    ap.add_argument("--json", action="store_true", help="print the result as JSON")
+    a = ap.parse_args()
+    if not os.path.isdir(a.dir):
+        print(f"{a.dir}: no such folder", file=sys.stderr)
+        return 2
+    if hasattr(os, "setpriority"):   # not on Windows
+        try:
+            os.setpriority(os.PRIO_PROCESS, 0, 19)   # checksums and decompression: stay out of VR's way
+        except OSError:
+            pass
+    report = validate(a.dir)
+    if a.json:
+        print(json.dumps(report.as_dict(), indent=2))
+    else:
+        for e in report.errors:
+            print(f"error: {e}")
+        for w in report.warnings:
+            print(f"warning: {w}")
+        s = report.summary
+        if s:
+            print(f"{s.get('session')}: {s.get('takes')} takes, {s.get('sets')} sets, {s.get('minutes')} min, "
+                  f"{report.bytes / 1000 ** 2:.1f} MB, consent {s.get('consent_version') or '-'}")
+        print("OK" if report.ok else f"{len(report.errors)} errors")
+    return 0 if report.ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/hands/tests/sides_test.cpp b/hands/tests/sides_test.cpp
new file mode 100644
index 0000000..63588d2
--- /dev/null
+++ b/hands/tests/sides_test.cpp
@@ -0,0 +1,146 @@
+// Unit tests for the side cameras' naming check (track/sides.h), on made-up cameras and a
+// made-up hand: no models, no recordings. make check (in the dev container) builds and runs it.
+#include "../track/sides.h"
+
+#include <cstdio>
+#include <cstdlib>
+
+namespace {
+
+int failures = 0;
+#define CHECK(c)                                                         \
+    do {                                                                 \
+        if (!(c)) std::printf("FAIL %s:%d: %s\n", __FILE__, __LINE__, #c), ++failures; \
+    } while (0)
+
+V3 cross(V3 a, V3 b) { return {a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]}; }
+
+// An equidistant fisheye (k = 0) at origin, looking along look, image "down" toward head -y.
+Camera camera(const char *name, V3 origin, V3 look, int w, int h, double f) {
+    Camera c;
+    c.name = name, c.width = w, c.height = h, c.fx = c.fy = f, c.cx = w / 2.0, c.cy = h / 2.0;
+    const V3 z = unit(look), down{0, -1, 0};
+    const V3 y = unit(down - z * dot(down, z)), x = cross(y, z);
+    for (int i = 0; i < 3; ++i) c.R[i][0] = x[i], c.R[i][1] = y[i], c.R[i][2] = z[i];
+    c.origin = origin;
+    return c;
+}
+
+// MediaPipe-like world landmarks (m, hand-centred, flat: z = 0): x across the palm, y along the fingers
+const double kHand[21][2] = {{0, 0},           {0.03, 0.03},     {0.05, 0.05},     {0.065, 0.07},   {0.075, 0.09},
+                             {0.025, 0.09},    {0.025, 0.13},    {0.025, 0.155},   {0.025, 0.175},  {0.005, 0.095},
+                             {0.005, 0.14},    {0.005, 0.165},   {0.005, 0.185},   {-0.015, 0.09},  {-0.015, 0.13},
+                             {-0.015, 0.155},  {-0.015, 0.17},   {-0.033, 0.08},   {-0.033, 0.11},  {-0.033, 0.13},
+                             {-0.033, 0.145}};
+
+// The hand with its wrist at p, the palm facing toward `facing`, as cam sees it.
+Landmarks view(const Camera &cam, V3 p, V3 facing) {
+    const V3 n = unit(facing - p), up0{0, 1, 0};
+    const V3 along = unit(up0 - n * dot(up0, n)), across = cross(along, n);
+    Landmarks lm;
+    for (int k = 0; k < 21; ++k) {
+        const V3 q = p + across * kHand[k][0] + along * kHand[k][1];
+        lm.pts[k] = cam.project(q, nullptr);
+        lm.world[k][0] = kHand[k][0], lm.world[k][1] = kHand[k][1], lm.world[k][2] = 0;
+    }
+    lm.presence = 0.9;
+    return lm;
+}
+
+Seen seen(const std::string &cam, const Landmarks &lm) { return Seen{cam, 0, Roi{}, lm, {}}; }
+
+}  // namespace
+
+int main() {
+    std::map<std::string, Camera> cams;
+    cams["slam_left"] = camera("slam_left", {-0.045, 0, -0.03}, {-0.5, -0.6, -0.6}, 1056, 1024, 300);
+    cams["slam_right"] = camera("slam_right", {0.045, 0, -0.03}, {0.5, -0.6, -0.6}, 1056, 1024, 300);
+    cams["upper_left"] = camera("upper_left", {-0.03, 0.02, -0.04}, {-0.2, 0.1, -1}, 640, 480, 180);
+    cams["upper_right"] = camera("upper_right", {0.03, 0.02, -0.04}, {0.2, 0.1, -1}, 640, 480, 180);
+    const Camera &L = cams["slam_left"], &R = cams["slam_right"], &UL = cams["upper_left"], &UR = cams["upper_right"];
+    const V3 hand{0.0, -0.22, -0.35}, eyes{0, 0, -0.03};
+    const Landmarks inL = view(L, hand, eyes), inR = view(R, hand, eyes), inUL = view(UL, hand, eyes),
+                    inUR = view(UR, hand, eyes);
+    SideCheck sc(cams);
+    CHECK(sc.usable());
+
+    // 1. the side pair, named right: meets as named, not swapped
+    SideCheck::Miss m = sc.test("slam_left", inL, "slam_right", inR);
+    std::printf("side pair as named: miss %.4f m as named, %.4f swapped\n", m.m[0], m.m[1]);
+    CHECK(m.m[0] >= 0 && m.m[0] < 0.001);
+    CHECK(SideCheck::vote(m) == 0);
+    // 2. the same images under each other's names (what a backwards ft-camd gives)
+    m = sc.test("slam_left", inR, "slam_right", inL);
+    std::printf("side pair swapped: miss %.4f m as named, %.4f swapped\n", m.m[0], m.m[1]);
+    CHECK(m.m[1] >= 0 && m.m[1] < 0.001);
+    CHECK(SideCheck::vote(m) == 1);
+    // 3. a side camera with an upper one
+    m = sc.test("slam_left", inL, "upper_left", inUL);
+    CHECK(SideCheck::vote(m) == 0);
+    m = sc.test("slam_right", inL, "upper_left", inUL);   // slam_left's image under slam_right's name
+    CHECK(SideCheck::vote(m) == 1);
+    m = sc.test("upper_right", inUR, "slam_left", inR);   // ... and the other way round, other order
+    CHECK(SideCheck::vote(m) == 1);
+    // 4. the upper pair alone says nothing
+    CHECK(sc.add({seen("upper_left", inUL), seen("upper_right", inUR)}, 1) == 0);
+    // 5. two different hands, one in each side camera, don't vote
+    const V3 other{0.25, -0.3, -0.3};
+    m = sc.test("slam_left", inL, "slam_right", view(R, other, eyes));
+    std::printf("two hands: miss %.4f m as named, %.4f swapped\n", m.m[0], m.m[1]);
+    CHECK(SideCheck::vote(m) == -1);
+    // 6. a vote needs one way clearly better: both meeting about as well is no vote
+    CHECK(SideCheck::vote({{0.004, 0.006}}) == -1);
+    CHECK(SideCheck::vote({{0.004, 0.02}}) == 0);
+    CHECK(SideCheck::vote({{-1, 0.003}}) == 1);
+    CHECK(SideCheck::vote({{0.02, -1}}) == -1);   // too far apart to be one hand
+    CHECK(SideCheck::vote({{-1, -1}}) == -1);
+
+    // 7. the decision: min_clean votes and none against, or min_votes and at most max_other
+    // against, over min_span_s
+    const std::vector<Seen> named = {seen("slam_left", inL), seen("slam_right", inR)};
+    const std::vector<Seen> swapped = {seen("slam_left", inR), seen("slam_right", inL)};
+    const int64_t s = 1'000'000'000;
+    sc.reset();
+    for (int i = 0; i < 9; ++i) CHECK(sc.add(named, i * s / 5) == 1);
+    CHECK(sc.verdict() == SideCheck::Undecided);   // 9 votes
+    sc.add(named, 9 * s / 5);
+    CHECK(sc.verdict() == SideCheck::AsNamed);     // 10 clean votes over 1.8 s
+    std::printf("%s\n", sc.summary().c_str());
+    // fast: 30 clean votes in 0.97 s aren't enough; the vote at 1.0 s is
+    sc.reset();
+    for (int i = 0; i < 30; ++i) sc.add(swapped, i * s / 30);
+    CHECK(sc.votes[1] == 30 && sc.verdict() == SideCheck::Undecided);
+    sc.add(swapped, s);
+    CHECK(sc.verdict() == SideCheck::Swapped);
+    CHECK(sc.median_miss_mm(1) >= 0 && sc.median_miss_mm(1) < 1);
+    // one vote against: it waits for min_votes
+    sc.reset();
+    sc.add(swapped, 0);
+    for (int i = 1; i < 20; ++i) sc.add(named, i * s / 10);
+    CHECK(sc.verdict() == SideCheck::Undecided);   // 19 to 1
+    sc.add(named, 2 * s);
+    CHECK(sc.verdict() == SideCheck::AsNamed);     // 20 to 1
+    // mixed evidence waits until the other way is at most a fifth of the votes
+    sc.reset();
+    for (int i = 0; i < 20; ++i) sc.add(named, i * s / 10);
+    for (int i = 0; i < 6; ++i) sc.add(swapped, (20 + i) * s / 10);
+    CHECK(sc.verdict() == SideCheck::Undecided);   // 6 of 26
+    for (int i = 0; i < 4; ++i) sc.add(named, (26 + i) * s / 10);
+    CHECK(sc.verdict() == SideCheck::AsNamed);     // 6 of 30
+    // the stricter check after a decision
+    sc.reset();
+    sc.min_clean = 20, sc.min_votes = 40;
+    for (int i = 0; i < 19; ++i) sc.add(named, i * s / 10);
+    CHECK(sc.verdict() == SideCheck::Undecided);
+    sc.add(named, 2 * s);
+    CHECK(sc.verdict() == SideCheck::AsNamed);
+    CHECK(sc.json().find("\"as_named\": 20") != std::string::npos);
+    // without both side cameras it can't check
+    std::map<std::string, Camera> one{{"slam_left", L}, {"upper_left", UL}};
+    SideCheck none(one);
+    CHECK(!none.usable());
+    CHECK(none.add(named, 0) == 0);
+
+    std::printf(failures ? "%d FAILED\n" : "sides_test: all passed\n", failures);
+    return failures ? 1 : 0;
+}
diff --git a/hands/tests/test_camcheck.py b/hands/tests/test_camcheck.py
new file mode 100644
index 0000000..fe58216
--- /dev/null
+++ b/hands/tests/test_camcheck.py
@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""Tests for hands/camcheck.py: the real XRService log of 2026-10-02 (a good start at 13:39,
+the VCINT failure after the 17:02 wake) cut at several points, synthetic logs for the other
+cases, and a made-up ft-camd ring. Nothing here touches SteamVR or the cameras.
+
+  python3 hands/tests/test_camcheck.py
+"""
+import io
+import json
+import os
+import shutil
+import struct
+import sys
+import tempfile
+import time
+import unittest
+from contextlib import redirect_stdout
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.dirname(HERE))
+import camcheck  # noqa: E402
+
+REAL_LOG = os.path.expanduser("~/.local/share/Steam/logs/XRService-2026.10.02/XRService-13-39-32.log")
+
+
+def L(t, text, level="INFO"):
+    """A log line as XRService writes it (with its colour codes on INFO lines)."""
+    if level == "INFO":
+        return "Fri Oct 02 2026 %s.000000 INFO: \x1b[0;36m%s\x1b[0m" % (t, text)
+    return "Fri Oct 02 2026 %s.000000 %s: %s" % (t, level, text)
+
+
+START = [L("10:00:00", "XRService logging to /tmp/x.log. Use --showLogToConsole to see it here as well")]
+GOOD_OPEN = [
+    L("10:00:01", "FPGA state check: PASSTHRU (register value: 0x00011212)"),
+    L("10:00:01", "Passthrough connected but FPGA is PASSTHRU - loading VCINT"),
+    L("10:00:01", "Loading FPGA image: VCINT"),
+    L("10:00:02", "FPGA image VCINT loaded and verified successfully"),
+    L("10:00:02", "Upper cameras FPGA interleaving support: 1 (Driver features available = 1 | VCINT loaded = 1)"),
+    L("10:00:02", "[buildMediaCtlSetupTasks] Created 6 tasks (4 tracking, 2 passthrough)"),
+] + [L("10:00:03", "TrackingCameraInit: index: %d. video device: /dev/video%d. v4l subdevice: /dev/v4l-subdev3%d"
+       % (i, n, i)) for i, n in enumerate((9, 13, 6, 7))]
+CLOSE = [L("11:00:00", "[SystemdInhibitor] Received systemd suspend notification"),
+         L("11:00:00", "[DeckardCaptureSource] Closing tracking camera interfaces camerasToUse: 1111"),
+         L("11:00:01", "[DeckardCaptureSource] Streaming paused")]
+RESUME = [L("11:30:00", "[SystemdInhibitor] Received systemd resume notification"),
+          L("11:30:00", "Failed to read FPGA register 0x12 (exit code 256)", "ERROR"),
+          L("11:30:00", "Passthrough connected but FPGA is ERROR/UNKNOWN - loading VCINT"),
+          L("11:30:00", "Loading FPGA image: VCINT")]
+FAIL = [L("11:30:01", "FPGA load failed (exit code 256): Loading VC Interleaving FPGA image", "ERROR"),
+        "Loading FPGA image from bitstream file /usr/lib/deckard-fpga/images/csi_agg_deckard_ev1_1_vcint.binx",
+        "  FAILED: FPGA config_done signal did not assert",
+        L("11:30:01", "Failed to load VCINT FPGA image when passthrough cameras are connected", "ERROR"),
+        L("11:30:01", "Upper cameras FPGA interleaving support: 0 (Driver features available = 1 | VCINT loaded = 0)"),
+        L("11:30:01", "[buildMediaCtlSetupTasks] Created 4 tasks (2 tracking, 2 passthrough)"),
+        L("11:30:01", "TrackingCameraInit: index: 0. video device: /dev/video9. v4l subdevice: /dev/v4l-subdev31"),
+        L("11:30:01", "TrackingCameraInit: index: 1. video device: /dev/video13. v4l subdevice: /dev/v4l-subdev30"),
+        L("11:30:02", "[DeckardCaptureSource] Streaming resumed (FPGA: PASSTHRU, VC interleaving: disabled)")]
+# A wake that works prints no "Created N tasks" (2026-10-01 16:39), so an older one must not count.
+RESUME_OK = [L("12:30:00", "[SystemdInhibitor] Received systemd resume notification"),
+             L("12:30:00", "Passthrough connected but FPGA is ERROR/UNKNOWN - loading VCINT"),
+             L("12:30:01", "FPGA image VCINT loaded and verified successfully"),
+             L("12:30:01", "FPGA state check: VCINT (register value: 0x00021211)"),
+             L("12:30:01", "Upper cameras FPGA interleaving support: 1 (Driver features available = 1 | VCINT loaded = 1)")] + \
+            [L("12:30:01", "TrackingCameraInit: index: %d. video device: /dev/video%d. v4l subdevice: x" % (i, n))
+             for i, n in enumerate((9, 13, 6, 7))] + \
+            [L("12:30:02", "[DeckardCaptureSource] Streaming resumed (FPGA: VCINT, VC interleaving: enabled)")]
+EXIT = [L("13:00:00", "XRService - main thread exiting"), L("13:00:00", "Exiting XRService")]
+
+
+def state(lines):
+    return camcheck.LogState("test").feed_text("\n".join(lines))
+
+
+class SyntheticLogs(unittest.TestCase):
+    def test_good_start(self):
+        st = state(START + GOOD_OPEN)
+        self.assertEqual(st.verdict()[:2], ("ok", "4 tracking cameras running"))
+        self.assertEqual(st.episode["vcint"], "ok")
+        self.assertEqual(st.upper_nodes(), (6, 7))
+
+    def test_good_start_tasks_only(self):
+        # "Created 6 tasks (4 tracking ...)" and no camera init yet: 4 tracking cameras planned
+        self.assertEqual(state(START + GOOD_OPEN[:6]).verdict()[0], "ok")
+
+    def test_starting(self):
+        self.assertEqual(state(START + GOOD_OPEN[:3]).verdict()[:2], ("unknown", "the cameras are starting"))
+
+    def test_vcint_already_loaded(self):
+        # A SteamVR restart in the same boot (2026-10-01 15:27): the FPGA still has VCINT.
+        lines = START + [L("10:00:01", "FPGA state check: VCINT (register value: 0x00021211)"),
+                         L("10:00:01", "Upper cameras FPGA interleaving support: 1 (Driver features available = 1 | VCINT loaded = 1)"),
+                         L("10:00:01", "[buildMediaCtlSetupTasks] Created 6 tasks (4 tracking, 2 passthrough)")]
+        st = state(lines)
+        self.assertEqual(st.verdict()[0], "ok")
+        self.assertEqual(st.episode["vcint"], "loaded")
+
+    def test_asleep(self):
+        status, reason, ev = state(START + GOOD_OPEN + CLOSE).verdict()
+        self.assertEqual(status, "unknown")
+        self.assertIn("closed", reason)
+        self.assertTrue(any("Closing tracking camera interfaces" in e for e in ev))
+
+    def test_vcint_failure(self):
+        st = state(START + GOOD_OPEN + CLOSE + RESUME + FAIL)
+        status, reason, ev = st.verdict()
+        self.assertEqual((status, reason), ("degraded", camcheck.VCINT_REASON))
+        self.assertTrue(any("Created 4 tasks (2 tracking, 2 passthrough)" in e for e in ev))
+        self.assertTrue(any("Closing tracking camera interfaces" in e for e in ev))
+        self.assertFalse(any("\x1b" in e for e in ev))
+        self.assertEqual(st.snapshot()["failure"], "test@11:30:01")
+        self.assertEqual(len(st.failures), 1)
+
+    def test_failure_seen_before_the_cameras_start(self):
+        # the failure line alone (camera init not logged yet): degraded already
+        st = state(START + GOOD_OPEN + CLOSE + RESUME + FAIL[:4])
+        self.assertEqual(st.verdict()[0], "degraded")
+
+    def test_wake_after_failure_works(self):
+        st = state(START + GOOD_OPEN + CLOSE + RESUME + FAIL + CLOSE + RESUME_OK)
+        self.assertEqual(st.verdict()[0], "ok")
+        self.assertEqual(st.snapshot()["failure"], "")
+        self.assertEqual(len(st.failures), 1)   # still remembered for the log's history
+
+    def test_fewer_cameras_without_vcint(self):
+        lines = START + [L("10:00:01", "[buildMediaCtlSetupTasks] Created 4 tasks (2 tracking, 2 passthrough)")]
+        status, reason, _ = state(lines).verdict()
+        self.assertEqual(status, "degraded")
+        self.assertEqual(reason, "only 2 of 4 tracking cameras running")
+
+    def test_exited_and_empty(self):
+        self.assertEqual(state(START + GOOD_OPEN + EXIT).verdict()[0], "unknown")
+        self.assertEqual(state([]).verdict()[0], "unknown")
+        self.assertEqual(state(START).verdict()[:2], ("unknown", "the cameras haven't started yet in this log"))
+
+    def test_new_instance_resets(self):
+        st = state(START + GOOD_OPEN + CLOSE + RESUME + FAIL + START + GOOD_OPEN)
+        self.assertEqual(st.verdict()[0], "ok")
+        self.assertEqual(st.failures, [])
+
+    def test_incremental_equals_whole(self):
+        text = "\n".join(START + GOOD_OPEN + CLOSE + RESUME + FAIL)
+        st = camcheck.LogState("test")
+        for line in text.split("\n"):
+            st.feed(line + "\n")
+        self.assertEqual(st.snapshot(), state(START + GOOD_OPEN + CLOSE + RESUME + FAIL).snapshot())
+
+
+@unittest.skipUnless(os.path.exists(REAL_LOG), "the 2026-10-02 XRService log isn't on this machine")
+class RealLog(unittest.TestCase):
+    """The log with both the good 13:39 start and the 17:02 failure, cut in copies in /tmp."""
+
+    @classmethod
+    def setUpClass(cls):
+        with open(REAL_LOG, errors="replace") as f:
+            cls.lines = f.read().split("\n")
+        cls.tmp = tempfile.mkdtemp(prefix="camcheck-test-")
+
+    @classmethod
+    def tearDownClass(cls):
+        shutil.rmtree(cls.tmp, ignore_errors=True)
+
+    def cut_after(self, needle, nth=1):
+        """The log up to and including the nth line containing needle, as a file in /tmp."""
+        seen = 0
+        for i, line in enumerate(self.lines):
+            if needle in line:
+                seen += 1
+                if seen == nth:
+                    path = os.path.join(self.tmp, "cut-%d.log" % i)
+                    with open(path, "w") as f:
+                        f.write("\n".join(self.lines[:i + 1]) + "\n")
+                    return path
+        self.fail("no line %d with %r" % (nth, needle))
+
+    def check(self, path):
+        return camcheck.check(log=path, proc=False, ring=False)
+
+    def test_cut_points(self):
+        cases = [
+            ("Loading FPGA image: VCINT", 1, "unknown", "the cameras are starting"),
+            ("FPGA image VCINT loaded and verified successfully", 1, "unknown", "the cameras are starting"),
+            ("Created 6 tasks (4 tracking, 2 passthrough)", 1, "ok", None),
+            ("TrackingCameraInit: index: 3.", 1, "ok", None),
+            ("Upper cameras are not in sync", 1, "ok", None),         # 15:45: a resync, not a failure
+            ("Closing tracking camera interfaces", 1, "unknown", None),   # 16:41: asleep
+            ("Passthrough connected but FPGA is ERROR/UNKNOWN", 1, "unknown", "the cameras are starting"),
+            ("Failed to load VCINT FPGA image", 1, "degraded", camcheck.VCINT_REASON),
+            ("Created 4 tasks (2 tracking, 2 passthrough)", 1, "degraded", camcheck.VCINT_REASON),
+            ("Streaming resumed (FPGA: PASSTHRU", 1, "degraded", camcheck.VCINT_REASON),
+        ]
+        for needle, nth, status, reason in cases:
+            with self.subTest(cut=needle):
+                r = self.check(self.cut_after(needle, nth))
+                self.assertEqual(r["status"], status, r["summary"])
+                if reason:
+                    self.assertEqual(r["reason"], reason)
+        r = self.check(self.cut_after("Closing tracking camera interfaces"))
+        self.assertIn("closed", r["reason"])
+
+    def test_whole_log(self):
+        r = self.check(REAL_LOG)
+        self.assertEqual(r["summary"], camcheck.DEGRADED_VCINT)
+        ev = "\n".join(r["evidence"])
+        for want in ("17:02:47 Failed to load VCINT FPGA image", "interleaving support: 0",
+                     "Created 4 tasks (2 tracking, 2 passthrough)", "/dev/video9", "/dev/video13",
+                     "Closing tracking camera interfaces"):
+            self.assertIn(want, ev)
+        self.assertNotIn("/dev/video6", ev)   # the 13:39 start isn't this episode's evidence
+        self.assertTrue(r["failure"].endswith("@17:02:47"))
+        self.assertTrue(camcheck.is_vcint_failure(r))
+
+    def test_cli(self):
+        out = io.StringIO()
+        with redirect_stdout(out):
+            code = camcheck.main(["--log", REAL_LOG, "--no-proc", "--no-ring", "--json"])
+        self.assertEqual(code, 1)
+        self.assertEqual(json.loads(out.getvalue())["status"], "degraded")
+        out = io.StringIO()
+        with redirect_stdout(out):
+            code = camcheck.main(["--log", self.cut_after("TrackingCameraInit: index: 3."), "--no-proc", "--no-ring"])
+        self.assertEqual(code, 0)
+        self.assertEqual(out.getvalue().split("\n")[0], "ok")
+
+
+def make_ring(path, mono_names, alive=True):
+    """A ring header as ft-camd writes it (camd/fhring.h), no frames."""
+    cams = [(b"og01a1b", n.encode(), 9 + i) for i, n in enumerate(mono_names)]
+    hb = time.clock_gettime_ns(time.CLOCK_MONOTONIC) if alive else 1
+    data = bytearray(camcheck.RING_HDR.pack(b"FHRING01", 1, 0, len(cams), 0, 0, 4242, 0))
+    struct.pack_into("<Q", data, 40, hb)
+    for sensor, name, node in cams:
+        data += camcheck.RING_CAM.pack(sensor, name, node, 0, 1056, 1024, 1056, 16, 0, 0, 0, 0, 0, 0, 0.0)
+    with open(path, "wb") as f:
+        f.write(bytes(data))
+
+
+class Ring(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp(prefix="camcheck-ring-")
+        self.ring = os.path.join(self.tmp, "cam-ring")
+        self.log = os.path.join(self.tmp, "x.log")
+        with open(self.log, "w") as f:
+            f.write("\n".join(START + GOOD_OPEN) + "\n")
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def test_two_cameras_in_ring(self):
+        make_ring(self.ring, ["slam_video9", "slam_video13"])
+        r = camcheck.check(log=self.log, proc=False, ring_path=self.ring)
+        self.assertEqual(r["status"], "degraded")
+        self.assertIn("ft-camd publishes only 2 of 4", r["reason"])
+
+    def test_four_cameras_in_ring(self):
+        make_ring(self.ring, ["a_video9", "b_video13", "c_video6", "d_video7", "a_video9_dk"])
+        r = camcheck.check(log=self.log, proc=False, ring_path=self.ring)
+        self.assertEqual(r["status"], "ok")
+        self.assertEqual(len(r["ring"]["mono"]), 4)   # the dark twin doesn't count
+
+    def test_stale_ring_ignored(self):
+        make_ring(self.ring, ["slam_video9"], alive=False)
+        r = camcheck.check(log=self.log, proc=False, ring_path=self.ring)
+        self.assertEqual(r["status"], "ok")
+        self.assertIn("stale ring", "\n".join(r["evidence"]))
+
+    def test_no_ring(self):
+        r = camcheck.check(log=self.log, proc=False, ring_path=os.path.join(self.tmp, "none"))
+        self.assertEqual(r["status"], "ok")
+        self.assertIsNone(r["ring"])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/hands/tests/test_camwatch.py b/hands/tests/test_camwatch.py
new file mode 100644
index 0000000..cfc9dbe
--- /dev/null
+++ b/hands/tests/test_camwatch.py
@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""Tests for hands/ft-camwatch: its decision logic with made-up inputs (worn or not, VR apps,
+remote viewers, cooldown, once per failure), following a growing log, and its settings. It
+never notifies or restarts anything here.
+
+  python3 hands/tests/test_camwatch.py
+"""
+import importlib.machinery
+import importlib.util
+import os
+import shutil
+import sys
+import tempfile
+import unittest
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+HANDS = os.path.dirname(HERE)
+sys.path.insert(0, HANDS)
+sys.path.insert(0, HERE)
+from test_camcheck import CLOSE, FAIL, GOOD_OPEN, RESUME, RESUME_OK, START  # noqa: E402
+
+loader = importlib.machinery.SourceFileLoader("camwatch", os.path.join(HANDS, "ft-camwatch"))
+spec = importlib.util.spec_from_loader("camwatch", loader)
+cw = importlib.util.module_from_spec(spec)
+loader.exec_module(cw)
+
+ON = dict(cw.DEFAULTS, CAMWATCH_AUTO_RESTART="1", CAMWATCH_IDLE_S="60", CAMWATCH_COOLDOWN_MIN="30")
+OFF = dict(cw.DEFAULTS)
+IDLE = {"steamvr": True, "worn": False, "vr_apps": [], "remote": []}
+WORN = dict(IDLE, worn=True)
+F1, F2 = "a.log@17:02:47", "b.log@18:10:00"
+
+
+def kinds(acts):
+    return [k for k, _ in acts]
+
+
+class Decide(unittest.TestCase):
+    def setUp(self):
+        self.mem = cw.new_memory()
+
+    def d(self, now, failure, env=IDLE, conf=ON):
+        return cw.decide(now, failure, env, self.mem, conf)
+
+    def test_nothing_wrong(self):
+        self.assertEqual(self.d(0, "", {}), [])
+        self.assertEqual(self.mem["pending"], "")
+
+    def test_notify_once(self):
+        acts = self.d(0, F1, WORN, OFF)
+        self.assertEqual(kinds(acts), ["log", "notify", "log"])
+        self.assertIn("CAMWATCH_AUTO_RESTART=1", acts[2][1])
+        self.assertEqual(self.d(2, F1, WORN, OFF), [])          # same failure, same reason: quiet
+        self.assertEqual(self.d(4, F1, IDLE, OFF), [])          # off: never restarts, whatever the state
+        self.assertEqual(self.d(1000, F1, IDLE, OFF), [])
+
+    def test_notify_off(self):
+        acts = self.d(0, F1, WORN, dict(OFF, CAMWATCH_NOTIFY="0"))
+        self.assertNotIn("notify", kinds(acts))
+
+    def test_never_while_worn(self):
+        self.d(0, F1, WORN)
+        for t in range(2, 4000, 2):
+            self.assertNotIn("restart", kinds(self.d(t, F1, WORN)))
+        self.assertIn("worn", self.mem["why"])
+
+    def test_restart_after_idle_then_once(self):
+        self.d(0, F1, WORN)
+        self.assertNotIn("restart", kinds(self.d(10, F1, IDLE)))   # just taken off: wait
+        self.assertIn("waiting", self.mem["why"])
+        self.assertNotIn("restart", kinds(self.d(69, F1, IDLE)))
+        acts = self.d(70, F1, IDLE)
+        self.assertEqual(kinds(acts), ["log", "restart"])
+        self.assertEqual(acts[1][1], F1)
+        # the same failure again (the new XRService hasn't logged yet, or failed the same way)
+        acts = self.d(72, F1, IDLE)
+        self.assertNotIn("restart", kinds(acts))
+        self.assertIn("restart the headset", self.mem["why"])
+        for t in range(74, 10000, 500):
+            self.assertNotIn("restart", kinds(self.d(t, F1, IDLE)))
+
+    def test_put_on_resets_the_wait(self):
+        self.d(0, F1, IDLE)
+        self.d(50, F1, WORN)                                        # back on at 50 s
+        self.assertNotIn("restart", kinds(self.d(70, F1, IDLE)))   # off again: the 60 s start over
+        self.assertNotIn("restart", kinds(self.d(129, F1, IDLE)))
+        self.assertIn("restart", kinds(self.d(131, F1, IDLE)))
+
+    def test_cooldown(self):
+        self.d(0, F1, IDLE)
+        self.assertIn("restart", kinds(self.d(60, F1, IDLE)))
+        # The restart's new XRService fails too: a new failure, but within the cooldown.
+        self.d(90, "", IDLE)
+        acts = self.d(120, F2, IDLE)
+        self.assertIn("notify", kinds(acts))
+        self.assertNotIn("restart", kinds(acts))
+        self.assertNotIn("restart", kinds(self.d(60 + 30 * 60 - 2, F2, IDLE)))
+        self.assertIn("cooldown", self.mem["why"])
+        self.assertIn("restart", kinds(self.d(60 + 30 * 60, F2, IDLE)))
+
+    def test_vr_app_remote_and_no_steamvr(self):
+        for env, word in ((dict(IDLE, vr_apps=["AppId=450390"]), "VR app"),
+                          (dict(IDLE, remote=["0A00000B:D2F0"]), "remote desktop"),
+                          (dict(IDLE, steamvr=False), "SteamVR isn't running")):
+            with self.subTest(word=word):
+                self.mem = cw.new_memory()
+                for t in range(0, 600, 2):
+                    self.assertNotIn("restart", kinds(self.d(t, F1, env)))
+                self.assertIn(word, self.mem["why"])
+                # once it's gone (and the headset still off), the restart happens
+                self.assertIn("restart", kinds(self.d(600, F1, IDLE)))
+
+    def test_resolved(self):
+        self.d(0, F1, WORN)
+        acts = self.d(10, "", {})
+        self.assertEqual(kinds(acts), ["log"])
+        self.assertIn("no longer current", acts[0][1])
+        self.assertEqual(self.mem["pending"], "")
+        self.assertEqual(self.d(12, "", {}), [])
+
+    def test_memory_round_trip(self):
+        tmp = tempfile.mkdtemp(prefix="camwatch-test-")
+        try:
+            path = os.path.join(tmp, "state", "camwatch.json")
+            self.d(0, F1, IDLE)
+            self.d(60, F1, IDLE)
+            cw.save_memory(self.mem, path)
+            mem = cw.load_memory(path)
+            self.assertEqual(mem["restarted"], {F1: 60})
+            self.assertEqual(mem["notified"], [F1])
+            # the watcher restarted: the same failure neither notifies nor restarts again
+            acts = cw.decide(200, F1, IDLE, mem, ON)
+            self.assertNotIn("notify", kinds(acts))
+            self.assertNotIn("restart", kinds(acts))
+            self.assertEqual(cw.load_memory(os.path.join(tmp, "missing.json"))["restarted"], {})
+        finally:
+            shutil.rmtree(tmp, ignore_errors=True)
+
+
+class Follow(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp(prefix="camwatch-follow-")
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def test_growing_log(self):
+        path = os.path.join(self.tmp, "x.log")
+        f = cw.Follower(path)
+        text = "\n".join(START + GOOD_OPEN) + "\n"
+        with open(path, "w") as out:
+            out.write(text)
+        self.assertEqual(cw.current_failure(f.poll()), "")
+        self.assertEqual(f.state.verdict()[0], "ok")
+        # half a line, then the rest: read as one line
+        more = "\n".join(CLOSE + RESUME + FAIL) + "\n"
+        cut = more.index("Failed to load VCINT") + 5
+        with open(path, "a") as out:
+            out.write(more[:cut])
+        self.assertEqual(cw.current_failure(f.poll()), "")
+        with open(path, "a") as out:
+            out.write(more[cut:])
+        self.assertTrue(cw.current_failure(f.poll()).endswith("@11:30:01"))
+        self.assertEqual(cw.current_failure(f.state, steamvr_running=False), "")
+        with open(path, "a") as out:
+            out.write("\n".join(CLOSE + RESUME_OK) + "\n")
+        self.assertEqual(cw.current_failure(f.poll()), "")
+
+    def test_new_log_starts_afresh(self):
+        a, b = os.path.join(self.tmp, "a.log"), os.path.join(self.tmp, "b.log")
+        with open(a, "w") as out:
+            out.write("\n".join(START + GOOD_OPEN + CLOSE + RESUME + FAIL) + "\n")
+        f = cw.Follower(a)
+        self.assertTrue(cw.current_failure(f.poll()))
+        with open(b, "w") as out:
+            out.write("\n".join(START + GOOD_OPEN) + "\n")
+        f.fixed = b   # as when xrservice.txt points at a new XRService's log
+        self.assertEqual(cw.current_failure(f.poll()), "")
+        self.assertEqual(f.path, b)
+
+
+class Settings(unittest.TestCase):
+    def test_read_conf(self):
+        tmp = tempfile.mkdtemp(prefix="camwatch-conf-")
+        try:
+            path = os.path.join(tmp, "frametop.conf")
+            with open(path, "w") as f:
+                f.write("# Frametop\nREMOTE=1   # comment\nCAMWATCH_AUTO_RESTART=1\nCAMWATCH_IDLE_S='90'\n"
+                        "CAMWATCH_IGNORE_APPIDS=\"1, 2\"\nnot a setting\n")
+            conf = cw.read_conf(path)
+            self.assertEqual(conf["CAMWATCH_AUTO_RESTART"], "1")
+            self.assertEqual(cw.conf_int(conf, "CAMWATCH_IDLE_S"), 90)
+            self.assertEqual(conf["CAMWATCH_IGNORE_APPIDS"], "1, 2")
+            self.assertEqual(cw.conf_int(conf, "CAMWATCH_COOLDOWN_MIN"), 30)   # the default
+            self.assertEqual(cw.read_conf(os.path.join(tmp, "none"))["CAMWATCH_AUTO_RESTART"], "0")
+            self.assertEqual(cw.conf_int({"CAMWATCH_IDLE_S": "soon"}, "CAMWATCH_IDLE_S"), 60)
+        finally:
+            shutil.rmtree(tmp, ignore_errors=True)
+
+    def test_headset_worn(self):
+        tmp = tempfile.mkdtemp(prefix="camwatch-bl-")
+        orig = cw.process_running
+        try:
+            os.makedirs(os.path.join(tmp, "panel0"))
+            bright = os.path.join(tmp, "panel0", "brightness")
+            for value, compositor, worn in (("95", True, True), ("0", True, False), ("95", False, False)):
+                with open(bright, "w") as f:
+                    f.write(value + "\n")
+                cw.process_running = lambda name, c=compositor: c and name == "vrcompositor"
+                self.assertEqual(cw.headset_worn(tmp), worn, (value, compositor))
+            self.assertFalse(cw.headset_worn(os.path.join(tmp, "none")))
+        finally:
+            cw.process_running = orig
+            shutil.rmtree(tmp, ignore_errors=True)
+
+    def test_remote_viewers(self):
+        tmp = tempfile.mkdtemp(prefix="camwatch-tcp-")
+        try:
+            path = os.path.join(tmp, "tcp")
+            with open(path, "w") as f:
+                f.write("  sl  local_address rem_address   st tx_queue rx_queue\n"
+                        "   0: 0100007F:170C 00000000:0000 0A 00000000:00000000\n"      # listening
+                        "   1: 0B00640A:170C 0C00640A:D2F0 01 00000000:00000000\n"      # a viewer
+                        "   2: 0B00640A:0016 0C00640A:D2F1 01 00000000:00000000\n")     # ssh
+            self.assertEqual(cw.remote_viewers(5900, (path,)), ["0C00640A:D2F0"])
+            self.assertEqual(cw.remote_viewers(5901, (path,)), [])
+        finally:
+            shutil.rmtree(tmp, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/hands/tools/check_sides.py b/hands/tools/check_sides.py
index 9f77e65..5bbba50 100644
--- a/hands/tools/check_sides.py
+++ b/hands/tools/check_sides.py
@@ -1,11 +1,18 @@
 """Check that the side cameras' images carry the right names (slam_left vs slam_right).
 
-usage: python tools/check_sides.py REC_DIR [--sets N]
-       python tools/check_sides.py --ring [--sets N]    (live, from ft-camd's ring)
+usage: python tools/check_sides.py REC [--sets N] [--pair side|upper] [--calib DIR] [--json]
+       python tools/check_sides.py --ring [--sets N] [--pair side|upper]   (live, from ft-camd's ring)
 
-With --ring it exits 0 when the names are right, 3 when they're swapped (run ft-hands
-with --swap-sides), and 2 when it can't tell (too little texture in view, or the headset
-isn't worn).
+REC is a recording folder (its sets.bin) or a sets file (a take's sets-N.bin). It checks the
+names as they are in the files: a recording's sides.json or session.json "sides" (the hand
+recorder's) isn't applied. Exits 0 when the names are right, 3 when they're swapped, and 2 when
+it can't tell (too little texture in view, or the headset isn't worn). --pair upper checks the
+upper pair (upper_left vs upper_right) the same way. --calib DIR uses DIR/calibration.json and
+DIR/device.json (a hand recorder session's, or cut.py's) instead of /persist. --json prints one
+line: {"pair", "verdict": "named"|"swapped"|"unknown", "named", "swapped", "matches", "sets"}.
+
+ft-hands decides the side cameras' naming by itself (HANDS_SWAP_SIDES=auto, track/sides.h);
+this is the independent check, from the scene rather than hands.
 
 ft-camd tells the two side cameras' buffers apart by the order XRService allocated them,
 and after some XRService restarts that order puts each camera's images under the other's
@@ -15,6 +22,7 @@ with the factory calibration, once as named and once swapped: true matches meet
 front of both cameras only under the right naming.
 """
 import argparse
+import json
 import os
 import sys
 
@@ -26,10 +34,14 @@ from tools.show_set import index, read_set  # noqa: E402
 from tools import calib  # noqa: E402
 
 
-PIPES = {'msm_vfe3_video0': 'slam_left', 'msm_vfe4_video0': 'slam_right'}   # as ft-hands maps them
+PIPES = {'msm_vfe3_video0': 'slam_left', 'msm_vfe4_video0': 'slam_right',    # as ft-hands maps them
+         'msm_vfe2_video0': 'upper_left', 'msm_vfe2_video1': 'upper_right'}
+PAIRS = {'side': ('slam_left', 'slam_right'), 'upper': ('upper_left', 'upper_right')}
 
 
-def load_cams():
+def load_cams(calib_dir=None):
+    if calib_dir:
+        return calib.load(os.path.join(calib_dir, 'calibration.json'), os.path.join(calib_dir, 'device.json'))
     return calib.load()
 
 
@@ -68,18 +80,20 @@ def score(cam_a, cam_b, ua, ub):
     return float(np.mean((d < 0.01) & front))
 
 
-def recorded_pairs(rec, count):
-    """(label, slam_left image, slam_right image) from sets spread across a recording."""
-    path = os.path.join(rec, 'sets.bin')
+def recorded_pairs(rec, count, names=PAIRS['side']):
+    """(label, left image, right image) from sets spread across a recording (or sets file)."""
+    path = rec if os.path.isfile(rec) else os.path.join(rec, 'sets.bin')
     offs = index(path)
-    for n in np.linspace(0, len(offs) - 1, count).astype(int):
+    if not offs:
+        return
+    for n in sorted(set(np.linspace(0, len(offs) - 1, count).astype(int))):
         images = read_set(path, offs[n])
-        if 'slam_left' in images and 'slam_right' in images:
-            yield 'set %5d' % n, images['slam_left'][0], images['slam_right'][0]
+        if names[0] in images and names[1] in images:
+            yield 'set %5d' % n, images[names[0]][0], images[names[1]][0]
 
 
-def live_pairs(count):
-    """(label, slam_left image, slam_right image) from ft-camd's ring, half a second apart."""
+def live_pairs(count, names=PAIRS['side']):
+    """(label, left image, right image) from ft-camd's ring, half a second apart."""
     import time
     from tools.ring import Ring
     ring = Ring()
@@ -91,37 +105,61 @@ def live_pairs(count):
         if name and not c.name.endswith('-dark'):
             cams[name] = c
     for k in range(count):
-        a, b = ring.read(cams['slam_left']), ring.read(cams['slam_right'])
+        a, b = ring.read(cams[names[0]]), ring.read(cams[names[1]])
         if a is not None and b is not None:
             yield 'frame %2d' % k, a.image, b.image
         time.sleep(0.5)
 
 
+def verdict(named, swapped, n, total_matches):
+    """'named', 'swapped' or 'unknown', from the summed per-set scores: the winner must meet
+    clearly more often (by 0.08 a set) and at least 4 times as often. The upper cameras' small
+    images meet within 1 cm less often (0.1-0.4 a set as named, 0 swapped) than the side ones (0.4-0.9)."""
+    hi, lo = max(named, swapped), min(named, swapped)
+    if n == 0 or total_matches < 100 or (hi - lo) / n < 0.08 or lo > 0.25 * hi:
+        return 'unknown'
+    return 'named' if named > swapped else 'swapped'
+
+
+def check(pairs, left, right, out=print):
+    """Score (label, left image, right image) pairs: (verdict, named, swapped, matches, sets)."""
+    named = swapped = 0.0
+    n = total_matches = 0
+    for label, img_l, img_r in pairs:
+        ua, ub = matches(img_l, img_r)
+        s_named = score(left, right, ua, ub)     # the left-named image seen by the left camera
+        s_swapped = score(right, left, ua, ub)   # ... by the right camera
+        named, swapped, n, total_matches = named + s_named, swapped + s_swapped, n + 1, total_matches + len(ua)
+        out('%s: %4d matches, meeting as named %3.0f%%, swapped %3.0f%%' %
+            (label, len(ua), 100 * s_named, 100 * s_swapped))
+    return verdict(named, swapped, n, total_matches), named / max(n, 1), swapped / max(n, 1), total_matches, n
+
+
 def main():
     ap = argparse.ArgumentParser()
     ap.add_argument('rec', nargs='?')
     ap.add_argument('--ring', action='store_true', help='check the live cameras instead of a recording')
     ap.add_argument('--sets', type=int, default=8, help='how many sets or live frames to check')
+    ap.add_argument('--pair', choices=sorted(PAIRS), default='side')
+    ap.add_argument('--calib', help='folder with calibration.json and device.json (default: /persist)')
+    ap.add_argument('--json', action='store_true', help='one JSON line instead of the report')
     a = ap.parse_args()
     if not a.ring and not a.rec:
         ap.error('give a recording or --ring')
-    cams = load_cams()
-    left, right = cams['slam_left'], cams['slam_right']
-    named = swapped = 0.0
-    n = total_matches = 0
-    for label, img_l, img_r in (live_pairs(a.sets) if a.ring else recorded_pairs(a.rec, a.sets)):
-        ua, ub = matches(img_l, img_r)
-        s_named = score(left, right, ua, ub)     # slam_left's image seen by the left camera
-        s_swapped = score(right, left, ua, ub)   # ... by the right camera
-        named, swapped, n, total_matches = named + s_named, swapped + s_swapped, n + 1, total_matches + len(ua)
-        print('%s: %4d matches, meeting as named %3.0f%%, swapped %3.0f%%' %
-              (label, len(ua), 100 * s_named, 100 * s_swapped))
-    if n == 0 or total_matches < 100 or abs(named - swapped) / n < 0.2:
-        print('side cameras: can\'t tell (%d matches)' % total_matches)
-        sys.exit(2)
-    print('side cameras: %s (named %.2f, swapped %.2f)' %
-          ('as named' if named > swapped else 'SWAPPED', named / n, swapped / n))
-    sys.exit(0 if named > swapped else 3)
+    cams = load_cams(a.calib)
+    names = PAIRS[a.pair]
+    left, right = cams[names[0]], cams[names[1]]
+    pairs = live_pairs(a.sets, names) if a.ring else recorded_pairs(a.rec, a.sets, names)
+    v, named, swapped, total, n = check(pairs, left, right, out=(lambda s: None) if a.json else print)
+    what = 'side cameras' if a.pair == 'side' else 'upper cameras'
+    if a.json:
+        print(json.dumps({'pair': a.pair, 'verdict': v, 'named': round(named, 3), 'swapped': round(swapped, 3),
+                          'matches': total, 'sets': n}))
+    elif v == 'unknown':
+        print('%s: can\'t tell (%d matches)' % (what, total))
+    else:
+        print('%s: %s (named %.2f, swapped %.2f)' % (what, 'as named' if v == 'named' else 'SWAPPED', named, swapped))
+    sys.exit({'named': 0, 'swapped': 3, 'unknown': 2}[v])
 
 
 if __name__ == '__main__':
diff --git a/hands/track/main.cpp b/hands/track/main.cpp
index aa2473d..20035fd 100644
--- a/hands/track/main.cpp
+++ b/hands/track/main.cpp
@@ -3,7 +3,7 @@
 // Python prototype: the same scheduling, with the models on a few threads.
 //
 //   ft-hands [--seconds N] [--threads N] [--int8] [--status S] [--models DIR] [--nice N]
-//            [--no-publish] [--no-gestures] [--record DIR] [--swap-sides] [--cams auto|mono|color|all] ...
+//            [--no-publish] [--no-gestures] [--record DIR] [--sides auto|0|1] [--cams auto|mono|color|all] ...
 //            (--help lists them all)
 //
 // --no-gestures: hands for the cutouts only. No pinch or grip detection, so nothing reaches
@@ -22,14 +22,24 @@
 // own clock, so they're placed on the mono cameras' by when they were dequeued, less the
 // mono cameras' measured delay.
 //
+// Which side camera is which (--sides, HANDS_SWAP_SIDES): ft-camd tells slam_left's buffers from
+// slam_right's by XRService's allocation order, which some XRService starts reverse. auto (the
+// default) tells from the hands it tracks (track/sides.h): once it's sure, it exchanges the two
+// cameras if they're backwards (the tracked views move with their images), and checks once
+// more. 0 and 1 force the naming (1: exchanged; --swap-sides is --sides 1); it still checks,
+// and warns if the hands disagree. The decision is published in /run/user/UID/frametop-hands/sides.json (see
+// write_sides below) and, for recordings, in DIR/sides.json. --record-only can't tell (it tracks
+// nothing): under auto it records the ring's names as they are.
+//
 // Settings in ~/.config/frametop.conf (FT_<name> in the environment overrides them, and
-// options override both): HANDS_SWAP_SIDES (1: as --swap-sides), HANDS_CPUS (as --cpus),
+// options override both): HANDS_SWAP_SIDES (auto, 0 or 1), HANDS_CPUS (as --cpus),
 // HANDS_CAMERAS, HANDS_BRIGHT, HANDS_BRIGHT_ON, HANDS_BRIGHT_OFF, HANDS_COLOR_LEFT (which
 // colour camera is passthrough_left: color_video0 or color_video3), HANDS_COLOR_CROP
 // (subtract or none: tools/check_color.py tells both).
 #include "io.h"
 #include "pinch.h"
 #include "record.h"
+#include "sides.h"
 
 #include <sched.h>
 #include <sys/resource.h>
@@ -45,6 +55,7 @@
 #include <cstdio>
 #include <cstring>
 #include <fstream>
+#include <optional>
 #include <thread>
 #include <utility>
 
@@ -148,12 +159,25 @@ struct Lighting {
     }
 };
 
+// Writes path through a temporary file, so a reader never sees half of it.
+bool write_file(const std::string &path, const std::string &text) {
+    const std::string tmp = path + ".tmp";
+    FILE *f = std::fopen(tmp.c_str(), "w");
+    if (!f) return false;
+    const bool ok = std::fputs(text.c_str(), f) >= 0;
+    if (std::fclose(f) != 0 || !ok || std::rename(tmp.c_str(), path.c_str()) != 0) return unlink(tmp.c_str()), false;
+    return true;
+}
+
+std::string json_bool(std::optional<bool> b) { return !b ? "null" : *b ? "true" : "false"; }
+std::string json_str(const std::string &s) { return s.empty() ? "null" : "\"" + s + "\""; }
+
 }  // namespace
 
 int main(int argc, char **argv) {
     double seconds = 0, status = 5;
     int threads = 3, niceness = 5;
-    bool int8 = false, publish = true, track = true, swap_sides = false, gestures_on = true;
+    bool int8 = false, publish = true, track = true, gestures_on = true;
     std::string models = std::string(argv[0]).substr(0, std::string(argv[0]).rfind('/') + 1) + "../models/ncnn";
     std::string record, ring_path = "/run/user/" + std::to_string(getuid()) + "/" FH_RING_NAME;
     // SteamOS starts user processes on CPUs 0-4 and keeps 5-7 (two A720s and the X4) for
@@ -163,7 +187,9 @@ int main(int argc, char **argv) {
     // latency 9.6 against 14.1 ms, and the compositor's late frames and CPU/GPU time didn't change.
     std::vector<int> cpus = {5, 6, 7};
     if (const auto c = parse_cpus(setting("HANDS_CPUS").c_str()); !c.empty()) cpus = c;
-    swap_sides = setting("HANDS_SWAP_SIDES") == "1";
+    // Which side camera is which (see the top): auto, 0 or 1, and where that came from
+    std::string sides_mode = setting("HANDS_SWAP_SIDES"), sides_from = "config";
+    if (sides_mode.empty()) sides_mode = "auto", sides_from = "default";
     // Which cameras (see the top).
     std::string cams_arg = setting("HANDS_CAMERAS"), bright_arg = setting("HANDS_BRIGHT");
     std::string color_left = setting("HANDS_COLOR_LEFT"), color_crop = setting("HANDS_COLOR_CROP");
@@ -181,7 +207,7 @@ int main(int argc, char **argv) {
     PinchParams pinch_params;
     GripParams grip_params;
     bool gesture_log = false;   // what the pinch and grip detectors measure, 10 times a second
-    double record_for = 120;
+    double record_for = 120, record_hz = 0;   // record_hz: at most this many sets a second (0: all)
     for (int i = 1; i < argc; ++i) {
         const std::string a = argv[i];
         const bool more = i + 1 < argc;
@@ -200,11 +226,13 @@ int main(int argc, char **argv) {
         else if (a == "--grip-begin" && more) grip_params.begin = std::atof(argv[++i]);
         else if (a == "--grip-end" && more) grip_params.end = std::atof(argv[++i]);
         else if (a == "--gesture-log") gesture_log = true;
-        else if (a == "--swap-sides") swap_sides = true;
+        else if (a == "--swap-sides") sides_mode = "1", sides_from = "option";
+        else if (a == "--sides" && more) sides_mode = argv[++i], sides_from = "option";
         else if (a == "--record-only") track = publish = false;
         else if (a == "--ring" && more) ring_path = argv[++i];
         else if (a == "--record" && more) record = argv[++i];
         else if (a == "--record-for" && more) record_for = std::atof(argv[++i]);
+        else if (a == "--record-hz" && more) record_hz = std::max(0.0, std::atof(argv[++i]));
         else if (a == "--keep-presence" && more) keep_presence = std::atof(argv[++i]);
         else if (a == "--cams" && more) cams_arg = argv[++i];
         else if (a == "--bright" && more) bright_arg = argv[++i];
@@ -222,19 +250,22 @@ int main(int argc, char **argv) {
         else {
             std::printf("usage: %s [--seconds N] [--threads N] [--int8] [--status S] [--models DIR] [--nice N] [--no-publish]\n"
                         "          [--no-gestures] (hands for the cutouts only: no pinches or grips)\n"
-                        "          [--record DIR] [--record-for S] [--record-only] [--cpus 5,6,7] [--swap-sides]\n"
+                        "          [--record DIR] [--record-for S] [--record-hz N] [--record-only] [--cpus 5,6,7]\n"
+                        "          [--sides auto|0|1] (auto: tell from the hands which side camera is which; 1: exchange them,\n"
+                        "          as --swap-sides; 0: as ft-camd names them)\n"
                         "          [--keep-presence P] (0.5) [--ring PATH] (ft-camd's, or ft-ringplay's)\n"
                         "          [--cams auto|mono|color|all] (auto) [--bright all|color] (all) [--bright-on L] (40) [--bright-off L] (25)\n"
                         "          [--color-left color_video0|color_video3] [--color-crop subtract|none]\n"
                         "          [--pinch-begin M] (0.020) [--pinch-end M] (0.035) [--pinch-triangulated] [--pinch-palm-down MAX] (1: off)\n"
                         "          [--grip-begin R] (1.2) [--grip-end R] (1.45) [--gesture-log]\n"
                         "          [--contrast MODE|PALM/HAND] (clahe[:CLIP], none, stretch; default clahe:2/none)\n"
-                        "Recording saves every frame set for S seconds (120) to DIR/sets.bin, for ft-handreplay; SIGUSR1\n"
+                        "Recording saves every frame set (at most N a second with --record-hz) for S seconds (120) to DIR/sets.bin,\n"
+                        "for ft-handreplay; SIGUSR1\n"
                         "starts one in ~/.local/share/frametop/hands/rec-<time>. --record-only records without tracking, so it\n"
                         "can run beside a tracking ft-hands. With ft-camd --with-dark, recordings also get each\n"
                         "camera's newest dark frame, as <name>_dk; with --with-color, the color cameras' as color_video<N>.\n"
                         "auto picks the cameras by the light (see the top of track/main.cpp).\n"
-                        "Settings in ~/.config/frametop.conf: HANDS_SWAP_SIDES=1, HANDS_CPUS=5,6,7, HANDS_CAMERAS, HANDS_BRIGHT,\n"
+                        "Settings in ~/.config/frametop.conf: HANDS_SWAP_SIDES=auto|0|1, HANDS_CPUS=5,6,7, HANDS_CAMERAS, HANDS_BRIGHT,\n"
                         "HANDS_BRIGHT_ON, HANDS_BRIGHT_OFF, HANDS_COLOR_LEFT, HANDS_COLOR_CROP (FT_<name> overrides).\n",
                         argv[0]);
             return a == "--help" ? 0 : 1;
@@ -245,6 +276,8 @@ int main(int argc, char **argv) {
     if ((!automatic && !parse_cams(cams_arg, fixed)) || !parse_cams(bright_arg, bright_cams) || bright_cams == Cams::Mono)
         return std::fprintf(stderr, "--cams auto|mono|color|all, --bright all|color\n"), 1;
     if (color_crop != "subtract" && color_crop != "none") return std::fprintf(stderr, "--color-crop subtract|none\n"), 1;
+    if (sides_mode != "auto" && sides_mode != "0" && sides_mode != "1")
+        return std::fprintf(stderr, "--sides (HANDS_SWAP_SIDES) auto, 0 or 1, not %s\n", sides_mode.c_str()), 1;
     std::setvbuf(stdout, nullptr, _IOLBF, 0);   // whole lines to the journal as they come
     if (nice(niceness) < 0) std::perror("nice");   // the VR stack wins contested CPUs
     std::signal(SIGINT, [](int) { g_stop = 1; });
@@ -260,10 +293,32 @@ int main(int argc, char **argv) {
     Pinch pinch(pinch_params);
     Grip grip(grip_params);
     std::unique_ptr<Recorder> rec;
-    uint64_t rec_start = 0;
+    uint64_t rec_start = 0, rec_next_ns = 0;   // rec_next_ns: --record-hz's next set, capture clock
+    // The side cameras (see the top). names_swapped: slam_left's and slam_right's ring cameras
+    // are exchanged from ft-camd's naming. truth: whether ft-camd's naming is backwards, once known.
+    bool names_swapped = sides_mode == "1";
+    std::optional<bool> truth;
+    std::string decided_by, sides_state = "deciding", decision_evidence;
+    double decided_after_s = -1;
+    if (sides_mode != "auto") truth = names_swapped, decided_by = sides_from, sides_state = "forced";
+    std::string rec_dir;
+    std::vector<std::pair<size_t, bool>> rec_names;   // from which recorded set on, names_swapped was what
+    // DIR/sides.json beside a recording's sets.bin: how its side cameras are named. A set's
+    // names are right when its names_swapped equals swapped (null: not known when recorded).
+    auto write_rec_sides = [&] {
+        if (!rec) return;
+        std::string runs;
+        for (auto &[from, sw] : rec_names) runs += (runs.empty() ? "" : ", ") + ("[" + std::to_string(from) + ", " + json_bool(sw) + "]");
+        write_file(rec_dir + "/sides.json",
+                   "{\"swapped\": " + json_bool(truth) + ", \"decided_by\": " + json_str(truth ? decided_by : "") +
+                       ", \"names_swapped\": [" + runs + "]" +
+                       (decision_evidence.empty() ? "" : ", \"evidence\": " + decision_evidence) + "}\n");
+    };
     auto start_recording = [&](const std::string &dir, std::string &e) {
         rec = std::make_unique<Recorder>();
         if (!rec->open(dir, e)) return rec.reset(), false;
+        rec_dir = dir, rec_names = {{0, names_swapped}};
+        write_rec_sides();
         rec_start = mono_ns();
         std::printf("recording to %s for %.0f s\n", dir.c_str(), record_for);
         std::fflush(stdout);
@@ -299,12 +354,26 @@ int main(int argc, char **argv) {
         else index[name] = i, used[name] = calib[name];
     }
     // ft-camd tells the side cameras' buffers apart by XRService's allocation order, which
-    // some XRService restarts reverse; tools/check_sides.py --ring tells when.
-    if (swap_sides && index.count("slam_left") && index.count("slam_right")) {
+    // some XRService restarts reverse (see the top).
+    const bool have_sides = index.count("slam_left") && index.count("slam_right");
+    std::map<std::string, uint64_t> last;       // per camera: the frame last used
+    auto exchange_sides = [&] {
         std::swap(index["slam_left"], index["slam_right"]);
+        std::swap(last["slam_left"], last["slam_right"]);
         if (dark.count("slam_left_dk") && dark.count("slam_right_dk")) std::swap(dark["slam_left_dk"], dark["slam_right_dk"]);
-        std::printf("side cameras swapped (--swap-sides)\n");
+    };
+    if (names_swapped && have_sides) {
+        exchange_sides();
+        std::printf("side cameras exchanged (%s)\n", sides_from == "option" ? "--sides 1" : "HANDS_SWAP_SIDES=1");
     }
+    // the mono cameras the side check may pair (not the colour ones)
+    std::map<std::string, Camera> side_cams;
+    for (auto &[name, i] : index) side_cams[name] = calib[name];
+    SideCheck side_check(side_cams);
+    bool checking = track && have_sides && side_check.usable();
+    int side_round = 0;   // auto: 0 deciding, then each check after a decision
+    if (!track && sides_mode == "auto" && have_sides)
+        std::printf("side cameras: as ft-camd names them (--record-only can't tell; the recording's sides.json says so)\n");
     // The colour pair, calibrated (see the top), unless only the mono cameras are wanted.
     if (color.size() == 2 && (automatic || fixed != Cams::Mono)) {
         const std::string left = color.count(color_left) ? color_left : color.begin()->first;
@@ -345,7 +414,6 @@ int main(int argc, char **argv) {
     Tracker tracker(used, nets, pool);
     tracker.set_keep_presence(keep_presence);
     std::map<std::string, std::vector<uint8_t>> pixels;
-    std::map<std::string, uint64_t> last;       // per camera: the frame last used
     std::map<std::string, uint64_t> lit_seen;   // per colour camera: the frame last counted for the light
     const uint64_t start = mono_ns();
     uint64_t t_status = start, next_ns = 0, t_want = 0, t_glog = 0;
@@ -357,6 +425,71 @@ int main(int argc, char **argv) {
     // to place the colour frames, whose capture clock is their own (see the top).
     double mono_delay_ns = -1;
     const std::string want_file = run_dir() + "/color-fps";
+    // The side cameras' naming, for the hand recorder and other tools (hands/rec/session.py
+    // reads it): written by a tracking, publishing ft-hands at the start, on every change and
+    // every 2 s, and removed when it exits. swapped: ft-camd's naming is backwards (null: not
+    // known yet); names_swapped: whether this ft-hands exchanged them; ring_ino: the ring file's
+    // inode (a new ft-camd makes a new one, and the decision is only good for that run).
+    const std::string sides_file = run_dir() + "/sides.json";
+    const bool write_sides_file = publish && track;
+    struct stat ring_st{};
+    stat(ring_path.c_str(), &ring_st);
+    uint64_t t_sides = 0;
+    auto write_sides = [&] {
+        if (!write_sides_file) return;
+        t_sides = mono_ns();
+        write_file(sides_file,
+                   "{\"pid\": " + std::to_string(getpid()) + ", \"ring_ino\": " + std::to_string(ring_st.st_ino) +
+                       ", \"mode\": \"" + sides_mode + "\", \"state\": \"" + sides_state + "\", \"swapped\": " +
+                       json_bool(truth) + ", \"decided_by\": " + json_str(truth ? decided_by : "") +
+                       ", \"names_swapped\": " + json_bool(names_swapped) +
+                       ", \"decided_after_s\": " + std::to_string(decided_after_s) +
+                       ", \"evidence\": " + (decision_evidence.empty() ? "null" : decision_evidence) +
+                       ", \"checking\": " + (checking ? side_check.json() : "null") +
+                       ", \"updated_ns\": " + std::to_string(mono_ns()) + "}\n");
+    };
+    write_sides();
+    // A verdict from the side check (see the top and track/sides.h).
+    auto side_verdict = [&](SideCheck::Verdict v, uint64_t now) {
+        const bool backwards = v == SideCheck::Swapped;   // relative to the names as they are now
+        const double after = (now - start) / 1e9;
+        const std::string ev = side_check.json(), text = side_check.summary();
+        if (sides_mode != "auto") {   // forced: only say so
+            const std::string what = (sides_from == "option" ? "--sides " : "HANDS_SWAP_SIDES=") + sides_mode;
+            if (backwards)
+                std::printf("side cameras: %s looks WRONG: the hands say the side cameras are the other way round (%s). "
+                            "Use auto.\n", what.c_str(), text.c_str());
+            else
+                std::printf("side cameras: %s agrees with the hands (%s)\n", what.c_str(), text.c_str());
+            sides_state = backwards ? "forced, disagrees" : "forced, agrees";
+            decision_evidence = ev;
+            checking = false;
+        } else if (side_round == 0 || backwards) {
+            if (backwards) {
+                exchange_sides();
+                names_swapped = !names_swapped;
+                tracker.exchange("slam_left", "slam_right");
+                if (rec) rec_names.push_back({rec->added(), names_swapped});
+            }
+            const bool reversed = side_round > 0;
+            truth = names_swapped, decided_by = "auto", decided_after_s = after, decision_evidence = ev;
+            sides_state = reversed ? "decided, reversed" : "decided";
+            std::printf("side cameras: %s after %.1f s (%s)\n",
+                        reversed ? "decision REVERSED" : names_swapped ? "SWAPPED, now exchanged" : "as named", after,
+                        text.c_str());
+            // check once more with the new names, more strictly; at most two changes
+            side_check.reset();
+            side_check.min_clean = 20, side_check.min_votes = 40;
+            checking = ++side_round < 3;
+        } else {
+            std::printf("side cameras: confirmed after %.1f s (%s)\n", after, text.c_str());
+            sides_state = "confirmed";
+            checking = false;
+        }
+        std::fflush(stdout);
+        write_rec_sides();
+        write_sides();
+    };
 
     // The colour pair's newest frames if both are newer than last used and taken together
     // (their own clock): their time, on the mono cameras' capture clock, else 0.
@@ -403,8 +536,13 @@ int main(int argc, char **argv) {
         return n ? sum / n : -1;
     };
 
+    int exit_code = 0;
     while (!g_stop && (seconds <= 0 || (mono_ns() - start) / 1e9 < seconds)) {
-        if (!ring.alive()) return std::fprintf(stderr, "ft-camd stopped\n"), 2;
+        if (!ring.alive()) {
+            std::fprintf(stderr, "ft-camd stopped\n");
+            exit_code = 2;
+            break;
+        }
         const uint64_t now0 = mono_ns();
         const int64_t raw_off = raw_minus_mono_ns();
 
@@ -490,7 +628,16 @@ int main(int argc, char **argv) {
                 if (!start_recording(dir + "/" + name, e)) std::fprintf(stderr, "%s\n", e.c_str());
             }
             if (rec) {   // about 80 MB/s; dark frames double that, color frames add 70 MB/s
-                if ((mono_ns() - rec_start) / 1e9 < record_for) {
+                const bool due = record_hz <= 0 || tmin >= rec_next_ns;   // --record-hz skips the sets between
+                if (due && record_hz > 0) rec_next_ns = tmin + uint64_t(1e9 / record_hz) - 5'000'000;
+                if ((mono_ns() - rec_start) / 1e9 >= record_for) {
+                    write_rec_sides();
+                    const size_t n = rec->written(), d = rec->dropped();
+                    rec.reset();   // writes out what's queued
+                    std::printf("recording done: %zu sets, %zu dropped\n", n, d);
+                    std::fflush(stdout);
+                    if (!track) break;
+                } else if (due) {
                     for (auto &[name, i] : dark) {   // the newest dark and color frames, as they are
                         fh_ring_slot_t meta;
                         const uint64_t n = ring.latest(i);
@@ -500,12 +647,6 @@ int main(int argc, char **argv) {
                                               meta.dqbuf_ns});
                     }
                     rec->add(frames);
-                } else {
-                    const size_t n = rec->written(), d = rec->dropped();
-                    rec.reset();   // writes out what's queued
-                    std::printf("recording done: %zu sets, %zu dropped\n", n, d);
-                    std::fflush(stdout);
-                    if (!track) break;
                 }
             }
             if (!track && rec && status > 0 && (mono_ns() - t_status) / 1e9 >= status) {
@@ -548,6 +689,16 @@ int main(int argc, char **argv) {
         const auto hands = tracker.step(images, int64_t(tmin));
         const uint64_t capture = uint64_t(int64_t(tmin) - raw_off);   // CLOCK_MONOTONIC
         const std::vector<Seen> views = tracker.views_now();
+        std::vector<Seen> side_views;   // the tracker's views, plus the side check's own looks
+        if (checking) {
+            side_views = views;
+            for (Seen &v : side_check.probe(nets, pool, images, views, int64_t(tmin))) side_views.push_back(v);
+        }
+        if (checking && side_check.add(side_views, int64_t(tmin)) > 0) {
+            const SideCheck::Verdict v = side_check.verdict();
+            if (v != SideCheck::Undecided) side_verdict(v, mono_ns());
+        }
+        if (mono_ns() - t_sides > 2'000'000'000ull) write_sides();
         if (gestures_on) {
             grip.update(hands, views, int64_t(capture));
             pinch.update(hands, views, int64_t(capture), grip.gripping());
@@ -603,6 +754,9 @@ int main(int argc, char **argv) {
                             s.handoff_miss, s.dups, s.splits, s.created, s.merged, s.forgotten,
                             !rec ? "" : ("  recorded " + std::to_string(rec->written()) + " dropped " +
                                          std::to_string(rec->dropped())).c_str());
+            if (checking)
+                std::printf("        side cameras: %s, %s\n", side_round ? "checking the decision" : "deciding",
+                            side_check.summary().c_str());
             if (gestures_on) {
                 std::printf("        pinches: left %u right %u (held back, palm down: %d %d)  grips: left %u right %u",
                             pinch.side(0).begins, pinch.side(1).begins, pinch.held_back[0], pinch.held_back[1],
@@ -628,11 +782,13 @@ int main(int argc, char **argv) {
         }
     }
     if (!color.empty()) unlink(want_file.c_str());
+    if (write_sides_file) unlink(sides_file.c_str());
+    write_rec_sides();
     if (publish) pub.write({}, mono_ns());
     if (publish && gestures_on) {
         pinch.release(int64_t(mono_ns()));   // a drag in progress ends, as lost
         grip.release(int64_t(mono_ns()));
         gestures.write(pinch, grip, mono_ns());
     }
-    return 0;
+    return exit_code;
 }
diff --git a/hands/track/record.cpp b/hands/track/record.cpp
index b64f04b..594940c 100644
--- a/hands/track/record.cpp
+++ b/hands/track/record.cpp
@@ -57,6 +57,7 @@ void Recorder::add(const std::vector<SetFrame> &frames) {
             return;
         }
         queue_.push_back(std::move(rec));
+        ++added_;
     }
     wake_.notify_one();
 }
diff --git a/hands/track/record.h b/hands/track/record.h
index b088e9d..9813a1d 100644
--- a/hands/track/record.h
+++ b/hands/track/record.h
@@ -42,6 +42,9 @@ public:
     ~Recorder();
     bool open(const std::string &dir, std::string &err);
     void add(const std::vector<SetFrame> &frames);
+    // Sets taken (not dropped for a full queue): the next one's place in the file, unless a
+    // write fails.
+    size_t added() const { return added_; }
     size_t written() const { return written_; }
     size_t dropped() const { return dropped_; }
 
@@ -53,7 +56,7 @@ private:
     std::condition_variable wake_;
     std::deque<std::vector<uint8_t>> queue_;
     bool stop_ = false;
-    size_t written_ = 0, dropped_ = 0;
+    size_t written_ = 0, dropped_ = 0, added_ = 0;
 };
 
 // Reads a recording back one set at a time.
diff --git a/hands/track/replay.cpp b/hands/track/replay.cpp
index 04cbbbe..f14995a 100644
--- a/hands/track/replay.cpp
+++ b/hands/track/replay.cpp
@@ -3,6 +3,7 @@
 //
 //   ft-handreplay DIR [--oracle N] [--slow F] [--timeline FILE] [--threads N] [--models DIR]
 //             [--from S] [--to S] [--contrast MODE|PALM/HAND] (clahe[:CLIP], none, stretch)
+//             [--sides file|0|1|auto]
 //
 // --oracle N: every N-th set, also search every tile of every camera (slow), to see
 //             which hands were there to find. Compares that with what the tracker had.
@@ -27,18 +28,29 @@
 //             views, hand scale, then its 21 world landmarks (the model's own 3D pose, averaged
 //             over its views, times the scale; metres, hand-centred) and its 21 published
 //             points (head frame). For studying gestures (pinch against typing, a fist).
+// --sides file|0|1|auto: the side cameras' names as DIR/sides.json says they should be (file, the
+//             default: ft-hands writes one with every recording; hands/rec/sides.py has the rule;
+//             without one, as recorded), as recorded (0), exchanged (1), or as ft-hands' auto
+//             decides them from the recorded names (track/sides.h): exchanged from the set it decides on,
+//             the tracker's views moving with their images (Tracker::exchange). The side check runs in every mode, and the report
+//             says what it found and when: seconds into the recording, and after how long of
+//             hands (from the first set with a hand in view).
 // --depth FILE: per processed set, a line per hand for tools/depth_report.py: its views'
 //             cameras, triangulation residual, hand scale, measured and published palm, and
 //             each view's one-view palm (Tracker::single_view at the hand's scale). The
 //             header has each camera's centre and focal length.
 #include "pinch.h"
 #include "record.h"
+#include "sides.h"
 #include "tracker.h"
 
+#include <json/json.h>
+
 #include <algorithm>
 #include <chrono>
 #include <cstdio>
 #include <cstring>
+#include <fstream>
 #include <map>
 #include <set>
 #include <string>
@@ -76,7 +88,7 @@ int main(int argc, char **argv) {
     double keep_presence = 0.5;   // landmark presence a tracked view needs to stay
     PinchParams pinch_params;
     GripParams grip_params;
-    std::string use = "mono", color_left = "color_video0", color_crop = "subtract";
+    std::string use = "mono", color_left = "color_video0", color_crop = "subtract", sides = "file";
     std::string timeline, depth, poses, models = std::string(argv[0]).substr(0, std::string(argv[0]).rfind('/') + 1) + "../models/ncnn";
     for (int i = 2; i < argc; ++i) {
         const std::string a = argv[i];
@@ -91,6 +103,7 @@ int main(int argc, char **argv) {
         else if (a == "--cost") cost = true;
         else if (a == "--keep-presence" && more) keep_presence = std::atof(argv[++i]);
         else if (a == "--cams" && more) use = argv[++i];
+        else if (a == "--sides" && more) sides = argv[++i];
         else if (a == "--pinch-begin" && more) pinch_params.begin_m = std::atof(argv[++i]);
         else if (a == "--pinch-end" && more) pinch_params.end_m = std::atof(argv[++i]);
         else if (a == "--pinch-triangulated") pinch_params.triangulated = true;
@@ -120,6 +133,24 @@ int main(int argc, char **argv) {
     std::vector<std::vector<uint8_t>> px;
     if (!in.next(cams, px)) return std::fprintf(stderr, "%s: no sets\n", dir.c_str()), 1;
     if (use != "mono" && use != "color" && use != "all") return std::fprintf(stderr, "--cams mono|color|all\n"), 1;
+    if (sides != "file" && sides != "0" && sides != "1" && sides != "auto")
+        return std::fprintf(stderr, "--sides file|0|1|auto\n"), 1;
+    // --sides file: from which set on the recorded names need exchanging (hands/rec/sides.py)
+    std::vector<std::pair<int, bool>> file_runs = {{0, false}};
+    if (sides == "file") {
+        std::ifstream f(dir + "/sides.json");
+        Json::Value v;
+        Json::CharReaderBuilder b;
+        std::string e;
+        if (f && Json::parseFromStream(b, f, &v, &e) && v["swapped"].isBool()) {
+            file_runs.clear();
+            for (const Json::Value &r : v["names_swapped"])
+                file_runs.push_back({r[0].asInt(), r[1].asBool() != v["swapped"].asBool()});
+            if (file_runs.empty()) file_runs = {{0, v["swapped"].asBool()}};
+            std::printf("side cameras: %s.json says swapped %s (%s)\n", (dir + "/sides").c_str(),
+                        v["swapped"].asBool() ? "true" : "false", v["decided_by"].asString().c_str());
+        }
+    }
     if (use != "mono") {
         std::vector<std::string> nodes;
         for (auto &c : cams)
@@ -136,6 +167,21 @@ int main(int argc, char **argv) {
     }
     Pool pool(threads, {2, 3, 4});
     Tracker tracker(used, nets, pool);
+    // The side cameras (see the top): names_swapped exchanges slam_left's and slam_right's names
+    // as sets are read.
+    bool names_swapped = sides == "1";
+    std::map<std::string, Camera> mono;
+    for (auto &[name, c] : used)
+        if (name.rfind("color_", 0) != 0) mono[name] = c;
+    SideCheck side_check(mono);
+    bool checking = side_check.usable();
+    int side_round = 0;
+    double first_hand_ts = -1;
+    std::string side_report;
+    auto rename = [&](const std::string &n) -> std::string {
+        if (!names_swapped) return n;
+        return n == "slam_left" ? "slam_right" : n == "slam_right" ? "slam_left" : n;
+    };
     tracker.set_keep_presence(keep_presence);
     FILE *dp = depth.empty() ? nullptr : std::fopen(depth.c_str(), "w");
     FILE *pp = poses.empty() ? nullptr : std::fopen(poses.c_str(), "w");
@@ -164,13 +210,16 @@ int main(int argc, char **argv) {
     double grip_begin_ts[2] = {0, 0};
     std::vector<double> grip_len[2];
     do {
+        if (sides == "file")
+            for (auto &[first, rename] : file_runs)
+                if (index + 1 >= first) names_swapped = rename;
         std::map<std::string, Image> images;
         // the set's time: the mono cameras' when they're used (the color ones run on another
         // clock); color frames can repeat across sets, so a set that doesn't move time on is skipped
         uint64_t t = UINT64_MAX, t_color = UINT64_MAX;
         for (size_t i = 0; i < cams.size(); ++i) {
             if (!used.count(cams[i].name)) continue;
-            images[cams[i].name] = {px[i].data(), int(cams[i].width), int(cams[i].height), int(cams[i].width)};
+            images[rename(cams[i].name)] = {px[i].data(), int(cams[i].width), int(cams[i].height), int(cams[i].width)};
             uint64_t &ti = std::string(cams[i].name).rfind("color_", 0) == 0 ? t_color : t;
             ti = std::min(ti, cams[i].capture_ns);
         }
@@ -199,6 +248,30 @@ int main(int argc, char **argv) {
             busy_ms += ms;
             busy_until = t + uint64_t(ms * slow * 1e6) + 3'000'000;   // + the ring hand-off
             const std::vector<Seen> seen = tracker.views_now();
+            if (first_hand_ts < 0 && !seen.empty()) first_hand_ts = ts;
+            std::vector<Seen> side_views = seen;
+            if (checking)
+                for (Seen &v : side_check.probe(nets, pool, images, seen, int64_t(t))) side_views.push_back(v);
+            if (checking && side_check.add(side_views, int64_t(t)) > 0 && side_check.verdict() != SideCheck::Undecided) {
+                const bool backwards = side_check.verdict() == SideCheck::Swapped;
+                char line[400];
+                std::snprintf(line, sizeof line, "side cameras: %s %s at %.1f s (%.1f s after the first hand; %s)\n",
+                              side_round ? "check" : "decision",
+                              backwards ? (sides == "auto" ? "SWAPPED, exchanged" : "SWAPPED") : "as named", ts,
+                              ts - first_hand_ts, side_check.summary().c_str());
+                side_report += line;
+                if (tl) std::fprintf(tl, "%.3f %s", ts, line);
+                if (sides != "auto") {
+                    checking = false;   // file, 0, 1: report only
+                } else if (side_round == 0 || backwards) {
+                    if (backwards) names_swapped = !names_swapped, tracker.exchange("slam_left", "slam_right");
+                    side_check.reset();
+                    side_check.min_clean = 20, side_check.min_votes = 40;
+                    checking = ++side_round < 3;
+                } else {
+                    checking = false;
+                }
+            }
             grip.update(out, seen, int64_t(t));
             pinch.update(out, seen, int64_t(t), grip.gripping());
             next_ns = t + uint64_t((std::min(tracker.interval(), pinch.engaged() || grip.engaged() ? 1 / 30.0 : 1.0) - 0.005) * 1e9);
@@ -361,6 +434,12 @@ int main(int argc, char **argv) {
         std::printf("palm jitter (off a straight line through the last two updates): measured median %.1f mm, 90%% %.1f mm; "
                     "published median %.1f mm, 90%% %.1f mm\n", jit_raw[jit_raw.size() / 2], jit_raw[jit_raw.size() * 9 / 10],
                     jit_sm[jit_sm.size() / 2], jit_sm[jit_sm.size() * 9 / 10]);
+    if (!side_check.usable())
+        std::printf("side cameras: not both in this recording\n");
+    else
+        std::printf("%sside cameras %s: %s\n", side_report.c_str(), side_report.empty() ? "undecided" : "at the end",
+                    checking || side_report.empty() ? side_check.summary().c_str()
+                                                    : names_swapped ? "exchanged from the recorded names" : "as recorded");
     if (o_sets) {
         std::printf("oracle, %d sets: a left hand findable in %d, the tracker had it in %d (%.0f%%); right %d, had %d (%.0f%%)\n",
                     o_sets, o_left, o_left_hit, 100.0 * o_left_hit / std::max(o_left, 1), o_right, o_right_hit,
diff --git a/hands/track/sides.cpp b/hands/track/sides.cpp
new file mode 100644
index 0000000..fcc3490
--- /dev/null
+++ b/hands/track/sides.cpp
@@ -0,0 +1,216 @@
+#include "sides.h"
+
+#include <algorithm>
+#include <cmath>
+#include <cstdio>
+#include <cstdlib>
+#include <functional>
+
+namespace {
+
+bool is_side(const std::string &name) { return name == "slam_left" || name == "slam_right"; }
+
+double median(std::vector<double> v) {
+    if (v.empty()) return -1;
+    std::nth_element(v.begin(), v.begin() + v.size() / 2, v.end());
+    return v[v.size() / 2];
+}
+
+constexpr int kMaxPairs = 12;          // per step
+constexpr int kMinFront = 15;          // of 21 landmarks: rays meeting in front of both cameras
+constexpr double kNear = 0.05, kFar = 1.5;      // m along each ray: where a hand can be
+constexpr double kRatioLo = 0.6, kRatioHi = 1.9;   // as Tracker's size check (tracker.cpp)
+constexpr double kProbeDepths[] = {0.8, 1.0, 1.25};   // probe(): times the one-view distance
+
+}  // namespace
+
+SideCheck::SideCheck(const std::map<std::string, Camera> &cams) {
+    for (const auto &[name, cam] : cams) cams_[name] = &cam;
+    if (cams_.count("slam_left")) left_ = cams_["slam_left"];
+    if (cams_.count("slam_right")) right_ = cams_["slam_right"];
+}
+
+const Camera *SideCheck::cam(const std::string &name, bool swapped) const {
+    if (swapped && name == "slam_left") return right_;
+    if (swapped && name == "slam_right") return left_;
+    const auto it = cams_.find(name);
+    return it == cams_.end() ? nullptr : it->second;
+}
+
+double SideCheck::miss(const Camera &ca, const Landmarks &a, const Camera &cb, const Landmarks &b) const {
+    std::vector<double> d;
+    V3 palm{};
+    bool have_palm = false;
+    for (int k = 0; k < 21; ++k) {
+        const V3 oa = ca.origin, da = ca.ray(a.pts[k]), ob = cb.origin, db = cb.ray(b.pts[k]);
+        const V3 w = oa - ob;
+        const double ab = dot(da, db), p = dot(da, w), q = dot(db, w), den = 1 - ab * ab;
+        if (den < 1e-9) continue;   // parallel rays
+        const double ta = (ab * q - p) / den, tb = (q - ab * p) / den;
+        if (ta < kNear || tb < kNear || ta > kFar || tb > kFar) continue;
+        const V3 pa = oa + da * ta, pb = ob + db * tb;
+        d.push_back(norm(pa - pb));
+        if (k == 9) palm = (pa + pb) * 0.5, have_palm = true;
+    }
+    if (int(d.size()) < kMinFront || !have_palm) return -1;
+    // as far from each camera as the hand's apparent size says (a hand of the model's size)
+    for (const auto &[c, lm] : {std::pair<const Camera *, const Landmarks *>{&ca, &a}, {&cb, &b}}) {
+        V3 mono[21];
+        if (!Tracker::single_view(*c, *lm, 1.0, mono)) return -1;
+        const double r = norm(palm - c->origin) / std::max(norm(mono[9] - c->origin), 1e-6);
+        if (r < kRatioLo || r > kRatioHi) return -1;
+    }
+    return median(d);
+}
+
+SideCheck::Miss SideCheck::test(const std::string &cam_a, const Landmarks &a, const std::string &cam_b,
+                                const Landmarks &b) const {
+    Miss out{{-1, -1}};
+    for (int way = 0; way < 2; ++way) {
+        const Camera *ca = cam(cam_a, way == 1), *cb = cam(cam_b, way == 1);
+        if (ca && cb) out.m[way] = miss(*ca, a, *cb, b);
+    }
+    return out;
+}
+
+int SideCheck::vote(const Miss &m) {
+    for (int w = 0; w < 2; ++w) {
+        const double win = m.m[w], other = m.m[1 - w];
+        if (win >= 0 && win < kGood && (other < 0 || other > kClear * win)) return w;
+    }
+    return -1;
+}
+
+int SideCheck::add(const std::vector<Seen> &views, int64_t t_ns) {
+    if (!usable()) return 0;
+    std::vector<const Seen *> vs;
+    for (const Seen &v : views)
+        if (cams_.count(v.cam)) vs.push_back(&v);
+    int pairs = 0, voted = 0;
+    for (size_t i = 0; i < vs.size(); ++i)
+        for (size_t j = i + 1; j < vs.size() && pairs < kMaxPairs; ++j) {
+            if (vs[i]->cam == vs[j]->cam || (!is_side(vs[i]->cam) && !is_side(vs[j]->cam))) continue;
+            ++pairs;
+            const Miss m = test(vs[i]->cam, vs[i]->lm, vs[j]->cam, vs[j]->lm);
+            const int v = vote(m);
+            if (v < 0) continue;
+            ++votes[v], ++voted;
+            misses_[0].push_back(m.m[0]), misses_[1].push_back(m.m[1]);
+            if (first_ns_ < 0) first_ns_ = t_ns;
+            last_ns_ = t_ns;
+        }
+    return voted;
+}
+
+std::vector<Seen> SideCheck::probe(const Nets &nets, Pool &pool, const std::map<std::string, Image> &images,
+                                   const std::vector<Seen> &views, int64_t t_ns) {
+    if (!usable() || (probe_ns_ >= 0 && (t_ns - probe_ns_) / 1e9 < probe_interval_s - 0.01)) return {};
+    struct Job {
+        int way;
+        std::string cam;
+        Roi roi;
+        Landmarks lm;
+    };
+    std::vector<Job> jobs;
+    // the views to look from: confident ones, a different hand each time (round robin)
+    std::vector<const Seen *> order;
+    for (const Seen &v : views)
+        if (cams_.count(v.cam) && v.lm.presence >= 0.5) order.push_back(&v);
+    std::sort(order.begin(), order.end(), [](const Seen *a, const Seen *b) { return a->lm.presence > b->lm.presence; });
+    if (!order.empty()) std::rotate(order.begin(), order.begin() + (probe_turn_++ % order.size()), order.end());
+    // Only the other naming: the tracker hands hands over to the other cameras under the names
+    // as they are every step, and add() tests what that finds.
+    for (int way = 1; way < 2; ++way) {
+        bool found = false;
+        for (const Seen *v : order) {
+            for (const char *target : {"slam_left", "slam_right"}) {
+                if (v->cam == target || !images.count(target)) continue;
+                bool paired = false;   // the tracker has this hand there already: add() tests that pair
+                for (const Seen &u : views) paired = paired || (u.cam == target && u.hand == v->hand && v->hand > 0);
+                if (paired) continue;
+                const Camera *cs = cam(v->cam, way == 1), *ct = cam(target, way == 1);
+                V3 pts[21];
+                if (!cs || !ct || !Tracker::single_view(*cs, v->lm, 1.0, pts)) continue;
+                // the hand at a few distances around the one-view guess, as the tracker hands
+                // a hand over to another camera (a crop around where its landmarks land)
+                const V3 axis{ct->R[0][2], ct->R[1][2], ct->R[2][2]}, o = cs->origin;
+                for (double f : kProbeDepths) {
+                    V2 uv[21];
+                    bool visible = true;
+                    for (int k = 0; k < 21; ++k) {
+                        const V3 p = o + (pts[k] - o) * f;
+                        visible = visible && dot(unit(p - ct->origin), axis) > 0.17;   // within 80 degrees
+                        uv[k] = ct->project(p, nullptr);
+                    }
+                    const V2 c = uv[9];
+                    if (!visible || c[0] < 0 || c[1] < 0 || c[0] >= ct->width || c[1] >= ct->height) continue;
+                    jobs.push_back({way, target, roi_from_points(uv), {}});
+                    found = true;
+                }
+                if (found) break;
+            }
+            if (found) break;
+        }
+    }
+    if (jobs.empty()) return {};
+    probe_ns_ = t_ns;
+    std::vector<std::function<void()>> run;
+    for (Job &j : jobs) run.push_back([&nets, &images, &j] { j.lm = nets.landmarks(images.at(j.cam), j.roi); });
+    pool.run(run);
+    static const bool debug = std::getenv("FT_SIDES_DEBUG") != nullptr;
+    std::vector<Seen> out;
+    probes += int(jobs.size());
+    for (int way = 1; way < 2; ++way) {   // the best look
+        const Job *best = nullptr;
+        for (const Job &j : jobs)
+            if (j.way == way && (!best || j.lm.presence > best->lm.presence)) best = &j;
+        if (debug && best)
+            std::fprintf(stderr, "side probe (%s) %s at %.0f %.0f size %.0f: presence %.2f\n", way ? "swapped" : "as named",
+                         best->cam.c_str(), best->roi.center[0], best->roi.center[1], best->roi.size, best->lm.presence);
+        if (!best || best->lm.presence < 0.5) continue;
+        ++probe_hits;
+        out.push_back(Seen{best->cam, 0, best->roi, best->lm, {}});
+    }
+    return out;
+}
+
+SideCheck::Verdict SideCheck::verdict() const {
+    const int total = votes[0] + votes[1], w = votes[0] >= votes[1] ? 0 : 1;
+    const bool clean = votes[1 - w] == 0 && votes[w] >= min_clean;
+    const bool clear = votes[w] >= min_votes && votes[1 - w] <= max_other * total;
+    if (!(clean || clear) || span_s() < min_span_s) return Undecided;
+    return w == 0 ? AsNamed : Swapped;
+}
+
+void SideCheck::reset() {
+    votes[0] = votes[1] = 0;
+    probes = probe_hits = 0;
+    probe_ns_ = -1;
+    misses_[0].clear(), misses_[1].clear();
+    first_ns_ = last_ns_ = -1;
+}
+
+double SideCheck::median_miss_mm(int way) const {
+    std::vector<double> v;
+    for (double m : misses_[way])
+        if (m >= 0) v.push_back(m * 1000);
+    return median(v);
+}
+
+std::string SideCheck::summary() const {
+    char s[320];
+    std::snprintf(s, sizeof s,
+                  "votes as named %d, swapped %d, over %.1f s; median ray miss as named %.1f mm, swapped %.1f mm "
+                  "(-1: never met); probes %d, found %d",
+                  votes[0], votes[1], span_s(), median_miss_mm(0), median_miss_mm(1), probes, probe_hits);
+    return s;
+}
+
+std::string SideCheck::json() const {
+    char s[320];
+    std::snprintf(s, sizeof s,
+                  "{\"as_named\": %d, \"swapped\": %d, \"seconds\": %.2f, \"miss_mm\": [%.1f, %.1f], \"probes\": %d, "
+                  "\"found\": %d}",
+                  votes[0], votes[1], span_s(), median_miss_mm(0), median_miss_mm(1), probes, probe_hits);
+    return s;
+}
diff --git a/hands/track/sides.h b/hands/track/sides.h
new file mode 100644
index 0000000..972c279
--- /dev/null
+++ b/hands/track/sides.h
@@ -0,0 +1,94 @@
+// Are the side cameras' images under the right names? ft-camd tells slam_left's buffers from
+// slam_right's only by the order XRService allocated them, and some XRService starts reverse
+// that order: then each side camera's images carry the other's name, every hand is seen by one
+// camera only, at the wrong depth, and the cutouts land beside the hands.
+//
+// SideCheck tells from the hands the tracker already finds. Whenever a hand's landmarks are
+// found in two cameras in the same frame set (one of them a side camera), the rays through its
+// 21 landmarks are intersected twice: with the calibrations as the images are named, and with
+// the two side cameras' calibrations exchanged. The same hand seen right meets within a few mm,
+// in front of both cameras and as far away as its apparent size says; under the wrong naming
+// the rays miss by centimetres or meet behind a camera. Each such pair is a vote. It decides once
+// one way has min_clean votes and the other none, or min_votes with at most max_other of all
+// votes the other way, over at least min_span_s of hands.
+//
+// The tracker's own views rarely give a pair when the names are wrong: it hands a hand over
+// to the other cameras where the wrong calibration puts it, finds nothing there, and keeps it in
+// one camera (the replays of swapped recordings: one hand, every handoff a miss, no pair). So
+// probe() looks for itself, 5 times a second while it's checking: it takes a hand the tracker
+// sees, places it in 3D from that one view (as far as its size says) with the side cameras
+// exchanged, and runs the landmark model where that puts it in the other side camera, at 0.8,
+// 1 and 1.25 times the one-view distance. That's the tracker's handoff under the other naming
+// (the tracker does it under the current one every step); the palm detector misses many of
+// these hands, which the landmark model finds from a good crop. What it finds is a view
+// like the tracker's, and the test above votes on it: finding a hand there proves nothing by
+// itself. It doesn't depend on how the tracker paired the views up.
+//
+// FT_SIDES_DEBUG=1 in the environment prints each probe's crop and what it found (stderr).
+//
+// Upper-camera pairs with a side camera count too (the upper pair's own naming was checked
+// stable: tools/check_sides.py --pair upper). Two upper views alone say nothing.
+#pragma once
+
+#include "tracker.h"
+
+#include <map>
+#include <string>
+#include <vector>
+
+class SideCheck {
+public:
+    enum Verdict { Undecided, AsNamed, Swapped };
+
+    // cams: the mono cameras' calibrations; slam_left and slam_right are needed.
+    explicit SideCheck(const std::map<std::string, Camera> &cams);
+    bool usable() const { return left_ && right_; }
+
+    // One step's fresh views (Tracker::views_now, plus probe()'s), cameras named as the
+    // images are now. Returns how many pairs voted.
+    int add(const std::vector<Seen> &views, int64_t t_ns);
+    // At most every probe_interval_s: for each naming, one view the tracker has, looked for in
+    // the other side camera where that naming puts it (see the top). Returns the views found
+    // (presence 0.5 or more), for add() with the tracker's. Runs the models on pool.
+    std::vector<Seen> probe(const Nets &nets, Pool &pool, const std::map<std::string, Image> &images,
+                            const std::vector<Seen> &views, int64_t t_ns);
+    double probe_interval_s = 0.2;
+    int probes = 0, probe_hits = 0;   // landmark model runs, and the views they found
+
+    // One pair: the median landmark ray miss (m) as named [0] and with the side cameras
+    // exchanged [1]; -1 where they can't be one hand that way (rays meet behind a camera, or
+    // at a distance the hand's apparent size rules out). For tests.
+    struct Miss {
+        double m[2];
+    };
+    Miss test(const std::string &cam_a, const Landmarks &a, const std::string &cam_b, const Landmarks &b) const;
+    // The vote for a Miss: 0 as named, 1 swapped, -1 neither.
+    static int vote(const Miss &m);
+
+    Verdict verdict() const;
+    void reset();
+
+    // Evidence so far
+    int votes[2] = {0, 0};
+    double span_s() const { return first_ns_ >= 0 ? (last_ns_ - first_ns_) / 1e9 : 0; }
+    double median_miss_mm(int way) const;   // over the voted pairs; -1 if none met that way
+    std::string summary() const;            // for the log
+    std::string json() const;               // for the sides file and recordings
+
+    // The rule (see the top)
+    int min_clean = 10, min_votes = 20;
+    double min_span_s = 1.0, max_other = 0.2;
+    static constexpr double kGood = 0.015;   // m: a pair's median miss to count as meeting
+    static constexpr double kClear = 3.0;    // both meet: one must miss this many times less
+
+private:
+    const Camera *cam(const std::string &name, bool swapped) const;
+    double miss(const Camera &ca, const Landmarks &a, const Camera &cb, const Landmarks &b) const;
+
+    std::map<std::string, const Camera *> cams_;
+    const Camera *left_ = nullptr, *right_ = nullptr;
+    std::vector<double> misses_[2];   // per voted pair, each way (-1: implausible)
+    int64_t first_ns_ = -1, last_ns_ = -1;   // the first and last vote
+    int64_t probe_ns_ = -1;
+    unsigned probe_turn_ = 0;
+};
diff --git a/hands/track/tracker.cpp b/hands/track/tracker.cpp
index 2e8169f..c7ed81d 100644
--- a/hands/track/tracker.cpp
+++ b/hands/track/tracker.cpp
@@ -162,7 +162,7 @@ void Tracker::run_landmarks(const std::map<std::string, Image> &images, std::vec
     ++stats.hand_batches;
 }
 
-bool Tracker::single_view(const Camera &cam, const Landmarks &lm, double scale, V3 out[21]) const {
+bool Tracker::single_view(const Camera &cam, const Landmarks &lm, double scale, V3 out[21]) {
     V3 rays[21];
     for (int i = 0; i < 21; ++i) rays[i] = cam.ray(lm.pts[i]);
     std::vector<std::pair<double, double>> est;   // (depth, weight)
@@ -556,6 +556,13 @@ std::vector<Seen> Tracker::views_now() const {
     return out;
 }
 
+void Tracker::exchange(const std::string &a, const std::string &b) {
+    if (!cams_.count(a) || !cams_.count(b)) return;
+    const Camera *ca = cams_[a], *cb = cams_[b];
+    for (View &v : views_) v.cam = v.cam == ca ? cb : v.cam == cb ? ca : v.cam;
+    for (auto &[id, h] : hands_) h.has_pts = false, h.frames = 0, h.residual = -1;
+}
+
 void Tracker::drop_camera(const std::string &name) {
     views_.erase(std::remove_if(views_.begin(), views_.end(), [&](const View &v) { return v.cam->name == name; }),
                  views_.end());
diff --git a/hands/track/tracker.h b/hands/track/tracker.h
index 18930bf..b7f3342 100644
--- a/hands/track/tracker.h
+++ b/hands/track/tracker.h
@@ -95,7 +95,11 @@ public:
     void set_keep_presence(double p) { keep_presence_ = p; }
     // One view's 3D hand: each landmark along its ray, as far as how big the palm looks says
     // for a hand `scale` times the model's (Hand::scale). False if the palm is degenerate.
-    bool single_view(const Camera &cam, const Landmarks &lm, double scale, V3 out[21]) const;
+    static bool single_view(const Camera &cam, const Landmarks &lm, double scale, V3 out[21]);
+    // Cameras a and b's images were under each other's names (the side cameras, track/sides.h):
+    // each view moves to the other camera (its crop is in the image's pixels, so it keeps
+    // following its hand), and every hand's 3D starts over from its views at the next step.
+    void exchange(const std::string &a, const std::string &b);
 
 private:
     struct View {
diff --git a/setup/dev-container.sh b/setup/dev-container.sh
index 10229ba..61f961f 100755
--- a/setup/dev-container.sh
+++ b/setup/dev-container.sh
@@ -23,6 +23,9 @@ packages=(
   # tools (hands/tools) need NumPy and OpenCV, which aren't here: Fedora's python3-opencv pulls
   # in over a gigabyte (hands/README.md says how to get them)
   jsoncpp-devel glibc-static
+  # hand recorder (hands/rec): its export compresses recordings with zstd; its Upload page and
+  # hub.py upload to Hugging Face with huggingface_hub (also the hf command, for hf auth login)
+  zstd python3-huggingface-hub
   # Frametop Input Settings app (Kirigami, PySide6)
   python3-pyside6 kf6-kirigami kf6-qqc2-desktop-style qt6-qtwayland breeze-icon-theme plasma-breeze
   # Frametop remote desktop (VNC bridge through krdp)