feat: reload.sh restarts quickshell components

The volume OSD drew only its "Output 72%" label, with the icon, bar and
device line clipped below the panel edge. The code and the theme were
not at fault: a hot reload fixed it, and a debug line logged just after
showed the volume row laid out correctly at the top of the panel. The
stuck state lived in the running process, so the fix is a restart.

quickshell has no reload subcommand and no IPC target for it, and a
hot reload needs a real content change to a file. reload.sh kills and
restarts each named component, or every directory holding a shell.qml,
and prints the qs count afterwards, since the process is qs and not
quickshell.

It must run from the user's terminal. A detached qs started from an
agent's tool call dies with the call, which would leave the desktop
without its shells; AGENTS.md now says so under Reloading.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2 files changed, 44 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 138148f..83c1b2d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -308,6 +308,14 @@ the whole screen use `ExclusionMode.Ignore`.
 | a component's QML | quickshell hot-reloads on save; no restart |
 | palette | regenerate with `udt-accent <wallpaper>`; watched, no restart |
 | Hyprland binds, layer rules, autostart | `hyprctl reload` |
+| a running shell in a bad state | `./reload.sh [component...]`, from the user's terminal |
+
+`reload.sh` restarts components rather than hot-reloading them. The volume OSD
+once drew only its label, with the icon, bar and device line clipped off, and
+a hot reload fixed it while the code and the layout both measured correct, so
+the stuck state lived in the running process. Do not run the script from an
+agent's tool call: the detached `qs` it starts dies with the call (see
+Verifying above), which leaves the user's desktop without its shells.
 
 Hot reload covers adding and removing windows too: the keepalive window above
 was added to a running shell and took effect on save.
diff --git a/reload.sh b/reload.sh
new file mode 100755
index 0000000..243a132
--- /dev/null
+++ b/reload.sh
@@ -0,0 +1,36 @@
+#!/bin/bash
+# Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 2 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+
+# Restart quickshell components. With no argument, every directory holding a
+# shell.qml; otherwise the named ones: ./reload.sh desktop notifications
+#
+# A restart rather than a hot reload: saving a file only rebuilds what
+# quickshell thinks changed, and a stuck window survives that.
+
+cd "$(dirname "$0")" || exit 1
+
+if [ $# -eq 0 ]; then
+    set -- */shell.qml
+    set -- "${@%/shell.qml}"
+fi
+
+for c in "$@"; do
+    c=${c%/}
+    [ -f "$c/shell.qml" ] || { echo "$c: no shell.qml" >&2; continue; }
+    qs kill -p "$PWD/$c" >/dev/null 2>&1
+    setsid -f qs -p "$PWD/$c" >/dev/null 2>&1
+    echo "restarted $c"
+done
+
+sleep 1
+# The process is qs, not quickshell: see AGENTS.md.
+echo "qs running: $(pgrep -cx qs)"