Skip to content

[architect] "Is there a display?" is decided in four places with two rules; empty WAYLAND_DISPLAY spawns the wrong process since #376 #381

Open

Description

@tuna-reef-hive

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 query picks Spawn::SessionHidden instead of Spawn::Headless. The spawned start --hidden cannot open a window. The query then fails with "Compass exited before its engine was ready" instead of starting the headless serve that ADR-0023 promises for a machine with no display.
  • compass start gets past the "no graphical session" guard in lib.rs::run, which exists so that winit does not fail with a backtrace. Its error message then points at compass doctor, and compass doctor reports session.type as 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:

  1. Add fn has_display_in(env: &Env) -> bool, using env.has("WAYLAND_DISPLAY") || env.has("WAYLAND_SOCKET") || env.has("DISPLAY"), so that an empty value is unset. Make activation::has_display() call it with Env::from_process(). Put the predicate beside Env, or move Env out of doctor if it should not live under the diagnostic.
  2. Route global_shortcuts.rs:644 and extension_windows.rs:106 through the same Wayland check.
  3. Add unit tests on has_display_in for unset, empty and set values, and a test that session_type and has_display_in agree on the same Env.

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

  1. added
    architectureApproved by a Hive merger/owner for auto-merge on green CI
    tech-debtApproved by a Hive merger/owner for auto-merge on green CI
    agent/architectApproved by a Hive merger/owner for auto-merge on green CI
    stage/010-actionableTriaged; eligible for the hive to pick up
    stage/stalledIn its current stage longer than expected
    on Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent/architectApproved by a Hive merger/owner for auto-merge on green CIarchitectureApproved by a Hive merger/owner for auto-merge on green CIstage/010-actionableTriaged; eligible for the hive to pick upstage/stalledIn its current stage longer than expectedtech-debtApproved by a Hive merger/owner for auto-merge on green CI

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions