vmctl: read-only held-state receipt for keys and pointer buttons

Add vmctl_key_held, vmctl_btn_held, vmctl_keys_snapshot and
vmctl_btns_snapshot, exposing the down-state each handle last actuated.
Two bitmaps in the handle (keys by evdev KEY_*, buttons by VMCTL_BTN_*)
are updated after a successful send in vmctl_batch_send; the send path
never reads them. VMCTL_KEY_CODE_MAX and VMCTL_KEYS_SNAPSHOT_BYTES give
callers the keys-snapshot buffer size.

include/vmctl.h

@@ -53,6 +53,9 @@ void     vmctl_close(vmctl_t* v);                /* safe on NULL     */
 #define VMCTL_BTN_BACK    6
 #define VMCTL_BTN_TASK    7
 
+#define VMCTL_KEY_CODE_MAX        0x2ff   /* highest supported evdev key code (inclusive) */
+#define VMCTL_KEYS_SNAPSHOT_BYTES ((VMCTL_KEY_CODE_MAX + 1) / 8)  /* bytes for vmctl_keys_snapshot */
+
 /* ===== Event batch (value-type, stack; build ONLY via builders — ev[] is not API) ===== */
 #define VMCTL_BATCH_MAX  64
 typedef struct {
@@ -78,6 +81,19 @@ int vmctl_btn   (vmctl_t* v, int btn,  int down);        /* VMCTL_BTN_* */
 int vmctl_key   (vmctl_t* v, int evdev_code, int down);  /* Linux KEY_* */
 int vmctl_scroll(vmctl_t* v, int axis, double value);    /* VMCTL_SCROLL_* */
 
+/* ===== Held-state receipt (read-only) =====
+ * "held" = key/button state as THIS handle last actuated it, not guest truth.
+ * It is the actuator's record of its own last output (sensing the guest belongs
+ * to the sensors layer, not here). Updated only after a successful send; the
+ * send path NEVER reads this map (no dedup, no auto-release, no autorepeat). */
+
+int      vmctl_key_held     (vmctl_t* v, int evdev_code);   /* Linux KEY_*; 1=down 0=up */
+int      vmctl_btn_held     (vmctl_t* v, int btn);          /* VMCTL_BTN_*; 1=down 0=up */
+int      vmctl_keys_snapshot(vmctl_t* v, unsigned char* bits, size_t nbytes);
+                                          /* copy key down-bits (EVIOCGKEY-style);
+                                             returns bytes written, -1 on bad args */
+unsigned vmctl_btns_snapshot(vmctl_t* v); /* VMCTL_BTN_* down-bits as a mask (bits 0..7) */
+
 /* ===== Power/lifecycle actuation (requires a QMP connection; -1 if there is none) ===== */
 int vmctl_powerdown(vmctl_t* v);   /* system_powerdown (ACPI soft-off) */
 int vmctl_reset    (vmctl_t* v);   /* system_reset                     */