A plugin file change while the session is locked strands the lock screen or aborts omarchy-shell
Checked every mechanical claim on this workstation (omarchy 4.0.2-1, quickshell 0.3.1-1, Hyprland 0.56.2) and every source claim against the threads read in full today. Confirmed here: unloadPluginServices() at /usr/share/omarchy/shell/shell.qml lines 348 to 354 destroys every service with no keepLoaded test, keepLoaded is read only around the panel Loader at line 625, /usr/share/omarchy/shell/plugins/lock/manifest.json sets keepLoaded: true, and /usr/share/omarchy/bin/omarchy-restart-shell lines 29 to 37 run jq -r '.secure or .requested' and print Refusing to restart Omarchy shell while the session is locked. at line 33, then set relock=1 and re-lock through relock_session() when neither is true, so claim 1 holds exactly as written. Confirmed here for claim 2: hl.clear_crashed_lockscreen is a function in the live hl table (hyprctl repl 'return type(hl.clear_crashed_lockscreen)' answers function), so is hl.dsp.exec_cmd, hyprctl --instance 0 and hyprctl eval both exist, hyprlock is not installed, and /usr/share/hypr/lockdead.png is the failsafe wall and prints the record's command verbatim plus the killall -9 hyprlock line that does nothing on Omarchy 4. Hyprland v0.56.2 source shows hlClearCrashedLockscreen refusing with session is locked with a client, refusing to unlock when clientLocked() || clientDenied() and otherwise calling forceUnlock(), which is the refuse-then-unlock behaviour the record claims. /usr/share/omarchy/bin/omarchy-launch-shell is the supervisor: it waits on quickshell, logs Omarchy shell exited with status $status; relaunching. at line 89, and gives up at line 85 with Giving up on the Omarchy shell after 6 relaunches in under a minute., so the SIGKILL route and both quoted journal lines are right. From sources: the fix claim is current. PR 9485 merged to quattro on 2026-09-02 as d3d23fdd, and shell.qml at tag v4.0.3 has serviceKeepLoaded() and an unloadPluginServices() that keeps those services, so the grep -n serviceKeepLoaded test is valid. omarchy 4.0.3-1 is in the [omarchy] stable repo today (fetched pkgs.omarchy.org/stable/x86_64/omarchy.db), so omarchy update really does deliver it. The still-open list also holds: v4.0.3's _syncServices still destroys unconditionally and never consults keepLoaded, and PR 7169 is still open. Issues 7106, 9441 and 6888 support the symptom, the status JSON, the refusal text, the delayed abort, the __pycache__ trigger and the pkill -9 recovery (cyppe on 7106 records status 137, then secure=true six seconds later, and the hl.clear_crashed_lockscreen() note the record's last-resort block is built from). Two things were wrong. First, no reporter in 7106, 9441 or 6888 has an Intel plus NVIDIA machine. What is attested is NVIDIA-only desktops, Intel i915 laptops, AMD amdgpu, one AMD plus NVIDIA dual-GPU machine and Apple Silicon. Second, The compositor lock holds throughout, so nothing on screen is exposed is contradicted by parnoldx on 6888, whose stalled machine had omarchy-hyprland-session-locked exiting 1, no LOCK in solitaryBlockedBy and no lock layer while the shell still reported secure:true. That is a security claim, so it is now qualified rather than stated flat. The danger field was rewritten to say what hl.clear_crashed_lockscreen() actually does (forceUnlock()), to name the re-lock step, and to record that killing quickshell is not free once the supervisor's five-relaunch budget is gone. Not exercised: nothing on the recovery path was run. This session cannot lock the screen, kill quickshell or call hl.clear_crashed_lockscreen() without stranding itself, so the kill-and-relaunch sequence and the failsafe clear rest on the scripts, the Hyprland source and the reporters, not on a local run.
The last resort unlocks the machine. hl.clear_crashed_lockscreen() calls Hyprland's forceUnlock(), so the desktop is live and unattended from the moment it returns until something locks it again, and the usual way into this recovery is a TTY or an ssh session from somewhere else. Only run it when you are physically at the machine, and lock again with omarchy-shell lock lock as soon as the shell is back. Killing quickshell is safer, because the compositor keeps holding the lock while the supervisor restarts the shell. It is not free either: omarchy-launch-shell allows five relaunches in sixty seconds, then logs Giving up on the Omarchy shell after 6 relaunches in under a minute. and stops, which leaves the failsafe up with no shell at all.
Symptom
The session is locked, by idle timeout or omarchy system lock. A file under ~/.config/omarchy/plugins/<plugin>/ then changes: chezmoi apply or Syncthing from another machine, a git pull in a plugin checkout, a background agent writing files, an editor still saving after you walked away, or a test suite dropping __pycache__/ into the plugin directory. journalctl --user -t omarchy-shell shows:
Local plugin changed, reloading: <plugin id>
omarchy lock ... lock-stranded: recovering
omarchy lock ... lock-requested
omarchy lock ... lock-pending: screen-stabilizing
It then goes one of two ways. Either it never progresses, and Hyprland's "lockscreen app died" failsafe stays on screen with no password prompt, or omarchy-shell aborts:
FATAL: Tried to show lockscreen surfaces without active lock
That is a SIGABRT from quickshell -n -p /usr/share/omarchy/shell, one core in coredumpctl, after which a replacement shell starts within a second or two and usually re-locks properly so your password works. The abort can be delayed by hours and land on a later screen wake with no plugin write near it.
In the stranded case, omarchy-shell lock status reports {"locked":true,"requested":true,"pending":true,"sessionLocked":false,"secure":true,...} and omarchy-restart-shell answers Refusing to restart Omarchy shell while the session is locked.
The compositor usually keeps holding the lock, so the failsafe wall stays up and the desktop is not exposed. Do not rely on that. One reporter on issue 6888 saw the opposite after a stall: omarchy-hyprland-session-locked exited 1, solitaryBlockedBy carried no LOCK, and the only layers left were omarchy-bar and omarchy-background, with the shell still reporting secure:true. Check a wedged machine with omarchy-hyprland-session-locked before you walk away from it.
Reported on 4.0.0-1, 4.0.1-1 and 4.0.2-1, with quickshell-git 0.3.0 and quickshell 0.3.1-1 on Qt 6.11.1 and 6.11.2, on NVIDIA desktops, Intel i915 laptops, AMD amdgpu machines, one AMD plus NVIDIA dual-GPU machine and Apple Silicon (Asahi). One reporter hit it with no lock involved at all, from a plugin rewritten every 10 to 40 seconds.
Cause
Established in the threads by collaborator triage against quattro and the quickshell sources, and by core dumps from three reporters.
A plugin change triggers reloadPlugins(), which calls unloadPluginServices() in shell/shell.qml. Before the fix that function destroyed every plugin service unconditionally, including omarchy.lock, which owns the live WlSessionLock. The lock manifest's keepLoaded: true was honoured for panel Loaders only. Confirmed on an omarchy 4.0.2-1 install: /usr/share/omarchy/shell/shell.qml lines 348 to 354 destroy every service, and keepLoaded is consulted only around the panel Loader at line 625.
Destroying the lock client leaves the compositor's ext-session-lock standing with no locker, which is what Hyprland's failsafe is showing. It also leaves quickshell's process-global QSWaylandSessionLockManager::active pointer dangling, because only unlock() clears it, so no lock attempt in that process can succeed again. The rebuilt lock service then reads sessionLock.secure through that dangling pointer. If it reads true the service returns early forever, which is the silent lock-pending stall. If it reads false it sets locked = true, and in quickshell 0.3.1 WlSessionLock::realizeLockTarget calls qFatal when manager->lock() fails, which is the abort. Reading a field of a freed object is why the abort can arrive hours later, once that memory is reused.
omarchy-restart-shell refuses in the stranded case because it asks the same wedged service: lines 28 to 36 on 4.0.2-1 test .secure or .requested and bail out when either is true. The same teardown is reachable without any file write, through omarchy plugin disable omarchy.lock or omarchy plugin remove while locked, which also go through _syncServices().
Fix
**The fix shipped in 4.0.3.** PR #9485, "Honor keepLoaded for services during plugin hot-reload", merged to quattro on 2026-09-02 as commit d3d23fdd, makes unloadPluginServices() keep any service whose manifest sets keepLoaded: true, which omarchy.lock does. The v4.0.3 tag, published 2026-09-08, contains it, and 4.0.2-1 and earlier do not:
omarchy update
grep -n serviceKeepLoaded /usr/share/omarchy/shell/shell.qml # present once the fix has arrived
Still open after that merge: omarchy plugin disable or remove while locked, and recovery of a process that has already taken the damage, which is PR #7169.
**Prevention on 4.0.2 and earlier.** Do not write under ~/.config/omarchy/plugins/ while the screen is locked. Edit a plugin in a scratch directory and copy it in when you are at the keyboard, and gate sync and dotfile tools on omarchy-hyprland-session-locked, which exits 0 while the compositor holds a session lock. One reporter runs this as a chezmoi pre-apply hook:
if omarchy-hyprland-session-locked; then
echo "session is locked, not touching plugins" >&2
exit 1
fi
**If the abort already happened** and a replacement shell is up, type your password. Nothing else is needed.
**If the session is stranded** with no password prompt, work from a TTY (Ctrl+Alt+F2) or over ssh as the session user, inside a login shell (bash -lc, otherwise OMARCHY_PATH is unset and every omarchy command fails). Kill the wedged shell. SIGKILL cannot be caught by quickshell's crash handler, so the supervisor omarchy-launch-shell logs Omarchy shell exited with status 137; relaunching. and the fresh process re-secures the lock on its own within a few seconds, after which the password prompt works. One reporter confirmed this on 4.0.2-1, and it matches the source analysis that only a new process clears the dangling pointer:
pkill -9 -x quickshell
sleep 6
omarchy-shell lock status # expect "sessionLocked":true,"secure":true
omarchy-restart-shell is the shorter route only once no locker is reporting: it refuses while the wedged service still says .secure or .requested, and re-locks a fresh shell when neither is true.
If the supervisor has given up (Giving up on the Omarchy shell after 6 relaunches in under a minute. in the journal) or you killed omarchy-launch-shell too, no client holds the lock any more. Clear Hyprland's failsafe and start the shell again. The session comes back **unlocked**:
hyprctl --instance 0 eval 'hl.clear_crashed_lockscreen()'
hyprctl --instance 0 dispatch 'hl.dsp.exec_cmd("omarchy-launch-shell")'
hl.clear_crashed_lockscreen() exists in Hyprland 0.56.2 and refuses while a client still holds the lock, which is why the kill comes first. The failsafe text's killall -9 hyprlock does nothing on Omarchy 4, which does not install hyprlock.
Verify
grep -n serviceKeepLoaded /usr/share/omarchy/shell/shell.qml # the fix is installed
journalctl --user -t omarchy-shell -n 30 --no-pager # lock-requested, then secure=true
omarchy-shell lock status | jq '.sessionLocked, .secure' # true, true
coredumpctl list quickshell # no new entry after a plugin write
Then type the password at the lock screen. One reporter's journal after the kill: lock-stranded: recovering at 12:45:59, secure=true at 12:46:05, password accepted. The upstream test plan for #9485 checks that after omarchy-shell shell rescanPlugins the lock service's lastEventAt is unchanged and its status is not lock-stranded.
Sources
- https://github.com/omacom/omarchy/issues/7106
- https://github.com/omacom/omarchy/issues/9441
- https://github.com/omacom/omarchy/issues/6888
- https://github.com/omacom/omarchy/pull/9485
- https://github.com/omacom/omarchy/pull/7169
- https://github.com/omacom/omarchy/blob/d3d23fdddef846ebb98b52122a6ece66211c0daf/shell/shell.qml
- https://github.com/omacom/omarchy/releases/tag/v4.0.3
- https://github.com/omacom/omarchy/blob/v4.0.3/shell/shell.qml
- https://github.com/hyprwm/Hyprland/blob/v0.56.2/src/config/lua/bindings/LuaBindingsToplevel.cpp
- https://github.com/hyprwm/Hyprland/blob/v0.56.2/src/render/Renderer.cpp