Per-theme wallpaper memory: host checkpoint

Observed 2026-09-23 from the c92160d8 integration base. The optional background-selections.json lives under the user’s theme state directory, outside every unchanged source checkout. Its keys hash canonical source paths; its values are source-relative backgrounds/NAME entries rather than stale generation store paths. The file is bounded to 64 KiB/256 choices, written atomically with mode 0600, and rejects foreign symlinks and malformed data.

Omitting a background in either omarchy-theme-set or the JSON chooser reads the remembered asset if it remains staged. An explicit asset wins, including the theme’s default image. If the remembered asset was removed in a source update, preparation reports remembered background removed; using theme default; this does not rewrite the preference during preview. The next acknowledged activation records the fallback.

The preference guard and final write run under the same existing activation flock as the current/active pointer swap. A shell commit ACK precedes the memory write; a failed ACK preserves both prior pointer and preference. A failed post-ACK preference write attempts restoration of the pointer, prior preference bytes, and shell generation. A stale implicit preview whose source preference changed while it waited for the lock is rejected for re-preview. There is no claim that the physical panel presented or remembered an image.

python3 tests/test_theme_preferences.py          PASS 9 host tests
python3 tests/test_theme_catalog.py              PASS 9 host tests
python3 tests/test_omarchy_theme_activation.py   PASS 9 host tests
python3 tests/test_omarchy_theme_transaction.py  PASS 13 host tests
openspec validate the-shell-loads-omarchy-themes --strict  PASS

Fixtures cover switch-away/back and a fresh process read, source update, deleted asset fallback, preview/cancel, failed shell ACK, injected preference write failure after replacement, cached-generation diagnostics, conflicting concurrent activations, the compatible command path, and an alien symlink. No Nix package build, reboot, touch chooser, decode/cache/overlay/fit mode, or real-glass proof was run for this checkpoint. OpenSpec task 4.1 and the physical tasks remain open.

The coordinator subsequently built the narrow command package from the landed 99ac8e48 integration revision: nix build .#handheld-theme-command --no-link PASS, output /nix/store/xjncl4sgb4yb7asabpk41l051wncpi5b-handheld-theme-command-0.1. This proves the package evaluates and cross-builds; it does not prove a theme switch, client repaint, wallpaper presentation, or persistence on the board.