Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

85.8 KB
Raw Blame
// Independent-seat design adapted from Dillon DuPont's Hyprland prototype.
// TARGET uses independent resources; FOREGROUND_TARGET explicitly uses the primary seat.
#include "input_experiment.hpp"
#include "drag_geometry.hpp"
#include "input_grant.hpp"
#include "input_client_deadline.hpp"
#include "passive_pointer_target.hpp"
#include "primary_trace.hpp"
#include "seat_lifetime.hpp"
#include "owned_socket_path.hpp"
#include "foreground_route.hpp"
#include "keymap_equivalence.hpp"

#include <src/Compositor.hpp>
#include <src/devices/IKeyboard.hpp>
#include <src/event/EventBus.hpp>
#include <src/managers/SeatManager.hpp>
#include <src/output/Monitor.hpp>
#include <src/protocols/core/Compositor.hpp>
#include <src/state/MonitorState.hpp>
#include <src/desktop/state/FocusState.hpp>
#include <src/managers/input/InputManager.hpp>
#include <src/pointer/PointerManager.hpp>
#include <src/protocols/core/Seat.hpp>
#include <src/protocols/core/DataDevice.hpp>
#include <src/layout/LayoutManager.hpp>
#include <linux/input-event-codes.h>
#include <wayland.hpp>
#include <wayland-server-core.h>

#ifdef CUA_HYPRLAND_TEST_INPUT
#include <openssl/evp.h>
#endif
#include <sys/random.h>
#include <sys/mman.h>
#include <xkbcommon/xkbcommon.h>

#include <algorithm>
#include <array>
#include <charconv>
#include <cerrno>
#include <chrono>
#include <cmath>
#include <cstring>
#include <cstdlib>
#include <filesystem>
#include <fcntl.h>
#include <format>
#include <memory>
#include <optional>
#include <stdexcept>
#include <string_view>
#include <sys/socket.h>
#include <sys/stat.h>
#include <sys/un.h>
#include <unistd.h>

#if defined(CUA_HYPRLAND_INPUT) == defined(CUA_HYPRLAND_TEST_INPUT)
#error Select exactly one input admission mode
#endif

namespace cua::hyprland {
namespace {
using Clock = std::chrono::steady_clock;
constexpr std::size_t kMaxPacket = 2048;
constexpr std::size_t kMaxClients = 8;
constexpr std::size_t kMaxResources = 512;
#ifdef CUA_HYPRLAND_INPUT
constexpr bool kProduction = true;
#else
constexpr bool kProduction = false;
#endif

#ifndef CUA_HYPRLAND_WINDOW_BACKEND_API
#error CUA_HYPRLAND_WINDOW_BACKEND_API must name the detected Hyprland window API
#endif
// Hyprland 0.57 moved window identity onto the window backend and renamed the
// exclusive layer list when pointer focus stopped following it (#15899). The
// input guard still refuses while any exclusive layer surface is present.
bool window_mapped(const PHLWINDOW& window) {
#if CUA_HYPRLAND_WINDOW_BACKEND_API
    return window->mapped();
#else
    return window->m_isMapped;
#endif
}
bool window_is_x11(const PHLWINDOW& window) {
#if CUA_HYPRLAND_WINDOW_BACKEND_API
    return window->backend().isX11();
#else
    return window->m_isX11;
#endif
}
pid_t window_pid(const PHLWINDOW& window) {
#if CUA_HYPRLAND_WINDOW_BACKEND_API
    return window->backend().pid();
#else
    return window->getPID();
#endif
}
const std::vector<PHLLSREF>& exclusive_layer_surfaces() {
#if CUA_HYPRLAND_WINDOW_BACKEND_API
    return g_pInputManager->m_exclusiveKeyboardLSes;
#else
    return g_pInputManager->m_exclusiveLSes;
#endif
}

#ifdef CUA_HYPRLAND_TEST_INPUT
std::uint64_t unix_ms() {
    return std::chrono::duration_cast<std::chrono::milliseconds>(
               std::chrono::system_clock::now().time_since_epoch()).count();
}
#endif
std::uint32_t event_ms() {
    return static_cast<std::uint32_t>(std::chrono::duration_cast<std::chrono::milliseconds>(
               Clock::now().time_since_epoch()).count());
}
std::string nonce() {
    std::array<unsigned char, 16> bytes{};
    std::size_t offset = 0;
    while (offset < bytes.size()) {
        const auto n = getrandom(bytes.data() + offset, bytes.size() - offset, 0);
        if (n < 0 && errno == EINTR) continue;
        if (n <= 0) throw std::runtime_error("input entropy unavailable");
        offset += static_cast<std::size_t>(n);
    }
    std::string result;
    for (auto b : bytes)
        result += std::format("{:02x}", b);
    return result;
}
#ifdef CUA_HYPRLAND_TEST_INPUT
std::vector<unsigned char> unhex(std::string_view value) {
    if (value.size() % 2)
        throw std::runtime_error("invalid hex");
    std::vector<unsigned char> bytes;
    for (std::size_t i = 0; i < value.size(); i += 2) {
        unsigned int n = 0;
        const auto [p, error] = std::from_chars(value.data() + i, value.data() + i + 2, n, 16);
        if (error != std::errc{} || p != value.data() + i + 2)
            throw std::runtime_error("invalid hex");
        bytes.push_back(static_cast<unsigned char>(n));
    }
    return bytes;
}
#endif
std::uint64_t number(std::string_view value, int base = 10) {
    std::uint64_t n = 0;
    const auto [p, error] = std::from_chars(value.data(), value.data() + value.size(), n, base);
    if (value.empty() || error != std::errc{} || p != value.data() + value.size())
        throw std::runtime_error("invalid integer");
    return n;
}
double real(std::string_view value) {
    double n = 0;
    const auto [p, error] = std::from_chars(value.data(), value.data() + value.size(), n);
    if (value.empty() || error != std::errc{} || p != value.data() + value.size() || !std::isfinite(n))
        throw std::runtime_error("invalid coordinate");
    return n;
}
std::vector<std::string> fields(std::string_view packet) {
    if (packet.empty() || packet.front() == ' ' || packet.back() == ' ')
        throw std::runtime_error("invalid packet");
    std::vector<std::string> result;
    std::size_t start = 0;
    for (std::size_t i = 0; i <= packet.size(); ++i) {
        if (i < packet.size() && (packet[i] < 32 || packet[i] > 126))
            throw std::runtime_error("non-ASCII packet");
        if (i != packet.size() && packet[i] != ' ')
            continue;
        if (i == start || result.size() >= 16)
            throw std::runtime_error("invalid fields");
        result.emplace_back(packet.substr(start, i - start));
        start = i + 1;
    }
    return result;
}
std::string refusal(std::string_view code) {
    // Only internal fixed identifiers enter JSON. No caller-provided strings.
    return std::format(R"({{"ok":false,"code":"{}","detail":"{}"}})", code, code);
}
std::string refusal(std::string_view code, ForegroundFailure failure) {
    return std::format(R"({{"ok":false,"code":"{}","detail":"{}"}})", code, failure.detail());
}
constexpr auto kDelivered = R"({"ok":true,"effect":"unverifiable","route":"synthetic_events"})";
constexpr auto kForegroundDelivered = R"({"ok":true,"effect":"unverifiable","route":"primary_foreground"})";
} // namespace

struct InputExperiment::Impl {
    struct Seat { SP<CWlSeat> wl; bool dead = false; };
    struct Pointer { SP<CWlPointer> wl; bool dead = false; WP<CWLSurfaceResource> focus; };
    struct Keyboard { SP<CWlKeyboard> wl; bool dead = false; WP<CWLSurfaceResource> focus; };
    struct Touch { SP<CWlTouch> wl; bool dead = false; };
    struct Client {
        Impl* owner = nullptr;
        int fd = -1;
        wl_event_source* source = nullptr;
        bool dead = false, hello = false;
        // Sticky for this connection: a bare CLAIM does not own inherited
        // hover. Never reset on STOP/CANCEL, repeated CLAIM, or invalidation.
        bool has_bound_target = false;
        InputRoute route = InputRoute::unbound;
        bool foreground_attempted = false;
        std::string challenge, token;
        WP<Desktop::View::CWindow> window;
        WP<CWLSurfaceResource> surface;
        std::array<double, 6> geometry{};
        std::uint64_t revision = 1, sequence = 0, approved_deadline = 0;
        InputClientDeadline deadline;
        CHyprSignalListener unmap, destroy;
        ~Client() {
            if (source) wl_event_source_remove(source);
            if (fd >= 0) close(fd);
        }
    };
    struct Drag {
        Client* client;
        double x1, y1, x2, y2;
        Clock::time_point start;
        unsigned duration;
        DragGeometry geometry;
    };
    int listener = -1;
    wl_event_source* listen_source = nullptr;
    wl_event_source* timer = nullptr;
    wl_global* global = nullptr;
    OwnedSocketPath socket_path;
    std::string_view socket_cleanup = "not_bound";
    std::string path, epoch = nonce(), keymap_text, physical_keymap_text;
    std::vector<unsigned char> public_key;
    std::vector<std::unique_ptr<Client>> clients;
    std::vector<std::unique_ptr<Seat>> seats;
    std::vector<std::unique_ptr<Pointer>> pointers;
    std::vector<std::unique_ptr<Keyboard>> keyboards;
    std::vector<std::unique_ptr<Touch>> touches;
    Client* lease = nullptr;
    // Pointer presence is not input authority. Keep the same live surface
    // entered between actions, as a real pointer is, without retaining a grant.
    PassivePointerTarget<WP<Desktop::View::CWindow>, WP<CWLSurfaceResource>> pointer_target;
    CHyprSignalListener pointer_unmap, pointer_destroy;
    Client* reservation = nullptr;
    std::uint64_t desktop_generation = 1;
    std::uint64_t capabilities = 0, dispatches = 0;
    Clock::time_point expires{};
    InputGrant grant;
    std::optional<Drag> drag;
    std::uint32_t held_button = 0;
    std::vector<std::uint32_t> held_keys;
    xkb_context* xkb_context_ = nullptr;
    xkb_keymap* keymap = nullptr;
    xkb_state* keyboard_state = nullptr;
    xkb_context* physical_xkb_context = nullptr;
    xkb_keymap* physical_keymap = nullptr;
    xkb_state* physical_keyboard_state = nullptr;
    int keymap_fd = -1;
    // Hyprland's input:repeat_rate and input:repeat_delay defaults, advertised
    // until an active keyboard reports the user's values.
    int repeat_rate = 25, repeat_delay = 600;
    bool retired = false, suspended = true, typing_keymap = false, physical_keymap_present = false;
    WP<IKeyboard> physical_keyboard;
    CHyprSignalListener keymap_listener;
    unsigned lane;
    std::array<Impl*, 2> peers{};
    PrimaryTrace* trace = nullptr;
    bool foreground_started = false, foreground_activating = false;
    bool foreground_keyboard_used = false;
    bool foreground_needs_keyboard = false;
    bool foreground_needs_pointer = false;
    WP<CWLSurfaceResource> foreground_surface;
    WP<CWLSeatResource> foreground_seat;
    std::vector<WP<CWLPointerResource>> foreground_pointers;
    std::vector<WP<CWLKeyboardResource>> foreground_keyboards;
    std::array<std::uint32_t, 4> foreground_modifiers{};

