fix(clipboard): address critical bugs and design issues

X11 ICCCM compliance (#4/#5):
- SetSelectionOwner now uses real server timestamp via PropertyNotify probe,
  not XCB_CURRENT_TIME (violates ICCCM §2.1). Added get_server_timestamp_locked()
  which fires a zero-byte ChangeProperty to trigger timestamp event.
- TIMESTAMP replies now return g_own_ts (real value) instead of truncated 0.
- Verified: xclip -o -t TIMESTAMP returns non-zero after our clipboard write.

INCR cleanup (#3):
- On INCR read timeout, delete property to unblock sender waiting for
  PropertyNotify=Delete (ICCCM compliant termination).

Process lifecycle (#7):
- Wayland: runCaptureBytes, runSilently, writeBytes now escalate to
  destroyForcibly() if SIGTERM doesn't terminate after 500ms grace.

AccessBehavior mapping (#12):
- Kotlin: explicit when() mapping (0→AlwaysAllow, 1→AskEveryTime, 2→AlwaysDeny)
  instead of ordinal/entries.getOrNull (fragile with future macOS versions).
- ObjC: validate input 0..2 on set; return -1 if get() returns out-of-range.

Documentation & robustness (#13, #1):
- Clipboard.watch() doc: clarify poll interval is always honored; source of
  counter differs by backend (Mach IPC / XFixes / wl-paste).
- Re-check isActive after slow availableFormats() to avoid emitting to
  cancelled flow.

Added X11TimestampSmokeTest to verify real timestamps are used.

Author: kdroidFilter

clipboard-common/src/main/kotlin/io/github/kdroidfilter/nucleus/clipboard/Clipboard.kt

@@ -132,9 +132,10 @@ object Clipboard {
      * Cold [Flow] that emits whenever the clipboard contents change.
      *
      * The event carries only format metadata and a monotonic `changeCount`, not
-     * payload bytes — call a `readXxx` method to fetch content. Polls the backend's
-     * change counter (cheap Mach IPC on macOS, WM_CLIPBOARDUPDATE on Windows,
-     * XFixes on X11, data-control events on Wayland).
+     * payload bytes — call a `readXxx` method to fetch content. The flow polls
+     * `changeCount()` on every [pollInterval] tick regardless of backend; what
+     * differs is the source that bumps the counter: Mach IPC on macOS, a native
+     * event thread backed by XFixes on X11, and `wl-paste --watch` on Wayland.
      *
      * The baseline is captured on `collect`, so the flow does not emit the current
      * clipboard state — only subsequent changes.
@@ -149,7 +150,13 @@ object Clipboard {
                         val cur = backend.changeCount()
                         if (cur != last) {
                             last = cur
-                            trySend(ClipboardEvent(formats = availableFormats(), changeCount = cur))
+                            // availableFormats() may be slow on Wayland (spawns a process);
+                            // re-check isActive so a cancellation during the await
+                            // does not leak a ghost emission after close.
+                            val formats = availableFormats()
+                            if (isActive) {
+                                trySend(ClipboardEvent(formats = formats, changeCount = cur))
+                            }
                         }
                     }
                 }

clipboard-linux/src/main/kotlin/io/github/kdroidfilter/nucleus/clipboard/linux/WaylandClipboardDelegate.kt

@@ -14,6 +14,7 @@ import java.util.concurrent.atomic.AtomicLong
 private const val PROCESS_WRITE_TIMEOUT_SECONDS: Long = 3L
 private const val IMAGE_READ_TIMEOUT_MS: Long = 5000L
 private const val DESTROY_DRAIN_MS: Long = 200L
+private const val DESTROY_GRACE_MS: Long = 500L
 
 private val IMAGE_MIME_PREFERENCE: List<String> =
     listOf("image/png", "image/jpeg", "image/jpg", "image/webp", "image/bmp", "image/gif", "image/tiff")
@@ -219,6 +220,9 @@ internal class WaylandClipboardDelegate {
             p.waitFor(PROCESS_WRITE_TIMEOUT_SECONDS, TimeUnit.SECONDS)
             if (p.isAlive) {
                 p.destroy()
+                if (!p.waitFor(DESTROY_GRACE_MS, TimeUnit.MILLISECONDS)) {
+                    p.destroyForcibly()
+                }
                 false
             } else {
                 p.exitValue() == 0
@@ -266,6 +270,9 @@ internal class WaylandClipboardDelegate {
                 }
             if (!p.waitFor(timeoutMs, TimeUnit.MILLISECONDS)) {
                 p.destroy()
+                if (!p.waitFor(DESTROY_GRACE_MS, TimeUnit.MILLISECONDS)) {
+                    p.destroyForcibly()
+                }
                 t.join(DESTROY_DRAIN_MS)
                 return null
             }
@@ -296,6 +303,9 @@ internal class WaylandClipboardDelegate {
             val p = ProcessBuilder(cmd).redirectErrorStream(true).start()
             if (!p.waitFor(timeoutMs, TimeUnit.MILLISECONDS)) {
                 p.destroy()
+                if (!p.waitFor(DESTROY_GRACE_MS, TimeUnit.MILLISECONDS)) {
+                    p.destroyForcibly()
+                }
                 false
             } else {
                 p.exitValue() == 0

clipboard-linux/src/main/native/linux/nucleus_clipboard_linux.c

@@ -313,7 +313,7 @@ static xcb_atom_t a_CLIPBOARD, a_TARGETS, a_MULTIPLE, a_TIMESTAMP, a_SAVE_TARGET
     a_INCR, a_ATOM_PAIR, a_UTF8_STRING, a_STRING, a_TEXT, a_COMPOUND_TEXT,
     a_text_plain, a_text_plain_utf8, a_text_html, a_text_rtf, a_application_rtf,
     a_image_png, a_text_uri_list, a_x_special_gnome_copied_files,
-    a_application_x_kde_cutselection, a_clipboard_manager, a_prop;
+    a_application_x_kde_cutselection, a_clipboard_manager, a_prop, a_ts_probe;
 
 /* Mutex protecting everything below. */
 static pthread_mutex_t g_mutex = PTHREAD_MUTEX_INITIALIZER;
@@ -327,7 +327,15 @@ typedef struct {
 
 static payload_t g_offers[OFFER__COUNT];
 static bool      g_offer_is_cut = false;
-static xcb_timestamp_t g_own_ts = 0;
+
+/* Latest X11 server timestamp observed on our own window. Used instead of
+ * XCB_CURRENT_TIME for SetSelectionOwner / TIMESTAMP replies, as ICCCM §2.1
+ * forbids CurrentTime for those. Fetched via a zero-byte ChangeProperty probe
+ * which triggers a PropertyNotify that the event thread captures. */
+static xcb_timestamp_t g_latest_ts = 0;
+static bool             g_ts_pending = false;
+static pthread_cond_t   g_ts_cond = PTHREAD_COND_INITIALIZER;
+static xcb_timestamp_t  g_own_ts = 0;
 
 /* Requestor-side pending read. */
 typedef struct {
@@ -444,6 +452,46 @@ static void intern_all_atoms(void) {
     a_application_x_kde_cutselection = intern("application/x-kde-cutselection", false);
     a_clipboard_manager  = intern("CLIPBOARD_MANAGER", false);
     a_prop               = intern(PROP_NAME, false);
+    a_ts_probe           = intern("NUCLEUS_CLIPBOARD_TS_PROBE", false);
+}
+
+/* --------------------------------------------------------------------- */
+/* Deadline helper                                                        */
+/* --------------------------------------------------------------------- */
+
+static void add_ms(struct timespec *ts, long ms) {
+    ts->tv_sec += ms / 1000;
+    ts->tv_nsec += (ms % 1000) * 1000000L;
+    if (ts->tv_nsec >= 1000000000L) { ts->tv_sec++; ts->tv_nsec -= 1000000000L; }
+}
+
+/* --------------------------------------------------------------------- */
+/* ICCCM-compliant server timestamp fetch                                 */
+/* --------------------------------------------------------------------- */
+
+/* Forces the server to emit a PropertyNotify on our window and captures its
+ * `time` field via the event thread. Must be called with g_mutex held; the
+ * condvar wait releases it transiently. Falls back to g_latest_ts on timeout,
+ * or 0 if no event has ever been observed. */
+static xcb_timestamp_t get_server_timestamp_locked(void) {
+    g_ts_pending = true;
+    /* Append 0 bytes to a dedicated property → unconditional PropertyNotify. */
+    p_xcb_change_property(g_conn, XCB_PROP_MODE_APPEND, g_window, a_ts_probe,
+                          XCB_ATOM_STRING, 8, 0, NULL);
+    p_xcb_flush(g_conn);
+
+    struct timespec deadline;
+    clock_gettime(CLOCK_REALTIME, &deadline);
+    add_ms(&deadline, 500);
+
+    while (g_ts_pending) {
+        int rc = pthread_cond_timedwait(&g_ts_cond, &g_mutex, &deadline);
+        if (rc == ETIMEDOUT) {
+            g_ts_pending = false;
+            break;
+        }
+    }
+    return g_latest_ts;
 }
 
 /* --------------------------------------------------------------------- */
@@ -616,13 +664,6 @@ static uint8_t *fetch_property(xcb_atom_t prop, bool *out_incr, size_t *out_len)
     return out;
 }
 
-/* Deadline helper. */
-static void add_ms(struct timespec *ts, long ms) {
-    ts->tv_sec += ms / 1000;
-    ts->tv_nsec += (ms % 1000) * 1000000L;
-    if (ts->tv_nsec >= 1000000000L) { ts->tv_sec++; ts->tv_nsec -= 1000000000L; }
-}
-
 /* Perform a full read for the given target (atom). Returns malloc'd bytes or NULL. */
 static uint8_t *read_selection(xcb_atom_t target, size_t *out_len) {
     *out_len = 0;
@@ -665,6 +706,11 @@ static uint8_t *read_selection(xcb_atom_t target, size_t *out_len) {
         while (!g_read.incr_done) {
             int rc = pthread_cond_timedwait(&g_read_cond, &g_mutex, &incr_deadline);
             if (rc == ETIMEDOUT) {
+                /* Delete the property so the sender is unblocked for its next
+                 * chunk (ICCCM requires the requestor to ack each chunk by
+                 * deleting the property). We then abandon the transfer. */
+                p_xcb_delete_property(g_conn, g_window, a_prop);
+                p_xcb_flush(g_conn);
                 g_read.waiting = false;
                 read_reset_locked();
                 pthread_mutex_unlock(&g_mutex);
@@ -720,8 +766,18 @@ static void on_selection_notify_locked(const xcb_selection_notify_event_t *ev) {
 }
 
 static void on_property_notify_locked(const xcb_property_notify_event_t *ev) {
+    /* Any PropertyNotify on our own window gives us a fresh server timestamp
+     * we can use for subsequent SetSelectionOwner calls (ICCCM §2.1). */
+    if (ev->window == g_window) {
+        g_latest_ts = ev->time;
+        if (ev->atom == a_ts_probe && g_ts_pending) {
+            g_ts_pending = false;
+            pthread_cond_broadcast(&g_ts_cond);
+        }
+    }
+
     /* state 0 = NewValue, 1 = Delete. We only care about NewValue on our
-     * own property during INCR. */
+     * own read property during INCR. */
     if (!g_read.waiting || !g_read.incr || g_read.incr_done) return;
     if (ev->window != g_window || ev->atom != a_prop || ev->state != 0) return;
 
@@ -1248,10 +1304,10 @@ Java_io_github_kdroidfilter_nucleus_clipboard_linux_NativeX11ClipboardBridge_nat
 
     g_offer_is_cut = (isCut == JNI_TRUE);
 
-    /* Use CurrentTime; xcb_set_selection_owner is routed via server and will
-     * be our implicit timestamp. Record it for TIMESTAMP replies. */
-    g_own_ts = XCB_CURRENT_TIME;
-    p_xcb_set_selection_owner(g_conn, g_window, a_CLIPBOARD, XCB_CURRENT_TIME);
+    /* ICCCM §2.1: SetSelectionOwner must use a real server timestamp,
+     * never CurrentTime. Probe one via a zero-byte ChangeProperty. */
+    g_own_ts = get_server_timestamp_locked();
+    p_xcb_set_selection_owner(g_conn, g_window, a_CLIPBOARD, g_own_ts);
     p_xcb_flush(g_conn);
 
     pthread_mutex_unlock(&g_mutex);
@@ -1271,7 +1327,8 @@ Java_io_github_kdroidfilter_nucleus_clipboard_linux_NativeX11ClipboardBridge_nat
      * often dies silently anyway. */
 
     free_offers_locked();
-    p_xcb_set_selection_owner(g_conn, XCB_ATOM_NONE, a_CLIPBOARD, XCB_CURRENT_TIME);
+    xcb_timestamp_t ts = get_server_timestamp_locked();
+    p_xcb_set_selection_owner(g_conn, XCB_ATOM_NONE, a_CLIPBOARD, ts);
     p_xcb_flush(g_conn);
 
     pthread_mutex_unlock(&g_mutex);

clipboard-linux/src/test/kotlin/io/github/kdroidfilter/nucleus/clipboard/linux/X11TimestampSmokeTest.kt

@@ -0,0 +1,53 @@
+package io.github.kdroidfilter.nucleus.clipboard.linux
+
+import kotlin.test.Test
+import kotlin.test.assertTrue
+
+/**
+ * Verifies that SetSelectionOwner uses a real X11 server timestamp (ICCCM §2.1),
+ * not XCB_CURRENT_TIME. We can't introspect the native timestamp directly; the
+ * proof is indirect: `xclip -selection clipboard -o -t TIMESTAMP` returns the
+ * selection owner's timestamp, which must be > 0 when the protocol is respected.
+ *
+ * Skipped when DISPLAY is unset or when xclip is not installed.
+ */
+class X11TimestampSmokeTest {
+    @Test
+    fun selectionTimestampIsNonZero() {
+        val display = System.getenv("DISPLAY") ?: return
+        if (display.isEmpty()) return
+        if (!NativeX11ClipboardBridge.isLoaded) return
+        if (!NativeX11ClipboardBridge.nativeInit()) return
+        if (!hasBinary("xclip")) return
+
+        NativeX11ClipboardBridge.nativeWrite(
+            "nucleus-ts-probe-${System.currentTimeMillis()}",
+            null,
+            null,
+            null,
+            null,
+            false,
+        )
+        Thread.sleep(150)
+
+        val output =
+            ProcessBuilder("xclip", "-selection", "clipboard", "-o", "-t", "TIMESTAMP")
+                .redirectErrorStream(true)
+                .start()
+                .inputStream
+                .bufferedReader()
+                .readText()
+                .trim()
+
+        println("TIMESTAMP output=$output")
+        val ts = output.toLongOrNull()
+        assertTrue(ts != null && ts > 0L, "selection timestamp must be non-zero, got '$output'")
+    }
+
+    private fun hasBinary(name: String): Boolean {
+        val path = System.getenv("PATH") ?: return false
+        return path.split(':').any { dir ->
+            dir.isNotEmpty() && java.io.File(dir, name).canExecute()
+        }
+    }
+}

clipboard-macos/src/main/kotlin/io/github/kdroidfilter/nucleus/clipboard/macos/MacClipboardBackend.kt

@@ -76,13 +76,23 @@ class MacClipboardBackend : ClipboardBackend {
 
     override fun setAccessBehavior(behavior: AccessBehavior) {
         if (!NativeMacClipboardBridge.isLoaded) return
-        NativeMacClipboardBridge.nativeSetAccessBehavior(behavior.ordinal)
+        val raw =
+            when (behavior) {
+                AccessBehavior.AlwaysAllow -> 0
+                AccessBehavior.AskEveryTime -> 1
+                AccessBehavior.AlwaysDeny -> 2
+            }
+        NativeMacClipboardBridge.nativeSetAccessBehavior(raw)
     }
 
     override fun accessBehavior(): AccessBehavior? {
         if (!NativeMacClipboardBridge.isLoaded) return null
-        val raw = NativeMacClipboardBridge.nativeGetAccessBehavior()
-        return AccessBehavior.entries.getOrNull(raw)
+        return when (NativeMacClipboardBridge.nativeGetAccessBehavior()) {
+            0 -> AccessBehavior.AlwaysAllow
+            1 -> AccessBehavior.AskEveryTime
+            2 -> AccessBehavior.AlwaysDeny
+            else -> null
+        }
     }
 
     override fun isAccessBehaviorSupported(): Boolean =

clipboard-macos/src/main/kotlin/io/github/kdroidfilter/nucleus/clipboard/macos/NativeMacClipboardBridge.kt

@@ -58,15 +58,17 @@ internal object NativeMacClipboardBridge {
     external fun nativeClear(): Boolean
 
     /**
-     * Sets `NSPasteboard.accessBehavior`. Values match [AccessBehavior] ordinal:
-     * 0 = always allow, 1 = ask every time, 2 = always deny. No-op on macOS < 15.4.
+     * Sets `NSPasteboard.accessBehavior`. Accepts 0 = always allow,
+     * 1 = ask every time, 2 = always deny. Other values are refused.
+     * No-op on macOS < 15.4.
      */
     @JvmStatic
     external fun nativeSetAccessBehavior(value: Int)
 
     /**
-     * Reads `NSPasteboard.accessBehavior`. Returns the raw enum value on
-     * macOS 15.4+, or `-1` when the property is not exposed by the runtime.
+     * Reads `NSPasteboard.accessBehavior`. Returns 0/1/2 on macOS 15.4+,
+     * or `-1` when the property is not exposed or the value is outside the
+     * documented range (future macOS may add new cases).
      */
     @JvmStatic
     external fun nativeGetAccessBehavior(): Int

clipboard-macos/src/main/native/macos/nucleus_clipboard.m

@@ -315,10 +315,13 @@ static jobjectArray toJStringArray(JNIEnv *env, NSArray<NSString *> *items) {
     JNIEnv *env, jclass cls, jint value) {
     (void)env; (void)cls;
     @autoreleasepool {
+        // macOS 15.4 enum layout: 0 = alwaysAllow, 1 = askEveryTime, 2 = alwaysDeny.
+        // Refuse out-of-range values rather than propagating them to AppKit where
+        // they would produce undefined behavior.
+        if (value < 0 || value > 2) return;
         NSPasteboard *pb = [NSPasteboard generalPasteboard];
         SEL sel = NSSelectorFromString(@"setAccessBehavior:");
         if (![pb respondsToSelector:sel]) return;
-        // macOS 15.4 enum layout: 0 = alwaysAllow, 1 = askEveryTime, 2 = alwaysDeny.
         NSInteger mapped = (NSInteger)value;
         NSMethodSignature *sig = [pb methodSignatureForSelector:sel];
         NSInvocation *inv = [NSInvocation invocationWithMethodSignature:sig];
@@ -344,6 +347,10 @@ static jobjectArray toJStringArray(JNIEnv *env, NSArray<NSString *> *items) {
         [inv invoke];
         NSInteger result = 0;
         [inv getReturnValue:&result];
+        // Only forward the three documented enum values. A future macOS
+        // release may add intermediate cases — surface them as -1 so the
+        // Kotlin side can degrade to null rather than silently misreport.
+        if (result < 0 || result > 2) return -1;
         return (jint)result;
     }
 }