fix(vdisplay/capture): channel-less sessions composite the pointer on a sticky-declared target

A declared IddCx hardware cursor is IRREVOCABLE for its OS target's life
(§8.6), and the sticky exclusion survives monitor REMOVE→ADD because each
client gets a STABLE target id — so once any desktop-mode session declared,
every later pure-capture session on that target streamed a cursor-less
desktop: DWM excluded the pointer, no channel forwarded it, no blend drew it
(the exact no-regression gap §8.6's per-session cap gate cannot see).

Driver: track every successful SetupHardwareCursor per target
(DECLARED_TARGETS — scoped to the WUDFHost's life, exactly the sticky
state's scope) and report it in a new AddReply::cursor_excluded tail field
(dual-size discipline, both skews degrade cleanly; no proto bump).

Host: the flag rides AddedMonitor → Monitor → WinCaptureTarget; a session
WITHOUT the cursor channel on a flagged target forces composite mode in the
IDD-push capturer — GDI poller + blend for the session's life, pinned on
(set_cursor_forward cannot clear it: with no client drawing, un-compositing
would erase the pointer entirely).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

crates/pf-capture/src/linux/xfixes_cursor.rs

@@ -331,13 +331,13 @@ fn update_shape(shape: &mut Shape, img: &GetCursorImageReply) {
 }
 
 /// One request+reply — x11rb splits errors (the request is `ConnectionError`, `reply()` is
-/// `ReplyError` which is `From<ConnectionError>`), so `?` collapses both.
+/// `ReplyError` which is `From<ConnectionError>`), so the request `?` converts into the reply error.
 fn fetch_cursor_image(conn: &RustConnection) -> Result<GetCursorImageReply, ReplyError> {
-    Ok(conn.xfixes_get_cursor_image()?.reply()?)
+    conn.xfixes_get_cursor_image()?.reply()
 }
 
 fn fetch_pointer(conn: &RustConnection, root: Window) -> Result<QueryPointerReply, ReplyError> {
-    Ok(conn.query_pointer(root)?.reply()?)
+    conn.query_pointer(root)?.reply()
 }
 
 /// XFixes cursor pixels are packed `0xAARRGGBB` with **premultiplied** alpha (the Xrender / Xcursor

crates/pf-capture/src/windows/idd_push.rs

@@ -399,8 +399,9 @@ pub struct IddPushCapturer {
     /// from [`cursor_poll::CursorPoller`] (the IddCx query is alpha-only — see cursor_poll.rs),
     /// and this shm read is the fallback if that poller dies.
     cursor_shared: Option<cursor::CursorShared>,
-    /// The GDI cursor-shape poller (design §8): the overlay source while alive. `Some` exactly
-    /// when `cursor_shared` is (both ride the negotiated cursor channel + successful delivery).
+    /// The GDI cursor-shape poller (design §8): the overlay source while alive. `Some` when
+    /// `cursor_shared` is (both ride the negotiated cursor channel + successful delivery) — or
+    /// when `composite_forced` (no channel, but the target's sticky declare needs a blend source).
     cursor_poll: Option<cursor_poll::CursorPoller>,
     /// Retained delivery sender (`IOCTL_SET_CURSOR_CHANNEL`) for RE-delivery: a driver-side
     /// monitor re-arrival (match-window re-arrival resize, a sibling session recreating the
@@ -410,6 +411,12 @@ pub struct IddPushCapturer {
     /// The CAPTURE mouse model is active — the HOST composites the pointer into the frame
     /// (see cursor_blend.rs for why DWM cannot: a declared IddCx hardware cursor is forever).
     composite_cursor: bool,
+    /// This session never negotiated the cursor channel but its target carries an IRREVOCABLE
+    /// hardware-cursor declare from an earlier session (`WinCaptureTarget::cursor_excluded`,
+    /// §8.6): DWM delivers pointer-free frames and no client draws the cursor, so the ONLY path
+    /// to a visible pointer is compositing here. Pins `composite_cursor` on — nothing may turn
+    /// it off (there is no channel to hand the pointer to).
+    composite_forced: bool,
     /// The cursor-quad blend pass (lazy; per capture device). `None` after a build failure —
     /// composite mode then degrades to pointer-less frames (warned once).
     cursor_blend: Option<cursor_blend::CursorBlendPass>,
@@ -1016,10 +1023,23 @@ impl IddPushCapturer {
                     }
                 }
             });
+            // No channel this session, but the target's sticky declare (an EARLIER session's —
+            // irrevocable, §8.6) keeps DWM's frames pointer-free with no client drawing either:
+            // the only visible pointer is the one composited here, so force composite mode on.
+            let composite_forced = target.cursor_excluded && cursor_sender.is_none();
+            if composite_forced {
+                tracing::info!(
+                    target_id = target.target_id,
+                    "target carries an irrevocable hardware-cursor declare from an earlier \
+                     desktop-mode session and this session has no cursor channel — the host \
+                     composites the pointer into frames (forced, for the session's life)"
+                );
+            }
             // The GDI shape poller rides the SAME gate as the delivered channel: with the driver's
             // hardware cursor keeping the frame cursor-free, the poller supplies the full-fidelity
             // shape (masked/monochrome included — the IddCx query can't; see cursor_poll.rs).
-            let cursor_poll = cursor_shared.as_ref().map(|_| {
+            // Forced-composite sessions need it too — it is their only shape/position source.
+            let cursor_poll = (cursor_shared.is_some() || composite_forced).then(|| {
                 // Safety of the CCD call: read-only QueryDisplayConfig over owned locals (same
                 // call CursorShared::create makes) — already inside open_on's unsafe region.
                 let rect = pf_win_display::win_display::source_desktop_rect(target.target_id)
@@ -1088,7 +1108,8 @@ impl IddPushCapturer {
                 cursor_shared,
                 cursor_poll,
                 cursor_sender,
-                composite_cursor: false,
+                composite_cursor: composite_forced,
+                composite_forced,
                 cursor_blend: None,
                 cursor_blend_failed: false,
                 blend_scratch: None,
@@ -2314,7 +2335,9 @@ impl Capturer for IddPushCapturer {
         // stays declared for the session's whole life — the only dependable state (there is NO
         // working un-declare; see cursor_blend.rs) — keeping every frame pointer-free, and the
         // capturer blends the GDI poller's shape into the frame itself. No driver round-trip.
-        let composite = !on && self.cursor_shared.is_some();
+        // `composite_forced` (a channel-less session on a sticky-declared target) is pinned ON:
+        // with no client drawing, un-compositing would erase the pointer entirely.
+        let composite = (!on && self.cursor_shared.is_some()) || self.composite_forced;
         if self.composite_cursor != composite {
             self.composite_cursor = composite;
             self.last_blend_key = None; // regenerate immediately at the current pointer state

crates/pf-driver-proto/src/lib.rs

@@ -79,6 +79,16 @@ pub const fn interface_guid_fields() -> (u32, u16, u16, [u8; 8]) {
 /// LIVE monitor, so the capture mouse model gets DWM's composited pointer back (full fidelity)
 /// and the desktop model gets exclusion + forwarding. Nothing existing changed; against a v5
 /// driver the unknown IOCTL fails and the host logs + keeps the declared-at-ADD behavior.
+/// v6 tail ext (no bump, the `AddRequest` luminance-tail discipline):
+/// [`control::AddReply::cursor_excluded`] — the driver reports whether the ADDed monitor's OS
+/// target already carries a hardware-cursor declare from an earlier session. A declare is
+/// IRREVOCABLE for the target's life (remote-desktop-sweep §8.6, proven on-glass): DWM never
+/// composites the software cursor back into that target's frames, and the sticky state survives
+/// monitor REMOVE→ADD because the host hands every client a STABLE target id. The host uses the
+/// flag to self-composite the pointer (GDI poller + blend) in sessions that never negotiate the
+/// cursor channel — without it those sessions are silently cursor-less. Both skews degrade
+/// cleanly: an old driver writes only the 20-byte reply prefix (host reads `0` = unknown/clean),
+/// an old host retrieves a 20-byte buffer (driver writes just the prefix).
 pub const PROTOCOL_VERSION: u32 = 6;
 
 /// The OLDEST driver protocol this host still drives (v4 is additive over v3 — see the v4 note on
@@ -207,8 +217,21 @@ pub mod control {
         /// `DuplicateHandle`, then [`IOCTL_SET_FRAME_CHANNEL`]). Reported per-ADD, not per-open, so a
         /// WUDFHost restart between sessions can never leave the host duplicating into a dead process.
         pub wudf_pid: u32,
+        /// Non-zero = this monitor's OS target already carries an IRREVOCABLE hardware-cursor
+        /// declare from an earlier session (remote-desktop-sweep §8.6): DWM excludes the pointer
+        /// from every frame on this target, forever, and a session without the cursor channel must
+        /// self-composite (GDI poller + blend) or stream a cursor-less desktop. Appended after
+        /// [`ADD_REPLY_LEGACY_SIZE`] under the same dual-size discipline as the `AddRequest`
+        /// luminance tail: an un-upgraded driver writes only the legacy prefix (the host's
+        /// zero-initialized buffer then reads `0` = unknown/clean), an un-upgraded host retrieves a
+        /// legacy-size buffer (the driver writes just the prefix).
+        pub cursor_excluded: u32,
     }
 
+    /// [`AddReply`]'s size before the `cursor_excluded` tail — the prefix an un-upgraded driver
+    /// writes and an un-upgraded host retrieves (see the field docs).
+    pub const ADD_REPLY_LEGACY_SIZE: usize = 20;
+
     /// `IOCTL_REMOVE` input.
     #[repr(C)]
     #[derive(Clone, Copy, Pod, Zeroable, Debug, PartialEq, Eq)]
@@ -329,12 +352,14 @@ pub mod control {
         assert!(offset_of!(AddRequest, hw_cursor) == 36);
         assert!(size_of::<AddRequest>() == 40);
 
-        assert!(size_of::<AddReply>() == 20);
+        assert!(size_of::<AddReply>() == 24);
         assert!(offset_of!(AddReply, adapter_luid_low) == 0);
         assert!(offset_of!(AddReply, adapter_luid_high) == 4);
         assert!(offset_of!(AddReply, target_id) == 8);
         assert!(offset_of!(AddReply, resolved_monitor_id) == 12);
         assert!(offset_of!(AddReply, wudf_pid) == 16);
+        // The cursor-excluded tail starts exactly at the legacy boundary (prefix-compat).
+        assert!(offset_of!(AddReply, cursor_excluded) == ADD_REPLY_LEGACY_SIZE);
 
         assert!(size_of::<SetFrameChannelRequest>() == 32 + 8 * RING_LEN_USIZE);
         assert!(offset_of!(SetFrameChannelRequest, target_id) == 0);

crates/pf-frame/src/dxgi.rs

@@ -32,6 +32,11 @@ pub struct WinCaptureTarget {
     /// duplicates the sealed frame channel's handles INTO (`idd_push::ChannelBroker`). `0` = unknown
     /// (a pre-v2 pairing can't occur — the version handshake is hard — so this only guards misuse).
     pub wudf_pid: u32,
+    /// The ADD reply flagged this target as carrying an IRREVOCABLE IddCx hardware-cursor declare
+    /// from an earlier session (remote-desktop-sweep §8.6): DWM excludes the pointer from its
+    /// frames forever, so a session WITHOUT the cursor channel must self-composite (the IDD-push
+    /// capturer's forced-composite gate) or the streamed desktop has no cursor at all.
+    pub cursor_excluded: bool,
 }
 
 /// The PyroWave (Windows) zero-copy sharing payload attached to a captured frame: the SECOND plane

crates/pf-vdisplay/src/vdisplay/windows/manager.rs

@@ -74,6 +74,12 @@ struct Monitor {
     /// This monitor was ADDed with the v5 hardware-cursor flag (already driver-proto-gated) —
     /// preserved across a re-arrival resize so the recreated monitor keeps the cursor channel.
     hw_cursor: bool,
+    /// The ADD reply flagged this monitor's OS target as carrying an IRREVOCABLE hardware-cursor
+    /// declare from an earlier session (§8.6): DWM excludes the pointer from its frames forever
+    /// (the sticky state survives monitor REMOVE→ADD via the stable per-client target id), so a
+    /// session WITHOUT the cursor channel must self-composite — carried into
+    /// [`WinCaptureTarget`] for the IDD-push capturer's forced-composite gate.
+    cursor_excluded: bool,
     /// The driver's WUDFHost pid (from the ADD reply) — carried into [`WinCaptureTarget`] so the
     /// IDD-push capturer knows where to duplicate the sealed frame channel's handles. The SAME
     /// process for every parallel monitor (one devnode → one WUDFHost hosts all publishers), which
@@ -101,6 +107,7 @@ impl Monitor {
                 gdi_name: n,
                 target_id: self.target_id,
                 wudf_pid: self.wudf_pid,
+                cursor_excluded: self.cursor_excluded,
             })
     }
 }
@@ -1092,6 +1099,7 @@ impl VirtualDisplayManager {
             position: (0, 0),
             gen: self.gen.fetch_add(1, Ordering::Relaxed),
             hw_cursor,
+            cursor_excluded: added.cursor_excluded,
         })
     }
 
@@ -1315,6 +1323,9 @@ impl VirtualDisplayManager {
             position: old.position,
             gen: old.gen,
             hw_cursor: old.hw_cursor,
+            // Fresh from THIS reply, not `old`: the driver's per-target declare registry is the
+            // ground truth (this session may itself have declared since the original ADD).
+            cursor_excluded: added.cursor_excluded,
         })
     }
 

crates/pf-vdisplay/src/vdisplay/windows/manager/driver.rs

@@ -22,6 +22,11 @@ pub(crate) struct AddedMonitor {
     pub luid: LUID,
     pub wudf_pid: u32,
     pub resolved_monitor_id: u32,
+    /// The driver reports the OS target already carries an IRREVOCABLE hardware-cursor declare
+    /// from an earlier session (`AddReply::cursor_excluded`, remote-desktop-sweep §8.6): DWM
+    /// excludes the pointer from this target's frames forever, so a session without the cursor
+    /// channel must self-composite (GDI poller + blend) or stream a cursor-less desktop.
+    pub cursor_excluded: bool,
 }
 
 /// The backend-specific IOCTL surface — the *only* thing that differs between SudoVDA and pf-vdisplay.

crates/pf-vdisplay/src/vdisplay/windows/pf_vdisplay.rs

@@ -605,10 +605,13 @@ impl VdisplayDriver for PfVdisplayDriver {
         })?;
         // Fail closed on a short reply — `target_id`/`wudf_pid`/`luid` below feed OpenProcess + the
         // WUDFHost verification, so don't decode a partially-written (zeroed) reply as authoritative.
-        if (n as usize) < size_of::<control::AddReply>() {
+        // The LEGACY size, not the full struct: an un-upgraded driver writes only the prefix before
+        // the `cursor_excluded` tail; `out` is zero-initialized, so the missing tail reads `0`
+        // (= unknown/clean — exactly what a driver that can't track declares should report).
+        if (n as usize) < control::ADD_REPLY_LEGACY_SIZE {
             anyhow::bail!(
-                "pf-vdisplay ADD returned {n} bytes, expected {}",
-                size_of::<control::AddReply>()
+                "pf-vdisplay ADD returned {n} bytes, expected at least {}",
+                control::ADD_REPLY_LEGACY_SIZE
             );
         }
         // `pod_read_unaligned` (NOT `from_bytes`): `out` is a stack `[u8; N]` with no guaranteed 4-byte
@@ -623,6 +626,7 @@ impl VdisplayDriver for PfVdisplayDriver {
             target_id = reply.target_id,
             adapter_luid = %format_args!("{:#x}", luid.LowPart),
             wudf_pid = reply.wudf_pid,
+            cursor_excluded = reply.cursor_excluded != 0,
             "pf-vdisplay monitor created {}x{}@{}",
             mode.width,
             mode.height,
@@ -659,6 +663,7 @@ impl VdisplayDriver for PfVdisplayDriver {
             luid,
             wudf_pid: reply.wudf_pid,
             resolved_monitor_id: reply.resolved_monitor_id,
+            cursor_excluded: reply.cursor_excluded != 0,
         })
     }