fix(agent): hand off capture across receiver routes

[justinechang39]

Summary

Fix HID++ button capture becoming stuck when one physical mouse moves between
receiver routes.

A retiring capture session now restores firmware state through the newly active
route before allowing its successor to arm. Pending restoration retries also
follow the latest route for the same physical device.

Changes

• openlogi-device

  • Add typed shutdown and route-handoff capture commands.
  • Restore diverted controls through the successor receiver route.
  • Retain the latest route across delayed restoration retries.
  • Support rapid route changes back to the original receiver without leaving capture blocked.

• openlogi-agent-core

  • Propagate route handoff intent through capture-session teardown.
  • Retry pending restoration through the latest capture plan for the same physical device.
  • Preserve the existing one-firmware-owner invariant until restoration completes.

No configuration or IPC wire-format changes.

Testing

macOS affected-package gate:

• DEVELOPER_DIR=/Library/Developer/CommandLineTools RUSTFLAGS="-D warnings" cargo fmt --all -- --check
• DEVELOPER_DIR=/Library/Developer/CommandLineTools RUSTFLAGS="-D warnings" cargo clippy -p openlogi-device -p openlogi-hid -p openlogi-agent-core -p openlogi-agent -p openlogi-cli -p openlogi --all-targets -- -D warnings
• DEVELOPER_DIR=/Library/Developer/CommandLineTools RUSTFLAGS="-D warnings" cargo test -p openlogi-device -p openlogi-hid -p openlogi-agent-core -p openlogi-agent -p openlogi-cli -p openlogi

Clean Linux full-workspace gate:

• PATH="$HOME/.cargo/bin:$PATH" RUSTFLAGS="-D warnings" cargo fmt --all -- --check
• PATH="$HOME/.cargo/bin:$PATH" RUSTFLAGS="-D warnings" cargo clippy --workspace --all-targets -- -D warnings
• PATH="$HOME/.cargo/bin:$PATH" RUSTFLAGS="-D warnings" cargo test --workspace --exclude openlogi-desktop
• PATH="$HOME/.cargo/bin:$PATH" RUSTFLAGS="-D warnings" RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --document-private-items --exclude openlogi-ui --exclude openlogi-desktop --exclude openlogi-overlay --exclude openlogi-agent
• PATH="$HOME/.cargo/bin:$PATH" RUSTFLAGS="-D warnings" cargo check -p openlogi-hidpp -p openlogi-device --target wasm32-unknown-unknown
• PATH="$HOME/.cargo/bin:$PATH" RUSTFLAGS="-D warnings" cargo check -p openlogi-core --no-default-features --target wasm32-unknown-unknown

The original failure was reproduced on an MX Master 4 with two Bolt receivers.
The patched app was not runtime-tested on hardware because no compatible full
Xcode/Metal toolchain is available for the test Mac's macOS 27 beta. Windows
checks were not run locally; CI covers that platform.

Fixes #1196

[greptile-apps]

Greptile Summary

The PR coordinates HID++ capture teardown across receiver-route changes so firmware restoration follows the physical device’s latest route before a successor session arms.

• Adds typed shutdown and route-handoff commands to capture sessions.
• Retargets immediate and delayed firmware restoration through the latest capture plan.
• Preserves firmware ownership and blocks successor capture until restoration completes.
• Adds coverage for route handoff, delayed successor publication, and rapid movement back to the original receiver.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
crates/openlogi-agent-core/src/watchers/capture_session.rs	Generalizes capture-session stop signaling so teardown can carry route-handoff intent while preserving existing lifecycle semantics.
crates/openlogi-agent-core/src/watchers/gesture.rs	Sends handoff commands for receiver-route changes and retargets pending restoration retries through the latest per-device plan.
crates/openlogi-device/src/session/capture_restore.rs	Adds route-aware restoration and retains the elected route across retries while checking registry currency after writes.
crates/openlogi-device/src/session/gesture.rs	Accepts typed capture stop reasons and propagates handoff routes into firmware teardown.
crates/openlogi-agent-core/src/watchers/gesture/tests.rs	Updates lifecycle tests for typed stop commands and verifies route changes request firmware handoff.
crates/openlogi-device/src/session/gesture/tests.rs	Covers restoration through a successor route, delayed route publication, and rapid return to the original route.

Sequence Diagram

sequenceDiagram
    participant Plans as Capture plans
    participant Manager as Gesture manager
    participant Old as Retiring session
    participant Registry as Channel registry
    participant New as Successor route

    Plans->>Manager: Publish same physical device on new route
    Manager->>Old: CaptureSessionStop::Handoff(new route)
    Old->>Registry: Look up new route
    Registry-->>Old: Current shared channel
    Old->>New: Restore native firmware reporting
    Old-->>Manager: Done / pending restoration token
    alt restoration completed
        Manager->>New: Arm successor capture session
    else restoration remains pending
        Manager->>Registry: Retry via latest capture-plan route
        Registry-->>Manager: Latest current channel
        Manager->>New: Restore, then arm successor
    end

Loading

_{Reviews (2): Last reviewed commit: "fix(agent): hand off capture across rece..." | Re-trigger Greptile}