### System details

#   Lenovo Yoga C640 laptop, single internal display, Arch,  #   omarchy-dev 4.0.0.r1744.gf002044-1, quickshell-git 0.3.0.r20.g28771c7-1,  #   hyprland 0.56.2-1

### What's wrong?

**Summary.** If the shell reloads its QML while the session is locked, the lock surface
is destroyed and the session is left on Hyprland's *"lockscreen app died"* wall. The
shell **notices this and starts its own recovery** — `lock-stranded: recovering` — but
the recovery then stalls permanently, so the user still needs a TTY. The recovery path
is one early-return away from working.

**Deterministic reproducer** (no display flakiness or idle timing needed):

1. Lock the session (`omarchy system lock`).
2. From another machine over SSH, or a TTY, write any file into a plugin folder the
   shell has loaded — e.g. `touch ~/.config/omarchy/plugins/<your-plugin>/Foo.qml`.
   Anything that triggers `Local plugin changed, reloading:` will do.
3. Return to the machine: *"Oopsie daisy, it looks like you locked your screen but the
   lockscreen app died"*, and it never resolves.

Hit on 2026-08-14 by a routine `install.sh` that copies plugin folders — the session
happened to be locked at the time.

**What the log shows.** `quickshell` never dies here; only the lock does:

```
14:59:16 omarchy-shell[143971]: DEBUG qml: Local plugin changed, reloading: yoda.emojis
14:59:16 omarchy-shell[143971]: DEBUG qml: omarchy lock … lock-stranded: recovering
14:59:16 omarchy-shell[143971]: DEBUG qml: omarchy lock … lock-requested
14:59:16 omarchy-shell[143971]: DEBUG qml: omarchy lock … lock-pending: screen-stabilizing
   (nothing further — the session stayed this way until a TTY login 34 s later)
```

**Where it stalls** — `shell/plugins/lock/Service.qml`:

`recoverStrandedLock()` (L94) correctly calls `beginLock()` (L128), which sets
`lockRequested = true`, logs `lock-requested`, and calls `queueSessionLock()` (L56).
`pendingSessionLockTimer` (L441, `interval: 100`, `repeat: true`) then retries
`requestSessionLock()` (L63) ten times a second — forever, silently:

```qml
function requestSessionLock() {
  if (!lockRequested || sessionLock.locked || sessionLock.secure) return   // L64
  if (sessionLockStabilizeTimer.running) return                           // L65

  if (!hasRealScreen()) {
    … logEvent("lock-pending: no-real-screen")                            // L68
    return
  }
  …
  sessionLock.locked = true                                               // L76
}
```

The log proves it returns at **L64**, not later: the last event is
`lock-pending: screen-stabilizing`, and `lock-pending: no-real-screen` is never emitted
even though L68's condition would have logged it (`lastEvent` differs). So execution
never reaches L67 — it exits on `sessionLock.locked || sessionLock.secure`.

That is the trap: **a stranded lock means the compositor's `ext-session-lock` is still
held**, so `sessionLock.secure` is already `true`. The shell therefore concludes a lock
is in place and declines to create one — while no client is drawing anything. The
retry timer spins at 10 Hz achieving nothing, and because `logEvent()` (L110) only
records state *changes*, the spin leaves no trace.

`locked` (L37) is defined as `lockRequested || sessionLock.locked || sessionLock.secure`,
so the same `secure` flag also makes `recoverStrandedLock()`'s own guard (L95,
`if (… || locked || …) return`) treat the orphan as a healthy lock on any later attempt.

**Suggested fix.** Recovery has to *release* the orphaned lock before requesting a new
one — the internal equivalent of `hl.clear_crashed_lockscreen()` — rather than treating
`secure` as proof that a working lock exists. Distinguishing "the compositor is secured
**by a surface this shell owns**" from "the compositor is secured by a dead client"
would make the existing `lock-stranded: recovering` path complete on its own. A bounded
retry that gives up loudly (instead of an unbounded silent 10 Hz spin) would also have
made this obvious from the log.

**Aggravating detail.** Hyprland's on-screen recovery text advises `killall -9 hyprlock`,
but **hyprlock is not installed on Quattro** — the lock is the `omarchy.lock` Quickshell
plugin, so following that advice literally leads nowhere. The actual recovery is
`hyprctl eval 'hl.clear_crashed_lockscreen()'` from a TTY or another machine.

**Related but distinct:** the shell *exiting* on a screen with no valid Wayland output
(reported separately). Here the shell survives the whole time — only the lock is lost —
so any watchdog that keys on "is quickshell running" will not notice this one.

**Workaround in use here.** A 30-second user timer that, when the shell is alive,
calls `hl.clear_crashed_lockscreen()` and immediately re-locks if it returns `ok`
(it returns `ok` only when the lock client is genuinely gone, and refuses while a
healthy lock exists, so polling it is safe). Plus a guard in our own installer that
refuses to write plugin files while the session is locked.