    explicit Impl(const std::string& directory, unsigned index) : lane(index) {
#ifdef CUA_HYPRLAND_TEST_INPUT
        public_key = unhex(CUA_HYPRLAND_TEST_OPERATOR_KEY);
        if (public_key.size() != 32)
            throw std::runtime_error("invalid test operator public key");
#endif
        path = directory + (kProduction ?
            (lane == 0 ? "/cua-input-v3.sock" : "/cua-input-v3-2.sock") :
            (lane == 0 ? "/cua-input-test.sock" : "/cua-input-test-2.sock"));
        if (path.size() >= sizeof(sockaddr_un::sun_path))
            throw std::runtime_error("input socket path too long");
        // No private key or input-enabled default exists in this component.
    }

    static int create_keymap_file(std::string_view text) {
        const auto fd = memfd_create("cua-agent-keymap", MFD_CLOEXEC);
        std::string payload(text);
        payload.push_back('\0');
        if (fd < 0 || ftruncate(fd, static_cast<off_t>(payload.size())) != 0) {
            if (fd >= 0) close(fd);
            throw std::runtime_error("agent keymap file unavailable");
        }
        std::size_t offset = 0;
        while (offset < payload.size()) {
            const auto written = pwrite(fd, payload.data() + offset, payload.size() - offset, static_cast<off_t>(offset));
            if (written < 0 && errno == EINTR) continue;
            if (written <= 0) { close(fd); throw std::runtime_error("agent keymap write failed"); }
            offset += static_cast<std::size_t>(written);
        }
        return fd;
    }
    void initialize_agent_keymap() {
        if (keyboard_state) return;
        const xkb_rule_names names{kAgentKeymap.rules.data(), kAgentKeymap.model.data(),
            kAgentKeymap.layout.data(), kAgentKeymap.variant.data(), kAgentKeymap.options.data()};
        auto* context = xkb_context_new(XKB_CONTEXT_NO_FLAGS);
        auto* map = context ? xkb_keymap_new_from_names(context, &names, XKB_KEYMAP_COMPILE_NO_FLAGS) : nullptr;
        auto* state = map ? xkb_state_new(map) : nullptr;
        char* serialized = map ? xkb_keymap_get_as_string(map, XKB_KEYMAP_FORMAT_TEXT_V1) : nullptr;
        if (!state || !serialized) {
            std::free(serialized);
            if (state) xkb_state_unref(state);
            if (map) xkb_keymap_unref(map);
            if (context) xkb_context_unref(context);
            throw std::runtime_error("agent US keymap unavailable");
        }
        std::string text(serialized);
        std::free(serialized);
        int fd = -1;
        try {
            fd = create_keymap_file(text);
        } catch (...) {
            xkb_state_unref(state);
            xkb_keymap_unref(map);
            xkb_context_unref(context);
            throw;
        }
        xkb_context_ = context;
        keymap = map;
        keyboard_state = state;
        keymap_text = std::move(text);
        keymap_fd = fd;
    }
    bool layout_qualified() const {
        if (!kProduction) return true;
        const auto keyboard = g_pSeatManager->m_keyboard.lock();
        return physical_keymap_present && typing_keymap && physical_keyboard_state && keyboard &&
            keyboard->m_xkbKeymapV1FD.get() >= 0 && keyboard->m_xkbKeymapV1String == physical_keymap_text;
    }
    // Agent keyboards advertise the user seat's wl_keyboard.repeat_info. A zero
    // rate is valid Wayland, but a single-seat client that binds an agent seat
    // may divide by it: imv 5.0.1 raised SIGFPE on repeat_info(0, 0) (#4257).
    //
    // A real rate cannot make Driver typing repeat. Protocol v3 has no key-down
    // or key-up request. One KEY request presses the key and its modifiers,
    // releases them, and leaves keyboard focus in a single synchronous handler
    // on the compositor thread, with no event-loop iteration in between. The
    // client gets the release together with the press and handles both in one
    // dispatch, so a repeat timer armed by the press is cancelled before the
    // client's event loop can run it; the wl_keyboard.leave that follows also
    // requires the client to stop repeating. The hold is therefore bounded by
    // that handler, not by the user's delay. DRAG holds only a pointer button.
    // A request that holds a key across dispatches would have to keep the
    // advertised delay above its longest hold.
    //
    // Like the user seat, keep the last values while no keyboard is active.
    void sync_key_repeat(const SP<IKeyboard>& keyboard) {
        if (!keyboard) return;
        const auto rate = std::max(0, keyboard->m_repeatRate), delay = std::max(0, keyboard->m_repeatDelay);
        if (rate == repeat_rate && delay == repeat_delay) return;
        repeat_rate = rate; repeat_delay = delay;
        for (auto& k : keyboards)
            if (!k->dead && k->wl->resource() && k->wl->version() >= 4) k->wl->sendRepeatInfo(rate, delay);
    }
    void sync_keymap() {
        initialize_agent_keymap();
        const auto keyboard = g_pSeatManager->m_keyboard.lock();
        sync_key_repeat(keyboard);
        if (physical_keyboard != keyboard) {
            if (physical_keymap_present) desktop_transition();
            keymap_listener.reset();
            physical_keyboard = keyboard;
            if (keyboard && kProduction)
                keymap_listener = keyboard->m_keyboardEvents.keymap.listen([this](IKeyboard::SKeymapEvent) {
                    desktop_transition();
                });
        }
        if (!keyboard || keyboard->m_xkbKeymapV1FD.get() < 0 || keyboard->m_xkbKeymapV1String.empty()) {
            if (physical_keymap_present) desktop_transition();
            physical_keymap_present = false;
            return;
        }
        physical_keymap_present = true;
        if (physical_keyboard_state && physical_keymap_text == keyboard->m_xkbKeymapV1String) return;
        // Foreground keyboard delivery uses the primary seat. Keep a separate
        // compiled state for it; the background seats retain their fixed US map.
        auto* context = xkb_context_new(XKB_CONTEXT_NO_FLAGS);
        auto* map = context ? xkb_keymap_new_from_string(context, keyboard->m_xkbKeymapV1String.c_str(),
            XKB_KEYMAP_FORMAT_TEXT_V1, XKB_KEYMAP_COMPILE_NO_FLAGS) : nullptr;
        auto* state = map ? xkb_state_new(map) : nullptr;
        if (!state) {
            if (state) xkb_state_unref(state);
            if (map) xkb_keymap_unref(map);
            if (context) xkb_context_unref(context);
            throw std::runtime_error("primary XKB state unavailable");
        }
        desktop_transition();
        if (physical_keyboard_state) xkb_state_unref(physical_keyboard_state);
        if (physical_keymap) xkb_keymap_unref(physical_keymap);
        if (physical_xkb_context) xkb_context_unref(physical_xkb_context);
        physical_keyboard_state = state; physical_keymap = map; physical_xkb_context = context;
        // Keyboard qualification: every key the KEY command can press must type the
        // same keysym as the canonical agent keymap. Checked once per keymap, so a
        // different layout refuses before activation rather than mid-string.
        typing_keymap = !kProduction || typing_keymap_equivalent(map, keymap);
        physical_keymap_text = keyboard->m_xkbKeymapV1String;
    }
    void start() {
        sync_keymap();
        timer = wl_event_loop_add_timer(g_pCompositor->m_wlEventLoop, tick, this);
        if (!timer) throw std::runtime_error("input timer registration failed");
        global = wl_global_create(g_pCompositor->m_wlDisplay, &wl_seat_interface, 9, this, bind_seat);
        if (!global) throw std::runtime_error("synthetic seat unavailable");
        wl_event_source_timer_update(timer, 16);
    }
    void resume() {
        if (retired || desktop_generation == UINT64_MAX)
            throw std::runtime_error("restart desktop before replacing input seats");
        if (!suspended) return;
        sync_keymap();
        // Every new admission period has fresh identity and no inherited grant.
        epoch = nonce();
        listener = socket(AF_UNIX, SOCK_SEQPACKET | SOCK_NONBLOCK | SOCK_CLOEXEC, 0);
        if (listener < 0) throw std::runtime_error("input socket unavailable");
        sockaddr_un address{};
        address.sun_family = AF_UNIX;
        std::memcpy(address.sun_path, path.c_str(), path.size() + 1);
        // Never unlink a pre-existing socket owned by another plugin instance.
        if (bind(listener, reinterpret_cast<sockaddr*>(&address), sizeof(address)) != 0)
            throw std::runtime_error("input socket bind refused");
        if (!socket_path.capture(path))
            throw std::runtime_error("input socket ownership unavailable");
        socket_cleanup = "bound";
        if (chmod(path.c_str(), 0600) != 0 || listen(listener, 8) != 0)
            throw std::runtime_error("input socket setup failed");
        listen_source = wl_event_loop_add_fd(g_pCompositor->m_wlEventLoop, listener, WL_EVENT_READABLE, accept_ready, this);
        if (!listen_source) throw std::runtime_error("input event loop registration failed");
        suspended = false;
    }
    void cleanup_socket() {
        using Result = OwnedSocketPath::CleanupResult;
        switch (socket_path.cleanup()) {
            case Result::NotCaptured: break;
            case Result::Removed: socket_cleanup = "removed"; break;
            case Result::AlreadyAbsent: socket_cleanup = "absent"; break;
            case Result::Replaced: socket_cleanup = "replacement_preserved"; break;
            case Result::Failed: socket_cleanup = "failed"; break;
        }
    }
    void suspend(std::string_view reason = "plugin_disabled") {
        suspended = true;
        revoke(reason, reason != "plugin_shutdown");
        reservation = nullptr;
        if (listen_source) wl_event_source_remove(listen_source);
        listen_source = nullptr;
        clients.clear();
        if (listener >= 0) close(listener);
        listener = -1;
        cleanup_socket();
        // Keep the globals, capabilities, and client resources stable. Removing
        // and recreating them makes existing apps lose their agent input path.
    }
    void retire() {
        // wl_global removal does not revoke existing protocol objects. Destroying
        // those objects immediately disconnects clients that still send release
        // or cursor requests (observed with foot). Retain inert resources and
        // callbacks until compositor exit; input-enabled modules are NODELETE.
        suspend("plugin_shutdown");
        keymap_listener.reset();
        retired = true;
        for (auto& seat : seats)
            if (!seat->dead && seat->wl->resource())
                seat->wl->sendCapabilities(static_cast<wl_seat_capability>(0));
        if (global) wl_global_remove(global);
    }
    ~Impl() {
        revoke("plugin_shutdown");
        if (global) wl_global_destroy(global);
        if (listen_source) wl_event_source_remove(listen_source);
        if (timer) wl_event_source_remove(timer);
        clients.clear();
        // Destroy all plugin-owned resources before unloading code callbacks.
        pointers.clear(); keyboards.clear(); touches.clear(); seats.clear();
        if (listener >= 0) close(listener);
        cleanup_socket();
        if (keyboard_state) xkb_state_unref(keyboard_state);
        if (keymap) xkb_keymap_unref(keymap);
        if (xkb_context_) xkb_context_unref(xkb_context_);
        if (physical_keyboard_state) xkb_state_unref(physical_keyboard_state);
        if (physical_keymap) xkb_keymap_unref(physical_keymap);
        if (physical_xkb_context) xkb_context_unref(physical_xkb_context);
        if (keymap_fd >= 0) close(keymap_fd);
    }
    std::uint32_t serial() const { return wl_display_next_serial(g_pCompositor->m_wlDisplay); }
    bool available() const {
        return !retired && !suspended && g_pCompositor->m_sessionActive && g_pCompositor->m_dpmsStateOn &&
            !g_pCompositor->m_isShuttingDown && !g_pSessionLockManager->isSessionLocked();
    }
    static void bind_seat(wl_client* client, void* data, std::uint32_t version, std::uint32_t id) {
        auto& self = *static_cast<Impl*>(data);
        if (self.seats.size() >= kMaxResources) { wl_client_post_no_memory(client); return; }
        auto seat = std::make_unique<Seat>();
        auto* entry = seat.get();
        seat->wl = makeShared<CWlSeat>(client, std::min(version, 9u), id);
        if (!seat->wl->resource()) { wl_client_post_no_memory(client); return; }
        // Stock resource lookup casts CWlSeat::data to CWLSeatResource. Null is
        // intentional: an agent serial must not authorize primary-seat WM grabs.
        seat->wl->setData(nullptr);
        seat->wl->setRelease([entry](CWlSeat*) { entry->dead = true; });
        seat->wl->setOnDestroy([entry](CWlSeat*) { entry->dead = true; });
        seat->wl->setGetPointer([&self](CWlSeat* r, std::uint32_t child) { self.add_pointer(r, child); });
        seat->wl->setGetKeyboard([&self](CWlSeat* r, std::uint32_t child) { self.add_keyboard(r, child); });
        seat->wl->setGetTouch([&self](CWlSeat* r, std::uint32_t child) { self.add_touch(r, child); });
        if (version >= 2) seat->wl->sendName(kProduction ?
            (self.lane == 0 ? "Cua-Agent" : "Cua-Agent-2") :
            (self.lane == 0 ? "Cua-Test-Agent" : "Cua-Test-Agent-2"));
        seat->wl->sendCapabilities(static_cast<wl_seat_capability>(self.retired ? 0 :
            WL_SEAT_CAPABILITY_POINTER | (self.keyboard_state ? WL_SEAT_CAPABILITY_KEYBOARD : 0)));
        self.seats.push_back(std::move(seat));
    }
    void add_pointer(CWlSeat* seat, std::uint32_t id) {
        if (pointers.size() >= kMaxResources) { seat->noMemory(); return; }
        auto p = std::make_unique<Pointer>(); auto* entry = p.get();
        p->wl = makeShared<CWlPointer>(seat->client(), seat->version(), id);
        if (!p->wl->resource()) { seat->noMemory(); return; }
        p->wl->setData(nullptr);
        p->wl->setRelease([entry](CWlPointer*) { entry->dead = true; });
        p->wl->setOnDestroy([entry](CWlPointer*) { entry->dead = true; });
        p->wl->setSetCursor([](CWlPointer*, std::uint32_t, wl_resource*, std::int32_t, std::int32_t) {});
        pointers.push_back(std::move(p));
    }
    void add_keyboard(CWlSeat* seat, std::uint32_t id) {
        if (!keyboard_state || keyboards.size() >= kMaxResources) { seat->noMemory(); return; }
        auto k = std::make_unique<Keyboard>(); auto* entry = k.get();
        k->wl = makeShared<CWlKeyboard>(seat->client(), seat->version(), id);
        if (!k->wl->resource()) { seat->noMemory(); return; }
        k->wl->setData(nullptr);
        k->wl->setRelease([entry](CWlKeyboard*) { entry->dead = true; });
        k->wl->setOnDestroy([entry](CWlKeyboard*) { entry->dead = true; });
        k->wl->sendKeymap(WL_KEYBOARD_KEYMAP_FORMAT_XKB_V1, keymap_fd, keymap_text.size() + 1);
        if (seat->version() >= 4) k->wl->sendRepeatInfo(repeat_rate, repeat_delay);
        keyboards.push_back(std::move(k));
    }
    void add_touch(CWlSeat* seat, std::uint32_t id) {
        // Never advertised. A valid inert resource is safer than a dangling id.
        if (touches.size() >= kMaxResources) { seat->noMemory(); return; }
        auto t = std::make_unique<Touch>(); auto* entry = t.get();
        t->wl = makeShared<CWlTouch>(seat->client(), seat->version(), id);
        if (!t->wl->resource()) { seat->noMemory(); return; }
        t->wl->setData(nullptr);
        t->wl->setRelease([entry](CWlTouch*) { entry->dead = true; });
        t->wl->setOnDestroy([entry](CWlTouch*) { entry->dead = true; });
        touches.push_back(std::move(t));
    }
    static std::optional<std::array<double, 6>> target_geometry(
        const PHLWINDOW& window, const SP<CWLSurfaceResource>& surface) {
        if (!window || !surface || !window_mapped(window) || window->isHidden() ||
            window_is_x11(window) || window->resource() != surface || !surface->m_mapped || !surface->good()) return std::nullopt;
        // Match Driver's captured client surface, not the decorated window box
        // (which includes compositor borders and shifts clicks by their width).
        const auto box = window->surfaceLogicalBox(); const auto surface_box = box;
        if (!box || !surface_box || box->w <= 0 || box->h <= 0 || box->w > 32767 || box->h > 32767) return std::nullopt;
        std::array<double, 6> geometry{box->x, box->y, box->w, box->h, surface_box->x, surface_box->y};
        if (!std::ranges::all_of(geometry, [](double value) { return std::isfinite(value); })) return std::nullopt;
        return geometry;
    }
    bool refresh(Client& c) {
        const auto geometry = target_geometry(c.window.lock(), c.surface.lock());
        if (!geometry) return false;
        if (*geometry != c.geometry) {
            if (c.revision == UINT64_MAX) return false;
            c.geometry = *geometry; ++c.revision;
        }
        return true;
    }
    bool primary_conflict(const Client& c) const {
        if (c.route == InputRoute::primary_foreground)
            return foreground_started && !foreground_activating && !foreground_guard(c).can_dispatch(foreground_needs_pointer);
        return primary_conflict(c.surface.lock());
    }
    bool primary_conflict(const SP<CWLSurfaceResource>& surface) const {
        if (!surface) return true;
        const auto pointer = g_pSeatManager->m_state.pointerFocus.lock();
        const auto keyboard = g_pSeatManager->m_state.keyboardFocus.lock();
        // Conservative per-client refusal avoids toolkit-global cross-window state.
        return (pointer && pointer->client() == surface->client()) ||
            (keyboard && keyboard->client() == surface->client());
    }
    bool agent_conflict(const Client& c) const {
        if (c.route == InputRoute::primary_foreground)
            for (const auto* peer : peers)
                if (peer && peer != this && peer->lease && peer->lease->route == InputRoute::primary_foreground) return true;
        return agent_conflict(c.surface.lock());
    }
    bool agent_conflict(const SP<CWLSurfaceResource>& surface) const {
        if (!surface) return true;
        for (const auto* peer : peers) {
            if (!peer || peer == this) continue;
            // Passive hover still participates after its transport owner dies.
            if (peer->pointer_target.same_client(surface)) return true;
            const auto other = peer->lease ? peer->lease->surface.lock() : nullptr;
            if (other && other->client() == surface->client()) return true;
        }
        return false;
    }
    void retire_orphan_hover(const Client& c) {
        for (auto* peer : peers) {
            if (!peer || peer == this) continue;
            const InputLaneActivity activity{
                .reserved = peer->reservation != nullptr,
                .leased = peer->lease != nullptr,
                .dragging = peer->drag.has_value(),
                .button = peer->held_button != 0,
                .keys = !peer->held_keys.empty(),
                .keyboard_focus = std::ranges::any_of(peer->keyboards, [](const auto& k) { return bool(k->focus); }),
                .capabilities = peer->capabilities != 0,
                .grant = peer->grant.deadline() != Clock::time_point{},
                .expiry = peer->expires != Clock::time_point{},
                .reservation_without_target = peer->reservation && !peer->reservation->has_bound_target,
            };
            // Driver claims the first free lane before TARGET. Retire only a
            // matching, completely inert peer hover so opposite-order reuse
            // cannot strand a target on another lane. A fresh claimant that
            // has never bound a target does not adopt inherited hover; an
            // existing target owner remains protected even after STOP.
            if (peer->pointer_target.reclaimable_for(c.surface.lock(), activity)) peer->leave_pointer();
        }
    }
    void invalidate(Client& c, bool clear_pointer = true) {
        if (lease == &c || (clear_pointer && c.surface.lock() && pointer_target.surface() == c.surface.lock()))
            revoke("stale_target", !clear_pointer);
        c.token.clear(); c.window.reset(); c.surface.reset();
        // Replay high-water belongs to the old target binding. A genuinely
        // new token may receive a shorter grant after Stop or target change.
        c.approved_deadline = 0;
    }
    void release_pointer_button() {
        if (!held_button) return;
        for (auto& p : pointers) {
            const auto surface = p->focus.lock();
            if (!p->dead && p->wl->resource() && surface && surface->good()) {
                p->wl->sendButton(serial(), event_ms(), held_button, WL_POINTER_BUTTON_STATE_RELEASED);
                // A complete release frame is delivery, not client processing proof.
                if (p->wl->version() >= 5) p->wl->sendFrame();
            }
        }
        held_button = 0;
    }
    void leave_pointer() {
        release_pointer_button();
        for (auto& p : pointers) {
            const auto surface = p->focus.lock();
            if (!p->dead && p->wl->resource() && surface && surface->good()) {
                p->wl->sendLeave(serial(), surface->getResource().get());
                if (p->wl->version() >= 5) p->wl->sendFrame();
            }
            p->focus.reset();
        }
        pointer_target.reset();
        pointer_unmap.reset(); pointer_destroy.reset();
    }
    void leave_keyboard() {
        for (auto& k : keyboards) {
            const auto surface = k->focus.lock();
            if (!k->dead && k->wl->resource() && surface && surface->good()) {
                for (auto key : held_keys) k->wl->sendKey(serial(), event_ms(), key, WL_KEYBOARD_KEY_STATE_RELEASED);
                k->wl->sendModifiers(serial(), 0, 0, 0, 0);
                k->wl->sendLeave(serial(), surface->getResource().get());
            }
            k->focus.reset();
        }
        held_keys.clear();
        if (keyboard_state) xkb_state_unref(keyboard_state);
        keyboard_state = keymap ? xkb_state_new(keymap) : nullptr;
        if (physical_keyboard_state) xkb_state_unref(physical_keyboard_state);
        physical_keyboard_state = physical_keymap ? xkb_state_new(physical_keymap) : nullptr;
    }
    void retire_grant() {
        lease = nullptr; capabilities = 0; grant.reset(); expires = {};
    }
    void complete_action() {
        // All buttons/keys were released by the operation. Keyboard focus is
        // action-scoped; passive pointer focus belongs only to its live target.
        // Never send a gratuitous leave immediately after a drag's release:
        // clients may requeue their release behind that leave while coalescing
        // motion. This is not a client-processing acknowledgement.
        finish_foreground();
        leave_keyboard();
        retire_grant();
    }
    void revoke(std::string_view reason, bool retain_pointer = false, ForegroundFailure failure = {ForegroundFailureReason::none}) {
        if (lease && trace && reason != "completed") trace->mark("agent_cancel", lane + 1);
        if (drag && drag->client && !drag->client->dead)
            send(*drag->client, failure.reason == ForegroundFailureReason::none ?
                refusal(foreground_started ? "foreground_partial_unknown" : reason) :
                refusal(foreground_started ? "foreground_partial_unknown" : reason, failure));
        drag.reset();
        finish_foreground();
        if (retain_pointer) release_pointer_button(); else leave_pointer();
        leave_keyboard(); retire_grant();
    }
    void cancel_authority(std::string_view reason, bool retain_pointer = true) {
        revoke(reason, retain_pointer);
        // Invalidate pending authority as well as active work. This also makes
        // unused signed renewals unusable in experimental builds. Keep the lane
        // reservation; v3 requires fresh TARGET admission for the next action.
        for (auto& c : clients) invalidate(*c, false);
    }
    void desktop_transition() {
        // Signals can fire before Hyprland updates its aggregate state. Revoke
        // unconditionally; an off/on pair between timer ticks must not revive
        // authority. Kill pending connections as well as the active lease so
        // a pre-transition signed grant cannot be approved after unlock.
        // Admission is gone immediately, but an unchanged live target may keep
        // inert hover just as after normal completion. A leave directly after
        // the release can interfere with the client's drag-release processing.
        revoke("desktop_changed", true);
        for (auto& c : clients) {
            // Observers and operator-control connections own no action target.
            // Keep them alive so Stop/status/evidence survives a transition.
            if (reservation != c.get() && c->token.empty()) continue;
            c->dead = true;
            if (c->source) wl_event_source_remove(c->source);
            c->source = nullptr;
            if (c->fd >= 0) close(c->fd);
            c->fd = -1;
        }
        reservation = nullptr;
        if (desktop_generation == UINT64_MAX)
            suspended = true;
        else
            ++desktop_generation;
    }
    void send(Client& c, const std::string& packet) {
        if (c.dead) return;
        const auto n = ::send(c.fd, packet.data(), packet.size(), MSG_DONTWAIT | MSG_NOSIGNAL);
        if (n < 0 || static_cast<std::size_t>(n) != packet.size()) c.dead = true;
    }
    static int accept_ready(int, std::uint32_t, void* data) {
        auto& self = *static_cast<Impl*>(data);
        for (unsigned i = 0; i < 8; ++i) {
            const auto fd = accept4(self.listener, nullptr, nullptr, SOCK_NONBLOCK | SOCK_CLOEXEC);
            if (fd < 0) break;
            ucred credentials{}; socklen_t size = sizeof(credentials);
            if (getsockopt(fd, SOL_SOCKET, SO_PEERCRED, &credentials, &size) != 0 ||
                size != sizeof(credentials) || credentials.uid != getuid() || self.clients.size() >= kMaxClients) { close(fd); continue; }
            bool owned = false;
            try {
                auto c = std::make_unique<Client>(); c->owner = &self; c->fd = fd; owned = true; c->challenge = nonce();
                c->source = wl_event_loop_add_fd(g_pCompositor->m_wlEventLoop, fd, WL_EVENT_READABLE, client_ready, c.get());
                if (!c->source) continue;
                self.clients.push_back(std::move(c));
            } catch (...) { if (!owned) close(fd); }
        }
        return 0;
    }
    static int client_ready(int fd, std::uint32_t mask, void* data) {
        auto& c = *static_cast<Client*>(data); auto& self = *c.owner;
        if (mask & (WL_EVENT_HANGUP | WL_EVENT_ERROR)) c.dead = true;
        for (unsigned i = 0; i < 8 && !c.dead; ++i) {
            // Check before reading or changing HELLO state, even if the event
            // loop's periodic expiry callback has not run yet.
            if (c.deadline.expired(c.hello, Clock::now())) { c.dead = true; break; }
            std::array<char, kMaxPacket> buffer{};
            const auto n = recv(fd, buffer.data(), buffer.size(), MSG_DONTWAIT | MSG_TRUNC);
            if (n < 0) { if (errno != EAGAIN && errno != EWOULDBLOCK && errno != EINTR) c.dead = true; break; }
            if (!n) { c.dead = true; break; }
            const auto received = Clock::now();
            if (c.deadline.expired(c.hello, received)) { c.dead = true; break; }
            c.deadline.touch(received);
            if (static_cast<std::size_t>(n) > buffer.size()) { self.send(c, refusal("invalid_request")); continue; }
            try { self.request(c, fields(std::string_view(buffer.data(), n))); }
            catch (const ForegroundFailure& failure) {
                const bool started = c.foreground_attempted;
                const bool drag_reply = self.drag && self.drag->client == &c;
                self.revoke("foreground_partial_unknown", false, failure);
                if (!drag_reply) self.send(c, refusal(ForegroundFailure::code(started), failure));
            }
            catch (...) {
                const bool foreground_partial = c.foreground_attempted;
                const bool foreground_drag_reply = foreground_partial && self.drag && self.drag->client == &c;
                if (kProduction && (self.lease == &c || self.reservation == &c)) self.revoke("invalid_request");
                if (!foreground_drag_reply) self.send(c, refusal(foreground_partial ? "foreground_partial_unknown" : "invalid_request"));
            }
        }
        if (c.dead) {
            if (self.lease == &c) self.revoke("disconnected", true);
            if (self.reservation == &c) self.reservation = nullptr;
        }
        return 0;
    }
#ifdef CUA_HYPRLAND_TEST_INPUT
    bool valid_signature(const std::string& message, const std::string& signature) const {
        if (signature.size() != 128) return false;
        const auto bytes = unhex(signature);
        auto* key = EVP_PKEY_new_raw_public_key(EVP_PKEY_ED25519, nullptr, public_key.data(), public_key.size());
        auto* ctx = EVP_MD_CTX_new();
        const bool ok = key && ctx && EVP_DigestVerifyInit(ctx, nullptr, nullptr, nullptr, key) == 1 &&
            EVP_DigestVerify(ctx, bytes.data(), bytes.size(), reinterpret_cast<const unsigned char*>(message.data()), message.size()) == 1;
        EVP_MD_CTX_free(ctx); EVP_PKEY_free(key); return ok;
    }
    void approve(Client& c, const std::vector<std::string>& f) {
        if (f.size() != 6) { send(c, refusal("invalid_grant")); return; }
        const auto deadline = number(f[3]); const auto caps = number(f[4]); const auto now = unix_ms();
        if (deadline <= now || deadline - now > 60000 || caps == 0 || caps > 15) { send(c, refusal("invalid_grant")); return; }
        const auto message = std::format("CUA_TEST_LEASE_1\n{}\n{}\n{}\n{}\n{}\n", epoch, f[1], f[2], deadline, caps);
        if (!valid_signature(message, f[5])) { send(c, refusal("invalid_grant")); return; }
        const auto found = std::ranges::find_if(clients, [&](auto& peer) {
            return !peer->dead && peer->hello && peer->challenge == f[1] && peer->token == f[2] && !peer->token.empty();
        });
        if (found == clients.end() || !refresh(**found)) { send(c, refusal("stale_target")); return; }
        if (reservation != found->get()) { send(c, refusal("lane_not_claimed")); return; }
        if (lease) { send(c, refusal("lease_busy")); return; }
        if (agent_conflict(**found)) { send(c, refusal("agent_target_busy")); return; }
        if (deadline <= (*found)->approved_deadline) { send(c, refusal("invalid_grant")); return; }
        if (!available()) { send(c, refusal("session_unavailable")); return; }
        // Bind steady-clock lifetime once; a clock change cannot extend a lease.
        lease = found->get(); capabilities = caps; expires = Clock::now() + std::chrono::milliseconds(deadline - now);
        lease->approved_deadline = deadline;
        // Approval begins the bounded active period. Time spent waiting for
        // the external operator must not consume the input connection's idle
        // budget while its newly approved lease is still valid.
        lease->deadline.touch(Clock::now());
        if (trace) trace->mark("agent_approved", lane + 1);
        send(c, R"({"ok":true})");
    }
#endif
    bool point(Client& c, double x, double y) const {
        return std::isfinite(x) && std::isfinite(y) && x >= 0 && y >= 0 && x < c.geometry[2] && y < c.geometry[3];
    }
    bool unique_primary_seat(wl_client* client) const {
        struct Scan {
            const Impl* self;
            ForegroundSeatBindings bindings;
        } scan{this, {}};
        // Hyprland's public lookup returns only the first primary binding.
        // Count classes without casting arbitrary protocol user data. Agent
        // seats are excluded only by exact resource identity, never by name.
        wl_client_for_each_resource(client, [](wl_resource* resource, void* data) {
            auto& scan = *static_cast<Scan*>(data);
            const std::string_view resource_class = wl_resource_get_class(resource);
            if (resource_class != "wl_seat") return WL_ITERATOR_CONTINUE;
            bool owned = false;
            for (const auto* peer : scan.self->peers) {
                if (!peer) continue;
                for (const auto& seat : peer->seats)
                    if (seat->wl->resource() == resource) { owned = true; break; }
                if (owned) break;
            }
            scan.bindings.observe(resource_class, owned);
            return WL_ITERATOR_CONTINUE;
        }, &scan);
        if (!scan.bindings.unique()) return false;
        if (!foreground_started) return true;
        // A release/rebind or new child resource during a drag must not leave
        // our captured delivery set different from the primary seat's set.
        const auto seat = g_pSeatManager->seatResourceForClient(client);
        if (!seat || seat != foreground_seat.lock()) return false;
        return foreground_resources_match(seat->m_pointers, foreground_pointers) &&
            foreground_resources_match(seat->m_keyboards, foreground_keyboards);
    }
    ForegroundGuard foreground_guard(const Client& c) const {
        const auto root = c.surface.lock();
        const auto geometry = target_geometry(c.window.lock(), root);
        bool pressed = !g_pInputManager->getKeysFromAllKBs().empty();
        for (const auto& kb : g_pInputManager->m_keyboards) {
            if (!kb->m_enabled || kb->isVirtual()) continue;
            for (std::uint32_t code = 0; code <= KEY_MAX && !pressed; ++code) pressed = kb->getPressed(code);
        }
        const bool exact_root = geometry && *geometry == c.geometry;
        return {
            .exact_root = exact_root,
            .primary_binding = !exact_root || unique_primary_seat(root->client()),
            .peer_conflict = agent_conflict(c),
            .physical_keys = pressed,
            .physical_buttons = g_pInputManager->hasHeldButtons(),
            .grab = bool(g_pSeatManager->m_seatGrab) || bool(g_layoutManager->dragController()->target()) ||
                !exclusive_layer_surfaces().empty(),
            .dnd = PROTO::data && PROTO::data->dndActive(),
            .constraint = g_pInputManager->isConstrained(),
            .exact_keyboard_focus = root && g_pSeatManager->m_state.keyboardFocus == root &&
                Desktop::focusState()->window() == c.window.lock() && Desktop::focusState()->surface() == root,
            .exact_pointer_focus = root && g_pSeatManager->m_state.pointerFocus == root,
        };
    }
    // Hyprland reports each keyboard's raw masks in that keyboard's own keymap
    // encoding and merges shared keyboards into the primary state. Refuse a
    // keyboard action under any state other than neutral or an unambiguous
    // Num Lock, and name Caps Lock explicitly.
    std::array<std::uint32_t, 4> capture_foreground_modifiers(bool needs_keyboard) const {
        const auto physical = g_pSeatManager->m_keyboard.lock();
        if (!physical) throw ForegroundFailure{ForegroundFailureReason::physical_keyboard};
        std::array<std::uint32_t, 4> result{};
        const auto observe = [&](const auto& kb, bool primary) {
            const std::array<std::uint32_t, 4> state{kb->m_modifiersState.depressed, kb->m_modifiersState.latched,
                kb->m_modifiersState.locked, kb->m_modifiersState.group};
            if (needs_keyboard) {
                const auto failure = foreground_key_modifier_failure(state, foreground_numlock_mask(kb->m_xkbKeymap),
                    foreground_caps_mask(kb->m_xkbKeymap));
                if (failure != ForegroundFailureReason::none) throw ForegroundFailure{failure};
                // A lock from a different encoding must not be reinterpreted
                // as the primary keymap's Num Lock.
                if (state[2] && state[2] != foreground_numlock_mask(physical_keymap))
                    throw ForegroundFailure{ForegroundFailureReason::keyboard_locked};
            }
            for (unsigned i = 0; i < 3; ++i) result[i] |= state[i];
            if (primary) result[3] = state[3];
        };
        observe(physical, true);
        for (const auto& kb : g_pInputManager->m_keyboards) {
            if (kb == physical || !kb->m_enabled || !kb->shareStates() ||
                (kb->isVirtual() && g_pInputManager->shouldIgnoreVirtualKeyboard(kb))) continue;
            observe(kb, false);
        }
        return result;
    }
    void require_foreground(Client& c) {
        if (lease != &c) throw ForegroundFailure{ForegroundFailureReason::lease};
        if (c.dead) throw ForegroundFailure{ForegroundFailureReason::client_dead};
        if (!available()) throw ForegroundFailure{ForegroundFailureReason::session_unavailable};
        if (!input_layout_qualified(c.route, foreground_needs_keyboard, layout_qualified()))
            throw ForegroundFailure{ForegroundFailureReason::unsupported_layout};
        if (Clock::now() >= expires) throw ForegroundFailure{ForegroundFailureReason::lease_expired};
        // The chord was admitted under the human keyboard's state. A lock or
        // modifier change during the action, including one caused by
        // activation, changes what the remaining events mean.
        if (foreground_needs_keyboard && capture_foreground_modifiers(true) != foreground_modifiers)
            throw ForegroundFailure{ForegroundFailureReason::keyboard_state};
        const auto failure = foreground_guard(c).dispatch_failure(foreground_needs_pointer);
        if (failure != ForegroundFailureReason::none) throw ForegroundFailure{failure};
    }
    void finish_foreground() {
        foreground_activating = false;
        if (!foreground_started) return;
        // Release only our own synthetic state, and only while these resources
        // still address the original root. A focus loss must not send to its successor.
        const auto root = foreground_surface.lock();
        if (root && root->good() && g_pSeatManager->m_state.pointerFocus == root)
            for (const auto& weak : foreground_pointers)
                if (const auto p = weak.lock(); p && p->good() && held_button) {
                    p->sendButton(event_ms(), held_button, WL_POINTER_BUTTON_STATE_RELEASED);
                    p->sendFrame();
                }
        if (foreground_keyboard_used && root && root->good() && g_pSeatManager->m_state.keyboardFocus == root) {
            // Synthetic keys change only private state. If human input cancelled
            // the action, restore the human keyboard's current state, not the
            // state captured at admission.
            const auto restore = g_pSeatManager->m_keyboard.lock() ?
                capture_foreground_modifiers(false) : foreground_modifiers;
            for (const auto& weak : foreground_keyboards)
                if (const auto k = weak.lock(); k && k->good()) {
                    for (auto code : held_keys) k->sendKey(event_ms(), code, WL_KEYBOARD_KEY_STATE_RELEASED);
                    k->sendMods(restore[0], restore[1], restore[2], restore[3]);
                }
        }
        held_button = 0; held_keys.clear();
        foreground_pointers.clear(); foreground_keyboards.clear(); foreground_surface.reset(); foreground_seat.reset();
        foreground_started = false;
        foreground_keyboard_used = false;
        foreground_needs_keyboard = false;
    }
    void start_foreground(Client& c, double x, double y, bool needs_pointer, bool needs_keyboard,
                          const std::array<std::uint32_t, 4>& modifiers) {
        const auto root = c.surface.lock();
        const auto physical = g_pSeatManager->m_keyboard.lock();
        const auto failure = foreground_guard(c).activation_failure();
        if (failure != ForegroundFailureReason::none) throw ForegroundFailure{failure};
        if (needs_keyboard && !physical) throw ForegroundFailure{ForegroundFailureReason::physical_keyboard};
        if (needs_keyboard && !physical_keyboard_state) throw ForegroundFailure{ForegroundFailureReason::keyboard_state};
        if (needs_pointer && !g_pSeatManager->m_mouse) throw ForegroundFailure{ForegroundFailureReason::physical_pointer};
        const Vector2D local{x + c.geometry[0] - c.geometry[4], y + c.geometry[1] - c.geometry[5]};
        if (needs_pointer && (!point(c, x, y) || root->at(local, true).first != root)) throw ForegroundFailure{ForegroundFailureReason::pointer_target};
        const auto seat = g_pSeatManager->seatResourceForClient(root->client());
        if (!seat || !seat->good()) throw ForegroundFailure{ForegroundFailureReason::seat_resource};
        foreground_pointers.clear(); foreground_keyboards.clear();
        for (const auto& p : seat->m_pointers) if (p && p->good()) foreground_pointers.push_back(p);
        for (const auto& k : seat->m_keyboards) if (k && k->good()) foreground_keyboards.push_back(k);
        if (needs_pointer && foreground_pointers.empty()) throw ForegroundFailure{ForegroundFailureReason::pointer_resources};
        if (needs_keyboard && foreground_keyboards.empty())
            throw ForegroundFailure{ForegroundFailureReason::keyboard_resources};
        foreground_modifiers = {};
        if (needs_keyboard) {
            // Keep the human keyboard's modifiers and locks. The caller admitted
            // this chord under exactly this state before consuming the grant.
            foreground_modifiers = modifiers;
            xkb_state_update_mask(physical_keyboard_state, foreground_modifiers[0], foreground_modifiers[1],
                foreground_modifiers[2], 0, 0, foreground_modifiers[3]);
        }
        foreground_surface = root;
        foreground_seat = seat;
        foreground_needs_pointer = needs_pointer;
        foreground_needs_keyboard = needs_keyboard;
        c.foreground_attempted = true;
        foreground_started = true;
        foreground_activating = true;
        // Activation intentionally persists. Never save, borrow, or restore focus.
        if (g_pSeatManager->m_state.keyboardFocus != root || Desktop::focusState()->window() != c.window.lock() ||
            Desktop::focusState()->surface() != root)
            Desktop::focusState()->fullWindowFocus(c.window.lock(), Desktop::FOCUS_REASON_OTHER, root);
        foreground_activating = false;
        if (lease != &c) throw ForegroundFailure{ForegroundFailureReason::lease};
        const auto focus_failure = foreground_guard(c).dispatch_failure(false);
        if (focus_failure != ForegroundFailureReason::none) throw ForegroundFailure{focus_failure};
        if (!needs_pointer) { require_foreground(c); return; }
        foreground_activating = true;
        ::Pointer::mgr()->warpTo({x + c.geometry[0], y + c.geometry[1]});
        if (lease != &c) throw ForegroundFailure{ForegroundFailureReason::lease};
        const auto warp_failure = foreground_guard(c).dispatch_failure(false);
        if (warp_failure != ForegroundFailureReason::none) throw ForegroundFailure{warp_failure};
        g_pSeatManager->setPointerFocus(root, local);
        foreground_activating = false;
        require_foreground(c);
        foreground_motion(c, x, y);
    }
    void foreground_motion(Client& c, double x, double y) {
        require_foreground(c);
        const Vector2D local{x + c.geometry[0] - c.geometry[4], y + c.geometry[1] - c.geometry[5]};
        if (!point(c, x, y) || c.surface.lock()->at(local, true).first != c.surface.lock()) throw ForegroundFailure{ForegroundFailureReason::pointer_target};
        ::Pointer::mgr()->warpTo({x + c.geometry[0], y + c.geometry[1]});
        require_foreground(c);
        for (const auto& weak : foreground_pointers) {
            const auto p = weak.lock(); if (!p || !p->good()) throw ForegroundFailure{ForegroundFailureReason::pointer_resources};
            p->sendMotion(event_ms(), local); p->sendFrame();
        }
    }
    void foreground_button(Client& c, std::uint32_t code, bool pressed) {
        require_foreground(c);
        // Mark ownership before sending, so a later resource failure can unwind.
        if (pressed) held_button = code;
        for (const auto& weak : foreground_pointers) {
            const auto p = weak.lock(); if (!p || !p->good()) throw ForegroundFailure{ForegroundFailureReason::pointer_resources};
            p->sendButton(event_ms(), code, pressed ? WL_POINTER_BUTTON_STATE_PRESSED : WL_POINTER_BUTTON_STATE_RELEASED);
            p->sendFrame();
        }
        held_button = pressed ? code : 0;
    }
    void foreground_key(Client& c, std::uint32_t code, bool pressed) {
        require_foreground(c);
        foreground_keyboard_used = true;
        xkb_state_update_key(physical_keyboard_state, code + 8, pressed ? XKB_KEY_DOWN : XKB_KEY_UP);
        if (pressed) held_keys.push_back(code); else std::erase(held_keys, code);
        for (const auto& weak : foreground_keyboards) {
            const auto k = weak.lock(); if (!k || !k->good()) throw ForegroundFailure{ForegroundFailureReason::keyboard_resources};
            k->sendKey(event_ms(), code, pressed ? WL_KEYBOARD_KEY_STATE_PRESSED : WL_KEYBOARD_KEY_STATE_RELEASED);
            k->sendMods(xkb_state_serialize_mods(physical_keyboard_state, XKB_STATE_MODS_DEPRESSED),
                xkb_state_serialize_mods(physical_keyboard_state, XKB_STATE_MODS_LATCHED),
                xkb_state_serialize_mods(physical_keyboard_state, XKB_STATE_MODS_LOCKED),
                xkb_state_serialize_layout(physical_keyboard_state, XKB_STATE_LAYOUT_EFFECTIVE));
        }
    }
    bool pointer_enter(Client& c, double x, double y) {
        const auto root = c.surface.lock(); if (!root) return false;
        // Initial experiment refuses subsurface targets instead of misrouting.
        const Vector2D local{x + c.geometry[0] - c.geometry[4], y + c.geometry[1] - c.geometry[5]};
        const auto hit = root->at(local, true);
        if (hit.first != root) return false;
        unsigned count = 0;
        for (auto& p : pointers) {
            if (p->dead || !p->wl->resource() || p->wl->client() != root->client()) continue;
            if (p->focus != root) {
                if (const auto old = p->focus.lock(); old && old->good()) p->wl->sendLeave(serial(), old->getResource().get());
                p->focus = root;
                p->wl->sendEnter(serial(), root->getResource().get(), wl_fixed_from_double(local.x), wl_fixed_from_double(local.y));
            }
            p->wl->sendMotion(event_ms(), wl_fixed_from_double(local.x), wl_fixed_from_double(local.y));
            if (p->wl->version() >= 5) p->wl->sendFrame();
            ++count;
        }
        if (count && !pointer_target.matches(c.window.lock(), root, c.geometry)) {
            pointer_unmap.reset(); pointer_destroy.reset();
            pointer_target.capture(c.window.lock(), root, c.geometry);
            // These listeners belong to the lane, never the socket Client.
            const auto window = c.window.lock();
            pointer_unmap = window->m_events.unmap.listen([this] { revoke("stale_target"); });
            pointer_destroy = window->m_events.destroy.listen([this] { revoke("stale_target"); });
        }
        return count > 0;
    }
    void button(std::uint32_t value, bool pressed) {
        for (auto& p : pointers) {
            if (p->dead || !p->wl->resource() || !p->focus) continue;
            p->wl->sendButton(serial(), event_ms(), value, pressed ? WL_POINTER_BUTTON_STATE_PRESSED : WL_POINTER_BUTTON_STATE_RELEASED);
            if (p->wl->version() >= 5) p->wl->sendFrame();
        }
        held_button = pressed ? value : 0;
    }
    bool keyboard_enter(Client& c) {
        const auto root = c.surface.lock();
        if (!root || !keyboard_state) return false;
        unsigned count = 0;
        for (auto& k : keyboards) {
            if (k->dead || !k->wl->resource() || k->wl->client() != root->client()) continue;
            if (k->focus != root) {
                if (const auto old = k->focus.lock(); old && old->good()) k->wl->sendLeave(serial(), old->getResource().get());
                k->focus = root;
                wl_array keys{};
                k->wl->sendEnter(serial(), root->getResource().get(), &keys);
                k->wl->sendModifiers(serial(), 0, 0, 0, 0);
            }
            ++count;
        }
        return count > 0;
    }
    void key(std::uint32_t code, bool pressed) {
        xkb_state_update_key(keyboard_state, code + 8, pressed ? XKB_KEY_DOWN : XKB_KEY_UP);
        if (pressed) held_keys.push_back(code); else std::erase(held_keys, code);
        for (auto& k : keyboards) {
            if (k->dead || !k->wl->resource() || !k->focus) continue;
            k->wl->sendKey(serial(), event_ms(), code, pressed ? WL_KEYBOARD_KEY_STATE_PRESSED : WL_KEYBOARD_KEY_STATE_RELEASED);
            k->wl->sendModifiers(serial(), xkb_state_serialize_mods(keyboard_state, XKB_STATE_MODS_DEPRESSED),
                xkb_state_serialize_mods(keyboard_state, XKB_STATE_MODS_LATCHED),
                xkb_state_serialize_mods(keyboard_state, XKB_STATE_MODS_LOCKED),
                xkb_state_serialize_layout(keyboard_state, XKB_STATE_LAYOUT_EFFECTIVE));
        }
    }
    void request(Client& c, const std::vector<std::string>& f) {
        if (!foreground_started) c.foreground_attempted = false;
        sync_keymap();
        if (c.dead) return;
        const auto& command = f[0];
        if (command == "HELLO") {
            if (f.size() != 1 || c.hello) { send(c, refusal("invalid_request")); return; }
            c.hello = true;
            if (kProduction)
                send(c, std::format(R"({{"ok":true,"protocol":3,"epoch":"{}","foreground_target":true}})", epoch));
            else
                send(c, std::format(R"({{"ok":true,"protocol":0,"epoch":"{}","challenge":"{}"}})", epoch, c.challenge));
            return;
        }
        if (!c.hello) { send(c, refusal("invalid_request")); return; }
        if (command == "CLAIM" && f.size() == 1) {
            if (reservation && reservation != &c) { send(c, refusal("lane_busy")); return; }
            reservation = &c;
            send(c, std::format(R"({{"ok":true,"lane":{}}})", lane)); return;
        }
        if (command == "STOP" && f.size() == 1) {
            if (kProduction) {
                if (reservation != &c) { send(c, refusal("lane_not_claimed")); return; }
                cancel_authority("stopped");
            } else {
                for (auto* peer : peers) if (peer) peer->cancel_authority("stopped");
            }
            send(c, R"({"ok":true})"); return;
        }
        if (command == "CANCEL" && f.size() == 1) {
            if (kProduction && reservation != &c) { send(c, refusal("lane_not_claimed")); return; }
            cancel_authority("cancelled"); send(c, R"({"ok":true})"); return;
        }
        if (trace && ((command == "TRACE_START" || command == "TRACE_STOP") && f.size() == 1)) {
            send(c, trace->request(command)); return;
        }
        if (trace && command == "TRACE_READ" && f.size() == 2) {
            const auto after = number(f[1]);
            if (after > 32768) { send(c, refusal("invalid_request")); return; }
            send(c, trace->request(command, after)); return;
        }
#ifdef CUA_HYPRLAND_TEST_INPUT
        if (command == "APPROVE") { approve(c, f); return; }
#endif
        if (reservation != &c) { send(c, refusal("lane_not_claimed")); return; }
        if (command == "TARGET" || (kProduction && command == "FOREGROUND_TARGET")) {
            if (drag) { send(c, refusal("invalid_request")); return; }
            const auto route = command == "FOREGROUND_TARGET" ? InputRoute::primary_foreground : InputRoute::independent;
            if (!bind_input_route(c.route, route)) { invalidate(c); send(c, refusal("route_mismatch")); return; }
            if (f.size() != (kProduction ? 4u : 3u)) {
                if (kProduction) invalidate(c);
                send(c, refusal("invalid_request")); return;
            }
            // A new admission attempt always retires any unused old grant.
            // Do not leave an unchanged surface merely to refresh authority.
            if (kProduction) retire_grant();
            const auto requested_cap = kProduction ? number(f[3]) : 0;
            if (kProduction && (!InputGrant::single_operation(requested_cap) ||
                (requested_cap == 16 && route != InputRoute::primary_foreground))) { invalidate(c); send(c, refusal("unsupported")); return; }
            if (kProduction && !available()) { invalidate(c, false); send(c, refusal("session_unavailable")); return; }
            if (!input_layout_qualified(route, requested_cap == 2, layout_qualified())) { invalidate(c, false); send(c, refusal("unsupported_layout")); return; }
            const auto pid = number(f[1]); const auto address = number(f[2], 16);
            PHLWINDOW window;
            for (const auto& w : Desktop::windowState()->windows())
                if (reinterpret_cast<std::uintptr_t>(w.get()) == address && static_cast<std::uint64_t>(window_pid(w)) == pid) window = w;
            if (!window || window_is_x11(window) || !window_mapped(window) || window->isHidden() || !window->resource()) {
                invalidate(c); send(c, refusal("stale_target")); return;
            }
            // Retire the old target before rebinding: even if the new target's
            // geometry validation fails, a reserved lane must not strand it.
            if (pointer_target.entered() && !pointer_target.same_target(window, window->resource()))
                revoke("stale_target");
            if (c.window != window || c.surface != window->resource() || c.token.empty()) {
                // Rebinding authority (including a new socket owner) may reuse
                // unchanged passive hover. Compare the actual target below.
                invalidate(c, false); c.unmap.reset(); c.destroy.reset();
                c.window = window; c.surface = window->resource(); c.token = nonce(); c.revision = 1;
                c.unmap = window->m_events.unmap.listen([this, &c] { invalidate(c); });
                c.destroy = window->m_events.destroy.listen([this, &c] { invalidate(c); });
            }
            if (!refresh(c)) { invalidate(c); send(c, refusal("stale_target")); return; }
            if (pointer_target.entered() && !pointer_target.matches(window, c.surface.lock(), c.geometry))
                revoke("stale_target");
            // Only a valid fresh TARGET can retire an orphan on another lane.
            // Dispatch/conflict checks never evict peer state or replay input.
            if (available() && !primary_conflict(c)) retire_orphan_hover(c);
            if (kProduction) {
                if (primary_conflict(c)) { invalidate(c); send(c, refusal("primary_target_busy")); return; }
                if (agent_conflict(c)) { invalidate(c); send(c, refusal("agent_target_busy")); return; }
                if (route == InputRoute::primary_foreground) {
                    const auto failure = foreground_guard(c).activation_failure();
                    if (failure != ForegroundFailureReason::none) {
                        invalidate(c); send(c, refusal("primary_target_busy", ForegroundFailure{failure})); return;
                    }
                }
                if (route == InputRoute::primary_foreground) leave_pointer();
                c.foreground_attempted = false;
                c.token = nonce();
                grant.arm(requested_cap, Clock::now());
                lease = &c; capabilities = requested_cap; expires = grant.deadline();
                if (trace) trace->mark("agent_admitted", lane + 1);
            }
            c.has_bound_target = true;
            if (route == InputRoute::primary_foreground) {
                send(c, std::format(R"({{"ok":true,"target":"{}","revision":{},"width":{},"height":{},"route":"primary_foreground"}})",
                    c.token, c.revision, c.geometry[2], c.geometry[3])); return;
            }
            send(c, std::format(R"({{"ok":true,"target":"{}","revision":{},"width":{},"height":{}}})", c.token, c.revision, c.geometry[2], c.geometry[3])); return;
        }
        const std::uint64_t cap = command == "CLICK" ? 1 : command == "KEY" ? 2 : command == "SCROLL" ? 4 : command == "DRAG" ? 8 :
            command == "ACTIVATE" && kProduction && c.route == InputRoute::primary_foreground ? 16 : 0;
        const std::size_t count = command == "CLICK" ? 8 : command == "KEY" ? 6 : command == "SCROLL" ? 8 : command == "ACTIVATE" ? 4 : 9;
        if (!cap) { send(c, refusal("unsupported")); return; }
        if (f.size() != count) { send(c, refusal("invalid_request")); return; }
        const auto sequence = number(f[1]);
        if (sequence <= c.sequence) { send(c, refusal("replay")); return; }
        c.sequence = sequence;
        if (c.token.empty() || f[2] != c.token || !refresh(c)) { send(c, refusal("stale_target")); return; }
        if (number(f[3]) != c.revision) { if (kProduction) revoke("stale_geometry"); send(c, refusal("stale_geometry")); return; }
        if (!available()) { revoke("session_unavailable", true); send(c, refusal("session_unavailable")); return; }
        if (!input_layout_qualified(c.route, cap == 2, layout_qualified())) { revoke("unsupported_layout", true); send(c, refusal("unsupported_layout")); return; }
        if (lease && Clock::now() >= expires) revoke("lease_expired");
        if (drag) { send(c, refusal("lease_busy")); return; }
        if (lease != &c || !(capabilities & cap) || (kProduction && !grant.permits(cap, Clock::now()))) {
            if (kProduction) {
                revoke("action_not_admitted");
                send(c, refusal("action_not_admitted"));
            } else {
                send(c, std::format(R"({{"ok":false,"code":"pending_operator_approval","detail":"external test operator approval required","epoch":"{}","challenge":"{}","target":"{}"}})", epoch, c.challenge, c.token));
            }
            return;
        }
        if (primary_conflict(c)) {
            if (kProduction) revoke("primary_target_busy");
            send(c, refusal("primary_target_busy")); return;
        }
        if (agent_conflict(c)) {
            if (kProduction) revoke("agent_target_busy");
            send(c, refusal("agent_target_busy")); return;
        }
        if (c.route == InputRoute::primary_foreground) {
            foreground_request(c, f, cap);
            return;
        }
        if (command == "KEY") {
            const auto code = number(f[4]); const auto mods = number(f[5]);
            if (code == 0 || code > 247 || mods > 15 || code == 58 || code == 69 || code == 70) { send(c, refusal("unsupported")); return; }
            if (!consume_grant(c, cap)) return;
            if (!keyboard_enter(c)) { send(c, refusal("client_not_bound")); return; }
            // Every key is released in this handler; sync_key_repeat relies on it.
            const std::array<std::uint32_t, 4> keys{42, 29, 56, 125};
            for (unsigned i = 0; i < 4; ++i) if ((mods & (1u << i)) && keys[i] != code) key(keys[i], true);
            key(code, true); key(code, false);
            for (int i = 3; i >= 0; --i) if ((mods & (1u << i)) && keys[i] != code) key(keys[i], false);
        } else {
            const auto x = real(f[4]), y = real(f[5]);
            if (!point(c, x, y)) { send(c, refusal("invalid_request")); return; }
            if (command == "CLICK") {
                const auto btn = number(f[6]), clicks = number(f[7]);
                if (btn < 272 || btn > 274 || clicks < 1 || clicks > 2) { send(c, refusal("invalid_request")); return; }
                if (!consume_grant(c, cap)) return;
                if (!pointer_enter(c, x, y)) { send(c, refusal("client_not_bound")); return; }
                for (unsigned i = 0; i < clicks; ++i) { button(btn, true); button(btn, false); }
            } else if (command == "SCROLL") {
                const auto axis = number(f[6]); const auto value = real(f[7]);
                if (axis > 1 || value == 0 || std::abs(value) > 1000) { send(c, refusal("invalid_request")); return; }
                if (!consume_grant(c, cap)) return;
                if (!pointer_enter(c, x, y)) { send(c, refusal("client_not_bound")); return; }
                for (auto& p : pointers) {
                    if (p->dead || !p->wl->resource() || !p->focus) continue;
                    if (p->wl->version() >= 5) p->wl->sendAxisSource(WL_POINTER_AXIS_SOURCE_WHEEL);
                    p->wl->sendAxis(event_ms(), static_cast<wl_pointer_axis>(axis), wl_fixed_from_double(value));
                    if (p->wl->version() >= 5) p->wl->sendFrame();
                }
            } else {
                const auto x2 = real(f[6]), y2 = real(f[7]); const auto duration = number(f[8]);
                if (!point(c, x2, y2) || duration < 50 || duration > 2000) { send(c, refusal("invalid_request")); return; }
                if (Clock::now() + std::chrono::milliseconds(duration + 50) >= expires) { send(c, refusal("lease_expired")); return; }
                if (!consume_grant(c, cap)) return;
                if (!pointer_enter(c, x, y)) { send(c, refusal("client_not_bound")); return; }
                if (trace) trace->mark("agent_drag_start", lane + 1);
                button(272, true);
                drag.emplace(Drag{&c, x, y, x2, y2, Clock::now(), static_cast<unsigned>(duration), DragGeometry{c.revision}});
                send(c, R"({"ok":true,"phase":"started"})"); return;
            }
        }
        ++dispatches;
        if (trace) trace->mark("agent_action_end", lane + 1);
        if (kProduction) complete_action();
        send(c, kDelivered);
    }
    void foreground_request(Client& c, const std::vector<std::string>& f, std::uint64_t cap) {
        const auto& command = f[0];
        double x = c.geometry[2] / 2, y = c.geometry[3] / 2, x2 = 0, y2 = 0, value = 0;
        std::uint64_t code = 0, mods = 0, clicks = 0, axis = 0, duration = 0;
        if (command == "KEY") {
            code = number(f[4]); mods = number(f[5]);
            if (code == 0 || code > 247 || mods > 15 || code == 58 || code == 69 || code == 70) {
                send(c, refusal("unsupported")); return;
            }
        } else if (command != "ACTIVATE") {
            x = real(f[4]); y = real(f[5]);
            if (!point(c, x, y)) { send(c, refusal("invalid_request")); return; }
            if (command == "CLICK") {
                code = number(f[6]); clicks = number(f[7]);
                if (code < 272 || code > 274 || clicks < 1 || clicks > 2) { send(c, refusal("invalid_request")); return; }
            } else if (command == "SCROLL") {
                axis = number(f[6]); value = real(f[7]);
                if (axis > 1 || value == 0 || std::abs(value) > 1000) { send(c, refusal("invalid_request")); return; }
            } else {
                x2 = real(f[6]); y2 = real(f[7]); duration = number(f[8]);
                if (!point(c, x2, y2) || duration < 50 || duration > 2000) { send(c, refusal("invalid_request")); return; }
                if (Clock::now() + std::chrono::milliseconds(duration + 50) >= expires) { send(c, refusal("lease_expired")); return; }
            }
        }
        std::array<std::uint32_t, 4> modifiers{};
        if (command == "KEY") {
            // Simulate the whole chord under the human keyboard's live state
            // before consuming the grant or changing focus. Num Lock and Caps
            // Lock stay as they are; a chord whose meaning they or the layout
            // would change refuses with its specific reason.
            modifiers = capture_foreground_modifiers(true);
            const auto failure = foreground_chord_failure(physical_keymap, keymap, static_cast<std::uint32_t>(code),
                static_cast<std::uint32_t>(mods), modifiers);
            if (failure != ForegroundFailureReason::none) throw ForegroundFailure{failure};
        }
        if (!consume_grant(c, cap)) return;
        start_foreground(c, x, y, command != "KEY" && command != "ACTIVATE", command == "KEY", modifiers);
        if (command == "KEY") {
            const std::array<std::uint32_t, 4> keys{42, 29, 56, 125};
            for (unsigned i = 0; i < 4; ++i) if ((mods & (1u << i)) && keys[i] != code) foreground_key(c, keys[i], true);
            foreground_key(c, code, true); foreground_key(c, code, false);
            for (int i = 3; i >= 0; --i) if ((mods & (1u << i)) && keys[i] != code) foreground_key(c, keys[i], false);
        } else if (command == "CLICK") {
            for (unsigned i = 0; i < clicks; ++i) { foreground_button(c, code, true); foreground_button(c, code, false); }
        } else if (command == "SCROLL") {
            require_foreground(c);
            for (const auto& weak : foreground_pointers) {
                const auto p = weak.lock(); if (!p || !p->good()) throw ForegroundFailure{ForegroundFailureReason::pointer_resources};
                p->sendAxisSource(WL_POINTER_AXIS_SOURCE_WHEEL);
                p->sendAxis(event_ms(), static_cast<wl_pointer_axis>(axis), value); p->sendFrame();
            }
        } else if (command == "DRAG") {
            foreground_button(c, 272, true);
            drag.emplace(Drag{&c, x, y, x2, y2, Clock::now(), static_cast<unsigned>(duration), DragGeometry{c.revision}});
            send(c, R"({"ok":true,"phase":"started"})"); return;
        }
        require_foreground(c);
        ++dispatches;
        complete_action();
        send(c, kForegroundDelivered);
    }
    bool consume_grant(Client& c, std::uint64_t capability) {
        if (!kProduction) return true;
        capabilities = 0;
        if (grant.consume(capability, Clock::now())) return true;
        revoke("action_not_admitted");
        send(c, refusal("action_not_admitted"));
        return false;
    }
    static int tick(void* data) {
        auto& self = *static_cast<Impl*>(data);
        try { self.step(); } catch (...) { self.revoke("internal_error"); }
        wl_event_source_timer_update(self.timer, self.retired ? 500 : 16); return 0;
    }
    void guard_targets() {
        if (lease) {
            const bool keyboard_action = (capabilities & 2) != 0 || foreground_needs_keyboard;
            if (lease->dead) revoke("disconnected", true);
            else if (Clock::now() >= expires) revoke("lease_expired");
            else if (!available() || !input_layout_qualified(lease->route, keyboard_action, layout_qualified()))
                revoke("cancelled", true);
            else if (!refresh(*lease) || primary_conflict(*lease) || agent_conflict(*lease) ||
                (drag && !drag->geometry.matches(lease->revision))) revoke("cancelled");
        }
        if (pointer_target.entered()) {
            const auto surface = pointer_target.surface();
            const auto geometry = target_geometry(pointer_target.window(), surface);
            const bool bound = std::ranges::any_of(pointers, [&](const auto& p) {
                return !p->dead && p->wl->resource() && surface && p->focus == surface;
            });
            // Availability controls admission, not passive pointer presence.
            // Retention never excuses a changed target, binding, or conflict.
            if (!geometry || *geometry != pointer_target.geometry() ||
                !bound || primary_conflict(surface) || agent_conflict(surface)) revoke("cancelled");
        }
    }
    void step() {
        if (!retired) sync_keymap();
        for (auto& c : clients) if (c->deadline.expired(c->hello, Clock::now())) c->dead = true;
        guard_targets();
        if (drag) {
            const auto d = *drag;
            const auto elapsed = std::chrono::duration<double, std::milli>(Clock::now() - d.start).count();
            const auto progress = std::min(elapsed / d.duration, 1.0);
            if (d.client->route == InputRoute::primary_foreground) {
                foreground_motion(*d.client, d.x1 + (d.x2 - d.x1) * progress, d.y1 + (d.y2 - d.y1) * progress);
                if (progress >= 1) {
                    foreground_button(*d.client, 272, false); drag.reset(); ++dispatches;
                    complete_action(); send(*d.client, kForegroundDelivered);
                }
            } else if (!pointer_enter(*d.client, d.x1 + (d.x2 - d.x1) * progress, d.y1 + (d.y2 - d.y1) * progress)) revoke("client_not_bound");
            else if (progress >= 1) {
                button(272, false); drag.reset(); ++dispatches;
                if (trace) trace->mark("agent_drag_end", lane + 1);
                if (kProduction) complete_action();
                send(*d.client, kDelivered);
            }
        }
        if (lease && lease->dead) revoke("disconnected", true);
        if (reservation && reservation->dead) reservation = nullptr;
        std::erase_if(clients, [](auto& c) { return c->dead; });
        std::erase_if(pointers, [](auto& p) { return p->dead; });
        std::erase_if(keyboards, [](auto& k) { return k->dead; });
        std::erase_if(touches, [](auto& t) { return t->dead; });
        std::erase_if(seats, [](auto& s) { return s->dead; });
    }
};

// Hyprland 0.56.2 signals run synchronously on the compositor thread. Keep
// their ownership explicit and detach before retiring the seats. No polling
// or aggregate-state comparison substitutes for this transition boundary.
struct InputExperiment::DesktopListeners {
    struct MonitorListeners {
        PHLMONITORREF monitor;
        CHyprSignalListener dpms, mode;
    };
    InputExperiment& owner;
    std::vector<MonitorListeners> monitors;
    CHyprSignalListener lock, unlock, active, layout, added, removed, destroyed;
    CHyprSignalListener keyboard_layout, pointer_focus, keyboard_focus;
    CHyprSignalListener mouse_move, mouse_button, mouse_axis, keyboard_key, touch_down, tablet_tip;

