Repository navigation
Description
Architecture Finding
Type: interface-violation (one decision implemented several times, with two different rules)
Affected area: crates/compass/src/activation.rs, crates/compass/src/lib.rs, crates/compass/src/global_shortcuts.rs, crates/compass/src/extension_windows.rs, crates/compass/src/doctor/env.rs
Since #376 (ADR-0023), the answer to "is there a graphical session?" decides which process a cold command spawns. That answer comes from four places, and they use two different rules:
| Site | Rule | Empty WAYLAND_DISPLAY= counts as |
|---|---|---|
doctor/env.rs Env::get → doctor/checks/session.rs |
empty value is unset ("An empty WAYLAND_DISPLAY means 'no Wayland' everywhere in the desktop stack") |
no session |
activation::has_display (used by ensure_window, ensure_engine, and the start guard in lib.rs::run) |
std::env::var_os(..).is_some() |
a session |
global_shortcuts.rs:644 connect_wayland |
var_os("WAYLAND_DISPLAY").is_none() |
Wayland |
extension_windows.rs:106 |
var_os("WAYLAND_DISPLAY").is_some() |
Wayland outputs |
The doctor built Env so that its checks are injectable and testable without set_var, which is unsafe in edition 2024 and forbidden here. The newer runtime sites read the process environment directly. That means they cannot be unit-tested, and has_display has no test.
Impact
When WAYLAND_DISPLAY and DISPLAY are set but empty (for example env WAYLAND_DISPLAY= DISPLAY= compass query foo, or a unit with Environment=DISPLAY=), these things go wrong:
compass querypicksSpawn::SessionHiddeninstead ofSpawn::Headless. The spawnedstart --hiddencannot open a window. The query then fails with "Compass exited before its engine was ready" instead of starting the headlessservethat ADR-0023 promises for a machine with no display.compass startgets past the "no graphical session" guard inlib.rs::run, which exists so that winit does not fail with a backtrace. Its error message then points atcompass doctor, andcompass doctorreportssession.typeas Fail: no graphical session. The two commands disagree about the same environment.- Every new caller has to pick a rule again. With two rules already in place, the next caller is as likely to copy the wrong one.
Recommendation
Make one predicate the only rule, and reuse the doctor's Env rather than adding a third:
- Add
fn has_display_in(env: &Env) -> bool, usingenv.has("WAYLAND_DISPLAY") || env.has("WAYLAND_SOCKET") || env.has("DISPLAY"), so that an empty value is unset. Makeactivation::has_display()call it withEnv::from_process(). Put the predicate besideEnv, or moveEnvout ofdoctorif it should not live under the diagnostic. - Route
global_shortcuts.rs:644andextension_windows.rs:106through the same Wayland check. - Add unit tests on
has_display_infor unset, empty and set values, and a test thatsession_typeandhas_display_inagree on the sameEnv.
This is a small behaviour fix (empty means unset everywhere), so it belongs with a fix lane rather than an architecture-only refactor.
Filed by architect agent (ACMM L6 — full mode)
🐝 Hive Agent: architect | Instance: reef | SHA: unknown
— hive: agent=architect backend=claude model=claude-opus-5-5 effort=high claude=2.1.322
Activity