Bump Frame Control to 0.4.18

* Never end playback over the cosmetic surround; always shut down OpenVR

Review (SWE-2 Max): a non-standby error re-sending the theatre surround
could end a healthy still, and a non-RuntimeError during DestroyOverlay
skipped VR_ShutdownInternal. drain() now drops a surround that fails for
other reasons, and close() shuts down in finally. Fake overlay handles no
longer depend on call order.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* Play without the theatre surround if SteamVR refuses it

Review (SWE-2 Max): a non-standby error creating the cosmetic surround
at startup still ended playback before the screen appeared. Theatre now
logs it and plays without the surround. close() treats any per-overlay
teardown error as best effort (signals are already ignored there).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* Verify media surround fallback and guard server startup ownership

* Record exact-head real Frame theatre playback smoke

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: SAPHID <saphid@users.noreply.github.com>

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+- Keep media playback running when SteamVR refuses the optional theatre dark
+  surround, including a retry after standby. Log the refusal and play without
+  the surround. Overlay teardown attempts every owned handle and always calls
+  OpenVR shutdown even if a handle fails to close.
+
+- Check the desktop server's single-instance lock before starting background
+  downloads, so a second server exits cleanly with the existing "already
+  running" message.
+
 - Recheck saved spatial layouts on SteamOS 0.5.6 / SteamVR 2.18.2 (issue #31).
   Read-only probes expose some panel geometry, but safe restoration of
   Steam/gamescope docking and positions remains unverified. Record exact API

app/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "frame-control",
-  "version": "0.4.17",
+  "version": "0.4.18",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "frame-control",
-      "version": "0.4.17",
+      "version": "0.4.18",
       "license": "MIT",
       "devDependencies": {
         "electron": "^44.4.5",

app/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frame-control",
   "productName": "Frame Control",
-  "version": "0.4.17",
+  "version": "0.4.18",
   "description": "Desktop app for managing a Valve Steam Frame over SSH",
   "private": true,
   "main": "main.js",

docs/evidence/media-surround-2026-10-24.md

@@ -0,0 +1,142 @@
+# Media surround hardening: 2026-10-24
+
+PR [#51](https://github.com/saphid/frame-control/pull/51), branch
+`theatre-media-surround-hardening`, merged main `2ded4c5` without rebasing.
+Both fixes remain necessary on that main: an optional-surround error escapes
+`play()`, and a non-`RuntimeError` during overlay teardown skips the remaining
+handles and OpenVR shutdown.
+
+## Offline checks
+
+- Focused media suite: **23 tests passed** on Linux / Python 3.12.3.
+- Final full suite: **1,381 tests, OK (15 skipped)** in 145.384 s with
+  `PYTHONFAULTHANDLER=1 python3 -m unittest discover -s tests -v`.
+  The service-regression module passed **33 tests**. Player/server compilation
+  and `git diff --check` passed. Current macOS/Windows validation is left to CI.
+- The startup/upload, creation/setup, deferred-surround refusal and teardown
+  regression tests were also run with main's player implementation: they
+  failed as expected (six errors across subtests). The screen-refusal test
+  passed, confirming that actual screen failures still propagate.
+- The historical macOS failure was job
+  [109239733717](https://github.com/saphid/frame-control/actions/runs/36516462623/job/109239733717),
+  on `dac9dbc`, Python 3.12: 619 tests, three failures in artwork resolver
+  tests (`test_resolver_slot_released_when_thread_cannot_start`,
+  `test_timed_out_lookups_are_capped`,
+  `test_url_fetch_refuses_private_hosts_and_honours_deadline`). Media tests
+  passed. Late DNS workers retained semaphore slots; the first failed
+  assertion could also leak acquired slots into later tests.
+- Main already contains `8051687`'s wait-for-idle and unconditional slot
+  cleanup, preserved by `d546568`. The current artwork module passed all
+  **40 tests** locally. No additional artwork changes were needed.
+- The first full run completed **1,380 tests, 15 skipped**, with one failure:
+  `test_a_second_server_is_refused_until_the_first_exits` observed SIGSEGV
+  (`-11`) instead of exit 1. All 41 server tests passed on a focused rerun.
+  Main started daemon index/TLS workers before refusing a second server;
+  its existing shutdown notes document a race with OpenSSL interpreter exit.
+  This crash mechanism is inferred; the first run did not retain a native
+  fault trace. The subprocess assertion now retains stderr for diagnosis.
+  A deterministic regression now checks that rejection starts no listener,
+  cleanup sweep or background workers. It failed before moving the ownership
+  check ahead of startup work and passed afterwards.
+
+The surround retry now logs a refusal before discarding that cosmetic work.
+Creation, setup and first-upload failures also allow the screen to play;
+standby remains retryable, and screen errors remain fatal. Teardown tests
+exercise OpenVR errors, unexpected exceptions and a late `InterruptedError`,
+checking that all handles are attempted and shutdown runs.
+
+## Earlier blocked real Frame attempt
+
+Read-only SSH preflight: SteamOS **0.5.6**, BUILD_ID **20261015.6141207**;
+SteamVR server PID **297506**, compositor PID **297620**; existing media
+service `inactive/dead`, MainPID 0; battery **99%**, fuel gauge `Not charging`,
+charger `Full`. The shared lock was absent at preflight.
+
+The subsequent atomic `mkdir /tmp/frame-test.lock` failed with
+`FileExistsError(17, 'File exists')`: another session acquired it in between.
+The probe stopped before uploading files, launching media, creating overlays,
+or changing any state. The foreign lock was neither modified nor released.
+All generated fixtures remained on the computer and were then removed; no
+headset cleanup was necessary. Steam/SteamVR and the prior player state were
+left alone.
+
+## Follow-up real Frame smoke at the exact PR head
+
+**Passed, 2026-10-24 10:35:02–10:35:23 UTC**, with byte-identical media modules
+from **`5d551a81658d9ff14f49285c28609d506cbc20aa`**. This later run resolves
+the earlier lack of fresh playback evidence. No production code changed.
+The headset was unworn. SteamOS **0.5.6**, BUILD_ID **20261015.6141207**,
+SteamVR **2.18.2**; battery **100%, Full** before and after.
+
+Read-only preflight found Game Mode (`XDG_CURRENT_DESKTOP=gamescope`,
+`start-gamescope` running, no `plasmashell`), Steam/SteamVR running, no media
+overlays, and the installed media service inactive/not loaded. The test then
+acquired `/tmp/frame-test.lock` with atomic `mkdir`; it did not take over a
+foreign lock. Under the lock, those safety conditions were checked again.
+
+Only generated media and the PR's four unchanged modules were uploaded, under
+the test-owned, uid-1000 directory
+`/tmp/pr51-5d551a8-4c0976a52564-utfbk_m0/`. The clip was a **12 s, 30 fps,
+960×540 half-SBS H.264** MP4 with solid red/cyan eye images and **silent AAC**.
+It was generated with FFmpeg's `color`, `hstack` and `anullsrc` sources; no
+personal or external media was used.
+
+The exact `frame_media_remote.run()` Play/status/Stop path was exercised by
+importing its unmodified module and changing only its in-memory `ROOT`,
+`RUNTIME`, `STATUS` and `UNIT` constants to the isolated test locations and
+`frame-control-media-pr51-5d551a8-4c0976a52564.service`. The real
+`frame_media_player.py` ran unchanged with `--layout auto --theatre`, using
+`h264_v4l2m2m` and Pulse output. This checks the player and its systemd lifecycle;
+it does **not** reverify the HTTP/UI upload or runtime installer, nor the
+literal production unit name. The installed media runtime, log, status and
+library were preserved.
+
+- First Play: `starting` → `playing` → **`ended`**, **360 frames**, **160 dropped**,
+  **12.0397 s**, `running=false`. The drops were the normal unworn/standby
+  `SetOverlayRaw` retry path; no fault was forced. At 60 frames, dropped was 0.
+  `vrcmd --overlays` listed `framecontrol.media.surround` as **1×1 visible**
+  and `framecontrol.media.screen` as **visible**. These are SteamVR metadata,
+  not a wearer or eye-capture verification.
+- After EOF: unit **inactive/dead, not-found, MainPID 0**, no test player or
+  decoder, and neither owned overlay remained. Stop after EOF succeeded and
+  retained `ended`.
+- Second Play reached `playing`, 60 frames, 0 dropped. Explicit Stop returned
+  **`stopped`, 72 frames, 0 dropped, `running=false`**. Again the unit was
+  inactive/dead/not-found with MainPID 0, no player/decoder and no owned overlays.
+- The test unit's `ExecStart` and cgroup identified the unique temporary
+  runtime. First-run player/decoder PIDs were **309650/309655**; second-run
+  PIDs were **309805/309810**. Stop controlled only this dedicated test unit.
+  Its player log was empty; no surround refusal or teardown error was logged.
+
+### Uploaded SHA-256 values
+
+```text
+generated_SBS.mp4      1b39cac1d3b092b89657250c817019b68e87a474976ccd44aeb38e8eee44ffca
+frame_media.py         001e3158f4c3931794846b21f1e4cb553349d9326b4db1454a01976d446ad97a
+frame_media_player.py  86b0a140ebff857c2819c74d3ac45d1897735c585d44c7360ad6f18c2ecf2645
+frame_media_remote.py  b60386eb192d32594358246a4e665474c543600f2c564c2efd554ef38d7a631d
+frame_splat.py         f35750926f1149c41b95617a302012406d355c0dfdd4530438b0c42ee6d55daa
+```
+
+### Cleanup and limits
+
+The temporary directory, including its fixture, code, bytecode, status and log,
+was removed only after verifying that its player and decoder had exited. The
+transient unit was collected. The test released only its own lock after cleanup.
+All installed media runtime file hashes, including `player.log` and
+`status.json`, were unchanged. The installed `frame-control-media.service`
+remained inactive/not loaded. Steam **297826**, vrserver **297506**,
+vrcompositor **297620**, vrdashboard **297721**, and start-gamescope **296997**
+kept the same PIDs. The pre-existing overlay key/dimension/visibility/type
+inventory matched the final inventory, and all dashboard main panels remained
+`not_visible`. No dashboard command, wake request, global setting, reboot or
+Steam/SteamVR stop was issued.
+
+Cosmetic surround refusal and exceptional teardown remain **fake-tested**;
+no real refusal or teardown fault was induced. This short unworn-headset
+smoke does not verify appearance, eye isolation, comfort, audible sound/lip
+sync (the AAC was silent), sustained display performance, or the issue #28
+report of laggy 1080p video. It does not cover new H.265, photo or splat cases.
+Historical checks remain in the earlier PR #51 description and
+[media playback notes](../vr-video.md). The PR remains draft and unmerged
+for parent review and CI.

docs/testing.md

@@ -382,7 +382,11 @@ trees on the fake Frame. None of it has run on a headset.
 
 `tests/test_media.py` covers layout evidence and overrides, OU eye ordering,
 hardware-decoder command construction, malformed splats, stereo parallax and
-fake-Frame library/process ownership. `tests/e2e/test_media_transfer.py` checks the real
+fake-Frame library/process ownership. It also covers optional-surround refusal
+at creation, setup, first upload and retry after standby, fatal screen refusal,
+and best-effort overlay teardown with shutdown.
+Run `python3 -m unittest discover -s tests -p test_media.py -v`.
+`tests/e2e/test_media_transfer.py` checks the real
 HTTP/SSH upload and library listing without pretending the fake renders VR.
 Real decode timings and captured stereo output are recorded in
 [vr-video.md](vr-video.md). Generated media only; no external player required.

docs/vr-video.md

@@ -101,6 +101,14 @@ Stills and the theatre surround are re-sent after waking. Five minutes
 without an accepted frame is reported as an error. Headset-view captures
 taken during standby show a flat dark frame, not our screen.
 
+**Optional surround:** if SteamVR refuses the theatre dark surround at startup
+or on a retry after standby, playback continues without it and the player log
+records `Theatre surround unavailable`. Screen errors still fail playback.
+On exit, the player attempts to destroy every owned overlay and calls OpenVR
+shutdown even if an overlay's teardown raises an exception. Refusal and
+teardown errors are covered by fake-OpenVR tests; a real surround refusal has
+not been induced safely. See the [current hardening checks](evidence/media-surround-2026-10-24.md).
+
 ![Media panel in Frame Control while a photo plays on the Frame](img/media-ui-panel.png)
 
 **Verified failed route:** GStreamer 1.24.2's `playbin` selected

tests/test_media.py

@@ -68,7 +68,7 @@ class Media(unittest.TestCase):
         self.assertIn('-frames:v', cmd)
 
     def play_with(self, name, busy=0, on_pixels=None, sleeps=None, info=None,
-                  fail=None, layout='auto'):
+                  fail=None, layout='auto', on_create=None, on_call=None):
         """Run the player against a fake OpenVR; returns (status, pixels calls).
 
         Handle 0 is the theatre surround and 1 the screen. `fail(handle, n)` makes
@@ -82,11 +82,18 @@ class Media(unittest.TestCase):
             write_status(path, **values)
 
         class FakeOverlay:
+            created = 0
+
             def create(self, *a, **k):
-                return len(calls)
+                # Handles in creation order: surround 0, then screen 1 (theatre).
+                FakeOverlay.created += 1
+                if on_create:
+                    on_create(*a, **k)
+                return FakeOverlay.created - 1
 
             def call(self, *a):
-                pass
+                if on_call:
+                    on_call(*a)
 
             def pixels(self, handle, data, w, h):
                 calls.append((handle, w, h))
@@ -132,6 +139,58 @@ class Media(unittest.TestCase):
         self.assertEqual(result['dropped'], 2)
         self.assertIn((0, 1, 1), calls[3:])
 
+    def test_theatre_surround_failure_does_not_stop_playback(self):
+        def fail_surround(n):
+            if n == 1:  # the surround's upload is the first pixels call
+                raise RuntimeError('OpenVR SetOverlayRaw failed: 11')
+        result, _ = self.play_with('clip_SBS.mp4', on_pixels=fail_surround)
+        self.assertEqual((result['state'], result['frames']), ('ended', 4))
+
+    def test_theatre_surround_creation_and_setup_failures_are_cosmetic(self):
+        def fail_create(key, *a, **k):
+            if key.endswith('.surround'):
+                raise RuntimeError('OpenVR CreateOverlay failed: 11')
+        def fail_alpha(name, *a):
+            if name == 'SetOverlayAlpha':
+                raise RuntimeError('OpenVR SetOverlayAlpha failed: 11')
+        for hooks in ({'on_create': fail_create}, {'on_call': fail_alpha}):
+            with self.subTest(hooks=hooks), patch('builtins.print') as log:
+                result, calls = self.play_with('clip_SBS.mp4', **hooks)
+            self.assertEqual((result['state'], result['frames']), ('ended', 4))
+            self.assertEqual(sum(h == 1 for h, w, hgt in calls), 4)
+            self.assertIn('Theatre surround unavailable:', log.call_args.args[0])
+
+    def test_theatre_surround_refusal_after_standby_is_not_retried(self):
+        def refuse_retry(n):
+            if n == 3:  # surround busy, screen accepted, surround retry refused
+                raise RuntimeError('OpenVR SetOverlayRaw failed: 11')
+        with patch('builtins.print') as log:
+            result, calls = self.play_with('clip_SBS.mp4', busy=1, on_pixels=refuse_retry)
+        self.assertEqual((result['state'], result['frames'], result['dropped']), ('ended', 4, 0))
+        self.assertEqual(sum(h == 0 for h, w, hgt in calls), 2)
+        self.assertIn('Theatre surround unavailable:', log.call_args.args[0])
+
+    def test_screen_refusal_still_fails_playback(self):
+        def refuse_screen(n):
+            if n == 2:
+                raise RuntimeError('OpenVR SetOverlayRaw failed: 11')
+        with self.assertRaisesRegex(RuntimeError, 'SetOverlayRaw failed: 11'):
+            self.play_with('clip_SBS.mp4', on_pixels=refuse_screen)
+
+    def test_close_attempts_every_overlay_and_shuts_down_after_teardown_errors(self):
+        for error in (RuntimeError('OpenVR error'), ValueError('bad handle'),
+                      InterruptedError('late Stop')):
+            with self.subTest(error=type(error).__name__):
+                overlay = player.Overlay.__new__(player.Overlay)
+                overlay.handles = [10, 20]
+                overlay.vr = unittest.mock.Mock()
+                overlay.call = unittest.mock.Mock(side_effect=[error, None])
+                overlay.close()
+                self.assertEqual(overlay.call.call_args_list, [
+                    unittest.mock.call('DestroyOverlay', 20),
+                    unittest.mock.call('DestroyOverlay', 10)])
+                overlay.vr.VR_ShutdownInternal.assert_called_once_with()
+
     def test_stop_mid_video_reports_stopped(self):
         result, _ = self.play_with('clip_SBS.mp4', on_pixels=lambda n: n == 3 and stop_now())
         self.assertEqual(result['state'], 'stopped')

tests/test_server.py

@@ -296,7 +296,7 @@ class OneServer(unittest.TestCase):
         self.assertIn("Frame Control on", first.stdout.readline())
         second = subprocess.run([sys.executable, str(ROOT / "ui" / "server.py"), "--port", "0"], env=env,
                                 capture_output=True, text=True, timeout=60)
-        self.assertEqual(second.returncode, 1)
+        self.assertEqual(second.returncode, 1, second.stderr)
         self.assertIn("already running", second.stderr)
         first.terminate()
         first.wait(10)

tests/test_service_regressions.py

@@ -19,6 +19,28 @@ import frame_agent as agent
 import frame_android as android
 
 
+class StartupTests(unittest.TestCase):
+    def test_rejected_server_starts_no_background_work(self):
+        # A losing process exits through Python teardown. Background TLS/index
+        # workers there can crash it, and it must not sweep the owner's files.
+        with mock.patch.object(server, 'LOCAL', False), \
+                mock.patch.object(server, 'PRIVATE', False), \
+                mock.patch.object(sys, 'argv', ['server.py', '--port', '0']), \
+                mock.patch.object(server, 'one_server', side_effect=SystemExit('already running')), \
+                mock.patch.object(server, 'LoopbackServer') as listener, \
+                mock.patch.object(server, 'sweep_tmp') as sweep, \
+                mock.patch.object(server.threading, 'Thread') as worker, \
+                mock.patch.object(server.frame_telemetry, 'start') as telemetry, \
+                mock.patch.object(server.frame_contact, 'start') as contact:
+            with self.assertRaisesRegex(SystemExit, 'already running'):
+                server.main()
+            listener.assert_not_called()
+            sweep.assert_not_called()
+            worker.assert_not_called()
+            telemetry.assert_not_called()
+            contact.assert_not_called()
+
+
 class TargetTests(unittest.TestCase):
     def setUp(self):
         self.active = {'id': 'a', 'name': 'Headset A'}

ui/frame_media_player.py

@@ -88,12 +88,14 @@ class Overlay:
     def close(self):
         # Best effort: SteamVR removes a disconnected client's overlays anyway,
         # and a teardown error must not overwrite a finished playback's status.
-        for h in reversed(self.handles):
-            try:
-                self.call('DestroyOverlay', h)
-            except RuntimeError:
-                pass
-        self.vr.VR_ShutdownInternal()
+        try:
+            for h in reversed(self.handles):
+                try:
+                    self.call('DestroyOverlay', h)
+                except Exception:  # signals are already ignored here, so Stop isn't lost
+                    pass
+        finally:
+            self.vr.VR_ShutdownInternal()
 
 
 def probe(path):
@@ -183,6 +185,9 @@ def play(args):
             except OverlayBusy:
                 pending.insert(0, item)
                 return
+            except RuntimeError as e:
+                # Only the cosmetic surround is queued here.
+                print('Theatre surround unavailable: %s' % e, flush=True)
 
     def hold(handle, data, w, h):
         """Keep a still (photo or splat) up until Stop, retrying through standby."""
@@ -203,10 +208,14 @@ def play(args):
     try:
         vr = Overlay()
         if args.theatre:
-            surround = vr.create('framecontrol.media.surround', 40, 4, order=0)
-            vr.call('SetOverlayAlpha', surround, .85)
-            if not show(surround, b'\x00\x00\x00\xff', 1, 1):
-                pending.append((surround, b'\x00\x00\x00\xff', 1, 1))
+            try:
+                surround = vr.create('framecontrol.media.surround', 40, 4, order=0)
+                vr.call('SetOverlayAlpha', surround, .85)
+                if not show(surround, b'\x00\x00\x00\xff', 1, 1):
+                    pending.append((surround, b'\x00\x00\x00\xff', 1, 1))
+            except RuntimeError as e:
+                # Cosmetic: play without the dark surround rather than not at all.
+                print('Theatre surround unavailable: %s' % e, flush=True)
         screen = vr.create('framecontrol.media.screen', 3 if args.theatre else 1.6, 2,
                            plan['layout'] != 'mono', aspect)
         if splat:

ui/server.py

@@ -3637,6 +3637,11 @@ def main():
                     help="stop cleanly when stdin closes (the app closes it on quit; "
                          "Windows has no SIGTERM to catch)")
     args = ap.parse_args()
+    global LINK, _ONE_SERVER
+    if not LOCAL and not PRIVATE:
+        # Refuse before starting daemon workers: the losing process exits through
+        # Python teardown, which can race TLS work and crash instead of exit 1.
+        _ONE_SERVER = one_server()
     httpd = LoopbackServer(("127.0.0.1", args.port), Handler)
     sweep_tmp()
     if os.environ.get('FRAME_COMPAT_SEARCH_REPORTS') != '0':
@@ -3645,10 +3650,7 @@ def main():
     threading.Thread(target=apk_search.warm, daemon=True).start()  # big indexes download before the first search
     frame_telemetry.start()
     frame_contact.start()
-    global LINK, _ONE_SERVER
     if not LOCAL:
-        if not PRIVATE:  # a private server only uses the headsets (see one_server)
-            _ONE_SERVER = one_server()
         LINK = frame_link.Link(frame_devices.Registry(), env_alias=FRAME if FRAME_FROM_ENV else None,
                                mux_base=MUX_BASE, control=CONTROL, apply=route, explain=unreachable)
         LINK.work_lock, LINK.work = _work_lock, lambda: _work[0]