fix(tracking): don't call an unworn eye-camera artifact a pulse

Unworn Frame runs gave a steady 'clear' 90-96 BPM. pulse now reads the
proximity sensor and refuses to report when the headset is not worn.

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

docs/tracking.md

@@ -218,14 +218,22 @@ How it works:
   far off an unclear result was.
   The thresholds are provisional until checked on real wearers.
 
-**Verified on the Frame, unworn, 2026-09-29:** a 30-second run captured
-5,362 eye frames, never had more than 7 images on disk, finished 3 s after
-the capture ended and left no capture directory. It reported no clear pulse
-(exit 3), as it should with nobody wearing it. Worth knowing: the unworn
-patches agreed on a steady rhythm near 127-129 BPM (about 2.1 Hz) with low
-signal/noise (0.15-0.19), in two separate runs. That is a camera or illumination artifact, not a pulse,
-and the signal/noise gate kept it from being reported. A worn test should
-also record an unworn baseline, to rule out the same artifact.
+**Verified on the Frame, unworn, 2026-09-29:** captures of 3,600-5,400 eye
+frames never had more than 8 images on disk, finished a few seconds after the
+capture ended and left no capture directory. **The estimator alone gave a
+false "clear" pulse.** With nobody wearing the headset, five runs reported a
+steady, self-consistent rhythm (90, 90, 93, 94 and 96 BPM; patch agreement
+100%, signal/noise 0.63-0.70), and earlier runs reported 127-129 BPM at lower
+signal/noise. It is a periodic camera or illumination artifact, and its
+frequency drifts between runs. A wearer-less scene cannot contain a pulse, so
+the signal/noise gate cannot tell this artifact from one. Because of that,
+`pulse` reads the Frame's proximity sensor (`vcnl4000`) before and after the
+capture. It reads about 3 unworn (**verified**). If either reading is below 20
+the result is never called clear, nothing is sent over OSC, and the command
+exits 3. **Inferred, unmeasured:** that a worn reading is well above 20; the
+cut-off is provisional until someone wears the headset. If the sensor can't be
+read, the guard is skipped. Confirming a real pulse also needs a reference
+(below).
 
 **Do not interrupt the capture. Verified on the Frame, 2026-09-29:** sending
 SIGTERM to `eyetracking --calib` left the DSP service's eye camera (OV6211)

frame/tracking/pulse.py

@@ -29,6 +29,10 @@ ET_WEIGHTS = ET_DIR / "resources/et_dsp_20250610_03136.weights"
 GRID = 16        # 16 × 16 patches of 25 × 25 pixels on the 400 × 400 image
 RATE = 15.0      # analysis sample rate, Hz; the band of interest ends at 3 Hz
 LOW, HIGH = 42.0, 180.0  # BPM search band
+# The Frame's proximity sensor (vcnl4000) reads about 3 with nobody wearing it.
+# A worn reading has not been measured yet, so the cut-off is provisional.
+IIO = Path("/sys/bus/iio/devices")
+WORN_MIN = 20.0
 WINDOW = 15.0    # seconds per windowed estimate
 
 
@@ -449,6 +453,22 @@ def analyse(frames):
     return estimate(times, patches)
 
 
+def proximity(root=None):
+    """The headset's proximity reading, or None if it can't be read."""
+    try:
+        for device in sorted(Path(root or IIO).glob("iio:device*")):
+            if (device / "name").read_text().strip() == "vcnl4000":
+                return float((device / "in_proximity_raw").read_text())
+    except (OSError, ValueError):
+        pass
+    return None
+
+
+def worn(reading):
+    """False only when the sensor says the headset is not on a face."""
+    return reading is None or reading >= WORN_MIN
+
+
 def reliable(result):
     """Whether the estimate is clear enough to show as a reading. Thresholds
     are provisional until checked against a reference on a real wearer."""

frame/tracking/tracking.py

@@ -347,8 +347,10 @@ def run_pulse(args, osc):
     if not pulse.ET_BIN.exists():
         raise TrackingError("SteamVR's eye-tracking tool is not installed on this Frame")
     print(f"Capturing {args.seconds} s from the eye cameras. Wear the headset and keep still.", flush=True)
+    readings = [pulse.proximity()]
     try:
         frames = pulse.Capture(args.seconds).run()
+        readings.append(pulse.proximity())
     except RuntimeError as error:  # capture status only; no image data
         raise TrackingError(str(error))
     print(f"Captured {len(frames)} eye frames; images already deleted. Analysing...", flush=True)
@@ -356,7 +358,12 @@ def run_pulse(args, osc):
         result = pulse.analyse(frames)
     except ValueError as error:
         raise TrackingError(str(error))
-    clear = pulse.reliable(result)
+    on_face = all(pulse.worn(reading) for reading in readings)
+    if not on_face:
+        # Unworn, the cameras still show a steady periodic artifact that looks
+        # like a pulse (verified on the Frame), so it is never called clear.
+        print("The proximity sensor says the headset is not being worn; no pulse can be read.")
+    clear = on_face and pulse.reliable(result)
     offset = time.time() - time.monotonic()  # the capture's timestamps are CLOCK_MONOTONIC
     if args.log:
         fd = os.open(args.log, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)

tests/test_pulse.py

@@ -176,6 +176,29 @@ class FakeCaptureTool:
         return self.returncode
 
 
+class WornCheck(unittest.TestCase):
+    def sensor(self, name, raw):
+        root = Path(self.enterContext(tempfile.TemporaryDirectory()))
+        device = root / "iio:device2"
+        device.mkdir()
+        (device / "name").write_text(name + "\n")
+        (device / "in_proximity_raw").write_text(raw + "\n")
+        return root
+
+    def test_reads_the_proximity_sensor(self):
+        self.assertEqual(pulse.proximity(self.sensor("vcnl4000", "3.250000000")), 3.25)
+
+    def test_unreadable_sensor_does_not_block(self):
+        self.assertIsNone(pulse.proximity(self.sensor("other", "9")))
+        self.assertIsNone(pulse.proximity(self.sensor("vcnl4000", "junk")))
+        self.assertIsNone(pulse.proximity(Path("/nonexistent")))
+        self.assertTrue(pulse.worn(None))
+
+    def test_low_reading_means_unworn(self):
+        self.assertFalse(pulse.worn(3.1))
+        self.assertTrue(pulse.worn(pulse.WORN_MIN))
+
+
 class CaptureLifecycle(unittest.TestCase):
     def setUp(self):
         self.root = Path(tempfile.mkdtemp())