Installed-app appearance adapter: host checkpoint

Observed 2026-09-23 from integration base 99ac8e48. The source is tools/app_appearance.py; this checkpoint does not install or invoke it in the normal shell service. Its input is an already prepared generation’s bounded report.json with the pinned upstream resolver’s palette. It writes only app-appearance/generations/ID/{terminal-foot.ini,monitor-foot.ini,coverage.json} under private theme state. sync obtains the activation lock, reads the acknowledged current/active pointer, and atomically updates a separate app-appearance/active pointer for future Foot launches. It rejects foreign generation/pointer paths and does not edit the source checkout.

The two generated Foot configs retain the portrait font and distinct app IDs, and use resolved semantic colors plus all sixteen explicit ANSI slots. Both Foot light and dark color sections receive the same selected palette so the app cannot silently switch back to an unrelated default. The opt-in osc-current command writes the pinned upstream OSC sequence only to the caller’s own terminal stdout after an isatty and TERM=foot check; these checks are an opt-in routing guard, not proof of the terminal executable. It never enumerates /dev/pts, signals a process, or closes an app. Selection and output flush hold the same bounded activation lock as theme publication, so a newer generation cannot publish between them. The host test compares its 21 sequences byte-for-byte with omarchy-theme-osc on the prepared fixture.

nix/handheld-theme-command.nix now installs k230-app-appearance. The pinned default package includes static terminal and monitor Foot configs generated by this same adapter; tools/generate_default_foot.py --check rejects drift. The static files extend the package output without changing the existing palette/appearance generation identity. A fresh home can use those Nix-store files before a mutable active pointer exists.

The host coordinator now calls app sync only after a shell commit ACK and after releasing the activation lock. Sync reacquires that lock and checks the expected generation, preventing a late first activation from overwriting a newer app selection. omarchy-theme-set and the JSON chooser return an app_appearance result separate from shell activation: applied, failed or superseded. An app failure does not falsely roll back an acknowledged shell theme. The host failure fixture verifies the shell pointer and phase history stay committed when app sync fails.

Coverage is deliberately bounded: htop, nano and nnn inherit Foot’s terminal colors; mpv’s video surface is not a terminal-color consumer; Help uses shell tokens; the on-screen keyboard remains a separate shell-surface integration. Existing Foot windows are not automatically retinted, and the normal Nix launch paths still point at their earlier immutable base configs. The generated configuration and sync hook must be wired to those launch paths before task 3.4 can be marked complete. Any app reload failure belongs in a separate status from the shell generation ACK; it must not be reported as a successful existing-session recolor.

An opt-in k230-foot-session source wrapper is now packaged for Foot launch paths. Invoked inside Foot as k230-foot-session --state-root STATE --default-generation PINNED -- COMMAND, it validates its own stdout TTY, forks one bounded color follower, then execs COMMAND with its original args and foreground process group. The follower inherits only that terminal’s stdout and a Linux pidfd opened before forking for the exec’d parent. The parent closes its copy before exec, so even a fast-exiting app cannot turn the follower’s parent lookup into PID 1. The follower reopens its own inherited TTY stdout through /proc/self/fd/1 as a separate nonblocking file description; it does not change the app’s stdout flags. OSC writes have a 100 ms deadline even with a stopped/full PTY, and release the activation lock on timeout. It polls the acknowledged generation once per second by default, emits OSC only on a generation change under the activation lock, uses the pinned default on rollback to no active pointer, and exits when the parent exits. It does not scan PTYs, signal apps, or keep a terminal open after its app leaves. If pidfd_open fails, the requested app still execs and a fixed diagnostic identifies the missing follower; no OSC claim is made for that session. A fake PTY with a controlling terminal proved unchanged argument execution, foreground process group, initial OSC, and follower exit. Separate host cases cover fast app exit and a full PTY with injected persistent backpressure and bounded lock release. A single 2026-09-23 x86_64 host run observed 14,600 KiB VmRSS for one Python follower; this is neither a target RSS nor a frame-cost measurement. The one-second polling and target cost need review on the actual handheld. The normal Foot launchers do not yet invoke this wrapper, so existing-window automatic recolor remains unproved in production.

python3 tests/test_handheld_app_themes.py   PASS 9 host tests
python3 tests/test_handheld_theme_default.py  PASS 2 host tests
python3 tests/test_omarchy_theme_transaction.py  PASS 13 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_foot_color_session.py  PASS 6 host tests; one host RSS=14,600 KiB
python3 tools/generate_default_foot.py --check  PASS
python3 -m py_compile tools/app_appearance.py  PASS
openspec validate the-shell-loads-omarchy-themes --strict  PASS
git diff --check  PASS

No Nix build, device session, physical display observation, or live Foot reload was performed for this adapter checkpoint. OpenSpec task 3.4 remains open, as do the cross-surface, app-session and physical gates.