    explicit DesktopListeners(InputExperiment& input) : owner(input) {
        lock = g_pSessionLockManager->m_events.lock.listen([this] { changed(); });
        unlock = g_pSessionLockManager->m_events.unlock.listen([this] { changed(); });
        if (g_pCompositor->m_aqBackend->hasSession())
            active = g_pCompositor->m_aqBackend->session->events.changeActive.listen([this] { changed(); });
        layout = Event::bus()->m_events.monitor.layoutChanged.listen([this] { changed(); });
        if (kProduction) {
            keyboard_layout = Event::bus()->m_events.input.keyboard.layout.listen(
                [this](SP<IKeyboard>, const std::string&) { changed(); });
            pointer_focus = g_pSeatManager->m_events.pointerFocusChange.listen([this] { primary_changed(); });
            keyboard_focus = g_pSeatManager->m_events.keyboardFocusChange.listen([this] { primary_changed(); });
            // These notifications precede physical delivery. Retire our owned
            // press before the user's event can become held on the same resource.
            mouse_move = Event::bus()->m_events.input.mouse.move.listen([this](Vector2D, Event::SCallbackInfo&) { external_input(); });
            mouse_button = Event::bus()->m_events.input.mouse.button.listen([this](IPointer::SButtonEvent, Event::SCallbackInfo&) { external_input(); });
            mouse_axis = Event::bus()->m_events.input.mouse.axis.listen([this](IPointer::SAxisEvent, Event::SCallbackInfo&) { external_input(); });
            keyboard_key = Event::bus()->m_events.input.keyboard.key.listen([this](IKeyboard::SKeyEvent, Event::SCallbackInfo&) { external_input(); });
            touch_down = Event::bus()->m_events.input.touch.down.listen([this](ITouch::SDownEvent, Event::SCallbackInfo&) { external_input(); });
            tablet_tip = Event::bus()->m_events.input.tablet.tip.listen([this](CTablet::STipEvent, Event::SCallbackInfo&) { external_input(); });
        }
        added = Event::bus()->m_events.monitor.preAdded.listen([this](PHLMONITOR monitor) {
            changed(); watch(monitor);
        });
        removed = Event::bus()->m_events.monitor.preRemoved.listen([this](PHLMONITOR) { changed(); });
        destroyed = Event::bus()->m_events.monitor.destroyMon.listen([this](PHLMONITOR monitor) {
            changed();
            std::erase_if(monitors, [&](const auto& entry) { return !entry.monitor || entry.monitor == monitor; });
        });
        for (const auto& monitor : State::monitorState()->allMonitors()) watch(monitor);
    }
    void changed() {
        for (auto& lane : owner.lanes_) lane->desktop_transition();
    }
    void external_input() {
        for (auto& lane : owner.lanes_)
            if (lane->lease && lane->lease->route == InputRoute::primary_foreground)
                lane->cancel_authority("foreground_interrupted", false);
    }
    void primary_changed() {
        for (auto& lane : owner.lanes_) {
            if ((lane->lease && lane->primary_conflict(*lane->lease)) ||
                (lane->pointer_target.entered() && lane->primary_conflict(lane->pointer_target.surface())))
                lane->cancel_authority("primary_target_busy", false);
        }
    }
    void watch(PHLMONITOR monitor) {
        if (!monitor || std::ranges::any_of(monitors, [&](const auto& entry) { return entry.monitor == monitor; })) return;
        MonitorListeners listeners;
        listeners.monitor = monitor;
        listeners.dpms = monitor->m_events.dpmsChanged.listen([this] { changed(); });
        listeners.mode = monitor->m_events.modeChanged.listen([this] { changed(); });
        monitors.push_back(std::move(listeners));
    }
};

InputExperiment::InputExperiment(const std::string& directory, void* plugin) {
    SeatLifetime lifetime(directory);
    for (unsigned i = 0; i < lanes_.size(); ++i) lanes_[i] = std::make_unique<Impl>(directory, i);
    for (auto& lane : lanes_) { lane->peers = {lanes_[0].get(), lanes_[1].get()}; lane->start(); }
#if defined(CUA_HYPRLAND_TEST_INPUT) || defined(CUA_HYPRLAND_INPUT_TRACE)
    trace_ = std::make_unique<PrimaryTrace>(plugin, [this](wl_resource* resource) {
        for (unsigned i = 0; i < lanes_.size(); ++i) {
            for (const auto& p : lanes_[i]->pointers) if (p->wl->resource() == resource) return i + 1;
            for (const auto& k : lanes_[i]->keyboards) if (k->wl->resource() == resource) return i + 1;
        }
        return 0u;
    });
    for (auto& lane : lanes_) lane->trace = trace_.get();
#else
    (void)plugin;
#endif
    desktop_listeners_ = std::make_unique<DesktopListeners>(*this);
    lifetime.publish();
}
InputExperiment::~InputExperiment() {
    desktop_listeners_.reset();
    for (auto& lane : lanes_) { lane->retire(); lane->trace = nullptr; lane->peers = {}; }
    trace_.reset();
    // Intentional process-lifetime ownership: callbacks, removed global, and
    // remaining client-owned resources cannot outlive their Impl. The instance
    // marker refuses replacement modules, so this retains at most two lanes.
    for (auto& lane : lanes_) (void)lane.release();
}
void InputExperiment::suspend() {
    for (auto& lane : lanes_) lane->suspend();
}
void InputExperiment::resume() {
    try {
        for (auto& lane : lanes_) lane->resume();
    } catch (...) {
        // Partial transport setup must not leave one admitted lane behind.
        suspend();
        throw;
    }
}
std::string InputExperiment::status_json() const {
    std::string states;
    for (const auto& lane : lanes_) {
        if (!states.empty()) states += ',';
        const bool pointer_focus = std::ranges::any_of(lane->pointers, [](const auto& p) { return !p->dead && bool(p->focus); });
        const bool keyboard_focus = std::ranges::any_of(lane->keyboards, [](const auto& k) { return !k->dead && bool(k->focus); });
        states += std::format(R"({{"lane":{},"epoch":"{}","desktop_generation":{},"reserved":{},"socket_cleanup":"{}","lease_active":{},"seat_resources":{},"pointer_resources":{},"keyboard_resources":{},"dispatches":{},"held_button":{},"held_keys":{},"drag_active":{},"pointer_focus":{},"keyboard_focus":{}}})",
            lane->lane, lane->epoch, lane->desktop_generation, lane->reservation != nullptr, lane->socket_cleanup, lane->lease != nullptr, lane->seats.size(), lane->pointers.size(), lane->keyboards.size(), lane->dispatches,
            lane->held_button, lane->held_keys.size(), lane->drag.has_value(), pointer_focus, keyboard_focus);
    }
    // Aggregate legacy fields remain available to existing test probes.
    return std::format(R"({{"protocol":{},"test_only":{},"seat_lifetime":"compositor","upgrade":"desktop_restart","transport_ready":{},"epoch":"{}","lease_active":{},"seat_resources":{},"pointer_resources":{},"keyboard_resources":{},"dispatches":{},"lanes":[{}]}})",
        kProduction ? 3 : 0, !kProduction, !lanes_[0]->suspended && !lanes_[1]->suspended, lanes_[0]->epoch, lanes_[0]->lease != nullptr || lanes_[1]->lease != nullptr,
        lanes_[0]->seats.size() + lanes_[1]->seats.size(), lanes_[0]->pointers.size() + lanes_[1]->pointers.size(),
        lanes_[0]->keyboards.size() + lanes_[1]->keyboards.size(), lanes_[0]->dispatches + lanes_[1]->dispatches, states);
}
} // namespace cua::hyprland