commit 1c0b219c1900bf3a1992680459d54b889a287481
parent 6fc2356438adc4384dc4797e38b7253bc2b27cbc
Author: umhau <umhau@example.invalid>
Date: Wed, 21 Oct 2026 12:00:12 +0000
SETUP: dedicated Metal render worker, strict health metrics, current verified status
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Diffstat:
1 file changed, 13 insertions(+), 4 deletions(-)
diff --git a/SETUP.md b/SETUP.md
@@ -74,10 +74,19 @@ zsh tools/build.sh # builds the app + the signe
grace period, it runs that helper directly to send a USB-PD Data Reset to port 2's controller. No sudo, no password:
the kernel admits root OR that entitlement, and AMFI being off (`amfi_get_out_of_my_way=1`) lets an ad-hoc signature
carry it. Limits: 3 s helper timeout, at most 3 resets per minute.
-- The app captures the headset display (no desktop on it), uses its native unscaled 4320x2160 mode, and drives
- frames from the headset display's own refresh.
-- Status: automatic recovery verified (3/3 trials at 90 Hz). 90 Hz presentation rate is **still being verified**:
- earlier frame counts may have included skipped frames, so they are not yet counted as success.
+- The app captures the headset display (no desktop on it) and uses its native unscaled 4320x2160 @ 90 Hz mode.
+ If macOS changes the mode by itself, the app restores 90 Hz (also checked every 10 s, CoreGraphics only).
+- Rendering runs on a dedicated "Headset Metal rendering" thread: a `CAMetalDisplayLink` on that thread's run loop
+ hands each frame a ready drawable (no `nextDrawable` calls, nothing drawn on the main thread). The main thread only
+ handles AppKit and display connect/disconnect callbacks, so a stalled frame can no longer delay drop detection
+ (it previously did, by up to ~11 s). The depth buffer is created once and reused.
+- Health line every 10 s in the app log: `submitted`, `presented` (only frames Metal reports with a real
+ presentation time), `skipped`, `fps` (presented per second), `presentAge`, `GPUms` per frame, `GPUerrors`, IMU sample
+ count. Healthy looks like `fps=90.00 presentAge=0.01s GPUerrors=0` with `skipped` not increasing after startup.
+- Status (2026-10-20): automatic recovery verified (3/3 trials at 90 Hz, then from a stuck state with the render
+ worker). Render worker 35 s test: 89.90 presented fps, presentAge 0.01 s, GPU 1.47 ms/frame, 0 errors, 12 skips at
+ startup only. The user confirmed the 3D scene inside the headset (twice). A 660 s soak with injected faults is
+ in progress (`evidence/final-metal-worker-soak.txt`).
## How the boot-arg was found
`amfi_get_out_of_my_way` controls code signing, not HDCP, so we searched this Mac's own kernel: