Reading the Wires

The special workspace never actually shows

Symptom: clicking the notification correctly opened Satty (confirmed — its window really did exist), but no overlay ever appeared on screen. Nothing visibly happened at all.

• confirmed hyprctl dispatch togglespecialworkspace screenshot — the classic syntax from Module 6 — was silently failing every single time. Tapped Hyprland's own event socket (see the snippet added to Module 8) across a full click cycle and the activespecial event, which fires whenever a special workspace is shown or hidden, never appeared anywhere in the capture — not once. Ran the exact dispatch command directly in a terminal next, and it surfaced the real error immediately: [string "return hl.dispatch(togglespecialworkspace scr..."]:1: ')' expected near 'screenshot'.

This particular Hyprland build — the one whose entire config is written in Lua via hl.* — doesn't accept classic dispatcher strings through hyprctl dispatch at all. It evaluates whatever text you pass as a Lua expression, effectively running hl.dispatch(<your text>). The correct form was sitting in the framework's own shipped example config (/usr/share/hypr/hyprland.lua), which calls dispatchers like hyprctl dispatch 'hl.dsp.exit()' — full Lua function calls, not bare dispatcher names.

A stray terminal, and lost focus

Symptom: once Bug 9 was fixed, two more things showed up: (a) sometimes a brand-new terminal window appeared inside the special workspace, entirely on its own, minutes after Satty had already closed; and (b) after closing Satty, no window had keyboard focus at all — the correct workspace was visible, but nothing responded to typing.

• ruled out A bug in open-satty.sh itself causing the stray terminal. Tapped the event socket across a full cycle again: the stray terminal's openwindow event landed several seconds after Satty's own closewindow/destroyworkspace events, and a concurrent pgrep polling loop (see Module 8) confirmed zero screenshot-related processes were even running at that moment. Whatever caused it, it wasn't our script running code.
• confirmed Hyprland's own internal bookkeeping for "which workspace do brand-new windows land on" wasn't fully reverting after the special workspace was hidden, and separately, closing a window that had focus inside a special workspace drops focus to nothing rather than falling back to whatever's on the workspace underneath. Reproduced the second part directly and in isolation: launched Satty manually, watched hyprctl activewindow before/during/after, and confirmed it goes completely null once Satty closes — even after explicitly switching back to the correct regular workspace.

The clipboard "doesn't paste" — mostly a false alarm

Symptom: picking an entry from the SUPER+SHIFT+V rofi picker appeared in the list fine, but pasting failed in both Google Docs and Thunar.

• ruled out A broken cliphist decode / wl-copy hand-off. Rather than guessing, dumped the clipboard's actual bytes right after a real rofi selection (wl-paste --type image/png to a file, checked with file) — came back as a correct, byte-identical 1920×1080 PNG every time. Re-tested Google Docs directly afterward and it pasted fine.

Thunar simply doesn't support "create a file from clipboard image data" at all — pasting a file into a folder needs a text/uri-list clipboard entry (a reference to an existing file), which a raw image copy never provides. Not a bug in this workflow; a missing feature in Thunar.

Making a rofi pick paste itself

Ask: could picking an entry in rofi paste it immediately, instead of just loading the clipboard and leaving you to press Ctrl+V yourself?

Wayland clipboard tools only ever touch the clipboard — none of them can simulate a keystroke. That needs a separate tool. Chose wtype over the more common ydotool: it's built specifically for wlroots compositors like Hyprland, needs no background daemon and no special group permissions, unlike ydotool which needs both.

Print silently fires twice

Symptom: found while re-testing Bug 10's fix — things felt subtly unreliable, "worked once, then got weird."

• confirmed A single physical Print press was reproducibly spawning two concurrent screenshot.sh processes. Caught directly with the pgrep polling loop from Module 8 — both PIDs persisted for the entire run, each independently capturing, copying, and sending its own notification.
• ruled out A bug in hl.dsp.exec_cmd or in the script itself causing a self-relaunch. Manually dispatched the exact same command directly (bypassing the physical key entirely) a dozen times — it only ever ran once. Whatever's duplicating the event, it's specific to how this particular key press arrives, possibly a firmware/driver quirk on this Print key — never conclusively identified, and not worth chasing further once it could be made harmless regardless of cause.

The lock fix breaks Print forever

Symptom: after Bug 13's fix, Print eventually stopped doing anything at all — every single press, no file, no notification, nothing.

• confirmed fuser -v on the lock file (see Module 8) showed it held open by a wl-copy process that had been running for over nine minutes, reparented to PID 1 (its original parent, an earlier screenshot.sh, was long gone). /proc/locks confirmed an active advisory lock still tied to that same file.

wl-copy deliberately never exits on its own — it stays alive indefinitely to keep serving paste requests (see Module 2) — and it had inherited a duplicate of the script's own lock file descriptor, simply by being launched from a shell that had one open (ordinary fork/exec fd inheritance, nothing exotic). Per Linux flock semantics, a lock tied to an open file description stays held as long as any process still holds a copy of that descriptor open, even after the process that originally created the lock has exited. A long-lived child can pin a lock forever.

Releasing the lock "early" reopens the race

Symptom: an earlier version of Bug 13's fix released the lock right after sending the notification, reasoning that only the capture/copy/notify steps needed protecting — the long click-wait and Satty session shouldn't block a later, legitimate Print press. Re-testing showed Print could still sometimes produce two overlapping notifications.

• confirmed Measured the actual gap between the two spurious screenshot.sh starts from Bug 13, using the same pgrep polling technique, and found it wasn't always sub-millisecond — sometimes 100+ ms apart. That's longer than it takes the first instance to reach the early-release point, so the second invocation could arrive after the first had already unlocked, acquire its own fresh lock, and run a complete parallel cycle anyway.

The multi-second click delay

Symptom: the longest chase of the session. Anywhere from ~1 to ~6 seconds between clicking the notification and Satty's window actually appearing — inconsistent, and initially looked unfixable.

• ruled out The daemon only fires ActionInvoked on dismiss, not on click (this was your hypothesis). Tested with an isolated raw notification and a live dbus-monitor tap, clicking immediately — the signal arrived in well under a second. The daemon fires it right away; this wasn't it.
• ruled out dbus-monitor's own stdout is block-buffered once piped elsewhere (a classic Unix gotcha — many programs switch from line-buffered to fully-buffered output once stdout isn't a terminal). Tested stdbuf -oL dbus-monitor ..., which forces line-buffering via an LD_PRELOAD shim — no change at all. The delay stayed at ~93-95% of whatever timeout value was configured, regardless of exactly when the click happened. dbus-monitor apparently doesn't use the kind of glibc stdio stdbuf can intercept.
• ruled out Switch to busctl monitor (systemd's bus-monitoring tool — a completely different implementation from dbus-monitor), in case the issue was specific to one binary. Identical near-timeout delay.
• ruled out dbus-monitor only flushes once a second message follows closely behind the first (a click usually fires both ActionInvoked and NotificationClosed almost simultaneously). Widened the match filter to catch both signals instead of just ActionInvoked — same delay again.
• confirmed gawk itself was buffering its own reads from the incoming pipe, independent of anything dbus-monitor was doing. Timed the exact same parsing logic two ways side by side: through gawk, and reimplemented in plain bash (a while read -r line; do ... done < <(dbus-monitor ...) loop, using parameter expansion instead of awk's split/match). The gawk version consistently only produced a result at ~93-95% of whatever timeout was set; the plain-bash version consistently detected the exact same click in ~1-1.5 seconds, matching ordinary human reaction time.

The toolkit behind this log

Module 8 (Reading it back yourself) already covers the Hyprland event-socket tap and the pgrep polling loop, which caught Bugs 10 and 13-15. Bug 16 needed one more instrument: a disposable, throwaway notification used purely as a stopwatch, since it lets you measure exactly how long detection takes without ever touching the real screenshot workflow.

The click-latency test rig. Start a listener in the background, print the exact moment you send a real (but harmless) notification, then print the exact moment the listener detects the click. The gap between those two timestamps is the number that mattered — not "does it work," but "how long does it take":

# start listening FIRST, in the background
(
  action=$(timeout 10 dbus-monitor --session \
      "type='signal',interface='org.freedesktop.Notifications',member='ActionInvoked'" 2>/dev/null | \
      gawk -v target="ID_FROM_BELOW" '
          /member=ActionInvoked/ {
              getline; split($0, a, " "); id = a[2]
              getline; match($0, /"([^"]*)"/, m); act = m[1]
              if (id == target) { print act; exit }
          }
      ')
  echo "got action='$action' at: $(date +%s.%N)"
) &

# then fire a real, disposable test notification and note when
echo "notify sent at: $(date +%s.%N)"
busctl --user call org.freedesktop.Notifications /org/freedesktop/Notifications \
    org.freedesktop.Notifications Notify susssasa{sv}i \
    "TimingTest" 0 "" "Click me now" "" \
    2 "default" "Click" 0 10000    # <- note the returned id, use it as target above

wait   # click the notification now

This rig is what falsified three hypotheses in a row cheaply: swap only the target id (a fresh one each run, since it increments per call), rerun, click promptly, and read off the delta. It's also what made the real cause obvious once tried: rerunning the exact same rig with only the consumer swapped — the gawk block above versus a plain while read -r line; do ... done < <(dbus-monitor ...) loop — produced two starkly different deltas (~93-95% of the timeout vs. ~1-1.5 seconds) from otherwise identical input. When two consumers of the identical data stream disagree that badly on timing, the consumer is the suspect, not the data source.

Combining two observers around one real action. Some bugs only make sense relative to timing across two different systems — "did Hyprland report this window opening before or after that process existed?" Running two independent capture loops in the background at once, against the same real button-press, then merging their timestamps afterward, is what pinned down both Bug 10 and Bug 13:

# observer 1 — Hyprland's own event stream, timestamped
python3 -c "
import socket, time
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.connect('\$XDG_RUNTIME_DIR/hypr/\$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock')
with open('events.log', 'w') as f:
    while True:
        data = s.recv(4096)
        if not data: break
        t = time.time()
        for line in data.decode(errors='replace').splitlines():
            f.write(f'{t:.3f} {line}\n')
        f.flush()
" &

# observer 2 — process snapshots, timestamped, every 100ms
(
  end=$((SECONDS+30))
  while [ $SECONDS -lt $end ]; do
    ts=$(date +%s.%N)
    procs=$(pgrep -af 'satty|open-satty|screenshot.sh')
    [ -n "$procs" ] && printf '%s %s\n' "$ts" "$procs" >> procs.log
    sleep 0.1
  done
) &

wait   # do the real thing now: press Print, click, close Satty

Both logs end up on the same wall-clock timeline, so afterward you can line up "this window opened" against "this process existed" to within 100ms. That's exactly how Bug 10's stray terminal was proven to land in the special workspace at a moment when zero screenshot-related processes were even running, and how Bug 13's double invocation was proven to be two complete, independent processes rather than one process forking.

Reproducing a bug without a human in the loop. Once Bug 10's focus-loss symptom was described, the fastest way to confirm the mechanism wasn't to keep asking for real Print-and-click cycles — it was to reproduce the exact sequence directly from a terminal:

satty -f test.png -o test_out.png --early-exit all &
satty_pid=$!
for _ in $(seq 1 50); do
  hyprctl clients -j | jq -e --arg pid "$satty_pid" \
    '.[] | select(.pid == ($pid | tonumber))' >/dev/null 2>&1 && break
  sleep 0.05
done
hyprctl dispatch 'hl.dsp.workspace.toggle_special("screenshot")'
sleep 0.5
hyprctl activewindow -j | jq -c '{address,class}'   # check focus WHILE shown

kill "$satty_pid"; wait "$satty_pid" 2>/dev/null
hyprctl dispatch 'hl.dsp.workspace.toggle_special("screenshot")'
hyprctl activewindow -j | jq -c '{address,class}'   # check focus AFTER hiding

This reproduced activewindow going completely null in isolation, in a few seconds, with a disposable test image — no physical keypress needed, no risk to a real screenshot, and repeatable as many times as it took to confirm the fix.

Testing the primitive before blaming your own script. Twice this session, the fastest path to a root cause was to stop reading screenshot.sh/open-satty.sh entirely and test the underlying command by hand, outside any script:

# is our own exec_cmd wrapper double-firing, or is it something else? (Bug 13)
hyprctl dispatch 'hl.dsp.exec_cmd("date +%s%N >> /tmp/exec_count.log")'
wc -l /tmp/exec_count.log            # exactly 1 -> rules out exec_cmd itself

# does the classic dispatcher syntax even work on this system at all? (Bug 9)
hyprctl dispatch togglespecialworkspace screenshot
# -> immediate Lua parse error, printed straight to the terminal

Both answers came back in under a second, and each one ruled out an entire category of explanation before a single line of either script needed to change.

SUPER+Print occasionally creates a workspace with no click, and focus is lost

Symptom: reported once, not yet reproduced on demand despite repeated attempts. Pressing SUPER+Print, a workspace gets created even without ever clicking the resulting notification, and afterward no window can gain keyboard focus at all — the only recovery is closing the current window and switching to a different workspace.

• open Most likely related to the same still-unexplained mechanism behind Bug 13 (Print reproducibly double-firing at the key-event level, root cause never identified) — but broader here, since Bug 13 only ever duplicated a whole script run, never corrupted focus or created a workspace without the click-gated path in open-satty.sh ever running. A stuck modifier key (SUPER not being released) or a duplicate/malformed scancode at the input-driver level would explain both an unexpected SUPER+<something> binding firing and a subsequent focus/input malfunction in one shot — but this is a hypothesis, not yet confirmed.

An always-on logger for bugs that won't reproduce

Bug 17 above doesn't reproduce on demand, which makes every technique earlier in this log (which all assume you can trigger the bug while something's watching) useless on its own. ~/.config/hypr/scripts/debug-logger.sh is the answer to that: a standalone script, independent of any Claude Code session, meant to be started in its own terminal and left running during ordinary use.

It runs two of the same taps used throughout this log — Hyprland's own timestamped event stream (the exact technique from Bugs 9-10 and the toolkit above), and a live kernel-log follow (journalctl -k -f), in case the root cause turns out to be at the input-driver level rather than in Hyprland at all — writing both continuously to ~/.cache/hypr-debug/ with simple size-based rotation so it's safe to leave running for hours or days. When Bug 17 happens again: no need to stop it, just note roughly when, and hand over the relevant window of both log files.

Click launches a program directly, with nothing of ours listening at all

The question: right now, screenshot.sh spawns a small process that watches for a click for a bounded window, then gives up. Could a notification click instead directly invoke Thunar/Satty, with literally no process of ours running to catch it?

What "invoke" actually does. Read wayle's own source (it's open source — confirmed real via pacman -Qi wayle-bin, then found on GitHub). Every path that handles a click — the notification body, and each action button, in both the transient popup and the persisted dropdown item — ends up calling the same function:

// wayle-notification/src/core/controls.rs
pub(super) async fn invoke(
    connection: &Connection,
    id: &u32,
    action_key: &str,
) -> Result<(), Error> {
    connection
        .emit_signal(
            None::<()>,
            SERVICE_PATH,
            SERVICE_INTERFACE,
            Signal::ActionInvoked.as_str(),
            &(id, action_key),
        )
        .await?;
    Ok(())
}

That's the entire behavior: re-broadcast the exact (id, action_key) pair as the standard org.freedesktop.Notifications.ActionInvoked signal — the same signal screenshot.sh has been catching this whole time. Wayle never interprets what "default" or "show-folder" mean; it doesn't know or care. That interpretation only happens on whichever side is listening.

Why this rules out zero-listener, structurally. The freedesktop Notifications spec is a fire-and-forget broadcast model by design — the daemon's contract is "show this, and shout if it's clicked," nothing more. Checked for a config-level escape hatch (some notification tools let you bind a shell command directly to an action) and there isn't one here: docs/config/modules/notifications.md has no such option, and busctl --user introspect org.freedesktop.Notifications /org/freedesktop/Notifications confirms wayle exposes only the four standard spec methods (Notify, CloseNotification, GetCapabilities, GetServerInformation) — nothing custom. Every app with clickable notifications (Slack, Discord, Firefox) handles this the same way: they can react because they're already running continuously anyway, so it doesn't read as "a listener," it's just one more thing their existing process does. A one-shot script like ours doesn't have that luxury for free.

So the real choice is between two designs, not three: