Make hand tracking a Frametop component

- Programs: ft-camd (the camera broker), ft-hands (the tracker), and
  ft-handreplay and ft-ringplay for recordings, built by hands/build.sh
  into hands/build/ with one Makefile. The first build fetches ncnn at
  frame-hands' pinned tag and builds it with the same options.
- ft-camd gets its privileges from file capabilities (CAP_SYS_PTRACE,
  CAP_PERFMON, CAP_DAC_READ_SEARCH) that hands/run.sh install sets with
  sudo, and drops them once set up. It still works under sudo. It runs
  on the host, linked statically, as frametop-camd.service. ft-hands
  runs in the dev container as frametop-hands.service. Both start and
  stop with SteamVR.
- Files move to /run/user/UID/frametop/ (cam-ring, hands, gestures),
  not $XDG_RUNTIME_DIR, which a terminal in the Frametop desktop has
  its own of. SIGUSR1 recordings go to ~/.local/share/frametop/hands.
- The calibration is read through /run/host in the container.
- Settings: HANDS_SWAP_SIDES and HANDS_CPUS in frametop.conf.
- install.sh offers hand tracking as an optional last step.
- The container gets jsoncpp-devel, glibc-static, and NumPy and OpenCV
  for the Python tools.
- tools/ring.py reads the ring, and models/NOTICE credits the
  Apache-2.0 models.

Checked: ft-handreplay gives identical summaries and byte-identical
depth dumps to frame-hands' fh-replay on both 2026-09-29 recordings.

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

hands/run.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Install, start, stop, or inspect hand tracking on the Frame: ft-camd (the camera broker) and
+# ft-hands (the tracker), user services that start and stop with SteamVR.
+# Usage: hands/run.sh install|uninstall
+#        hands/run.sh caps      # give ft-camd its capabilities again (a rebuild clears them)
+#        hands/run.sh start|stop|restart|status|log [lines]
+# install and caps need the password (sudo setcap, once per build of ft-camd). On the Frame,
+# sudo asks in the terminal. From a PC (or with no terminal), the password comes from
+# steamos_root_pwd in the repo's .env and is sent to sudo -S on stdin, never on a command line.
+set -euo pipefail
+root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+. "$root/scripts/_env.sh"
+frame="$root/scripts/frame.sh"
+units="frametop-camd.service frametop-hands.service"
+# pidfd_getfd on XRService (ptrace_scope=1), system-wide tracepoints, and their root-only
+# format files. ft-camd drops them all once it has set up.
+caps=cap_sys_ptrace,cap_perfmon,cap_dac_read_search+ep
+
+sudo_run() {
+  if [ "$FRAME_LOCAL" = 1 ] && [ -t 0 ]; then
+    sudo bash -c "$1"  # asks for the password here
+    return
+  fi
+  local pw
+  pw=$(sed -n 's/^steamos_root_pwd=//p' "$root/.env" 2>/dev/null)
+  pw=${pw#[\"\']}; pw=${pw%[\"\']}  # .env values may be quoted
+  [ -n "$pw" ] || { echo "no terminal for sudo, and steamos_root_pwd is missing from $root/.env" >&2; exit 1; }
+  printf '%s\n' "$pw" | on_frame "sudo -S -p '' bash -c $(printf %q "$1")"
+}
+
+set_caps() {
+  local bin
+  bin=$(printf %q "$FRAME_REPO/hands/build/ft-camd")
+  sudo_run "setcap $caps $bin && getcap $bin"
+}
+
+states="for u in $units; do echo \"\$u: \$(systemctl --user is-active \$u)\"; done"
+
+case ${1:-status} in
+  install)
+    "$root/hands/build.sh"
+    set_caps
+    for u in $units; do
+      fill_template "$root/hands/$u" | on_frame "mkdir -p ~/.config/systemd/user && cat > ~/.config/systemd/user/$u"
+    done
+    "$frame" --host "set -e; systemctl --user daemon-reload; systemctl --user enable $units
+if systemctl --user -q is-active steamvr.service; then systemctl --user restart $units; sleep 5; fi
+$states" ;;
+  caps) set_caps ;;
+  uninstall) "$frame" --host "systemctl --user disable --now $units 2>/dev/null
+for u in $units; do rm -f ~/.config/systemd/user/\$u; done; systemctl --user daemon-reload; echo removed" ;;
+  start|stop|restart) "$frame" --host "systemctl --user $1 $units; $states" ;;
+  status) "$frame" --host "$states; journalctl --user -u frametop-hands.service --no-pager -o cat -n 4" || true ;;
+  log) "$frame" --host "journalctl --user -u frametop-camd.service -u frametop-hands.service --no-pager -o short -n ${2:-30}" ;;
+  *) echo "usage: $0 install|uninstall|caps|start|stop|restart|status|log [lines]" >&2; exit 2 ;;
+esac