Skip to content

Keep the shell supervisor attached after a locked Hyprland restart - #13490

Open
MilesRomney wants to merge 2 commits into
omacom:quattrofrom
MilesRomney:launch-shell-live-instance
Open

MilesRomney wants to merge 2 commits into
omacom:quattrofrom
MilesRomney:launch-shell-live-instance

Conversation

@MilesRomney

@MilesRomney MilesRomney commented Sep 28, 2026 •

Copy link
Copy Markdown

Problem

A Hyprland crash while the screen is locked comes back from start-hyprland as --safe-mode --locked. Two things then leave the seat stranded:

  • omarchy-launch-shell keeps the crashed process's HYPRLAND_INSTANCE_SIGNATURE. hyprctl monitors follows that dead socket and fails, so compositor_alive exits the supervisor with no log and Quickshell is never started again. Safe mode does not run hyprland.start, so nothing else starts it.
  • misc:allow_session_lock_restore lives in looknfeel.lua, which safe mode does not load. A later lock request against the stranded session is a fatal Wayland error (invalid object) and Quickshell dies instead of drawing the unlock screen.

Change

omarchy-launch-shell now adopts whichever instance hyprctl instances can still talk to, including that instance's Wayland socket, before each Quickshell launch and before deciding the compositor is gone. The watchdog restart gets a few seconds to answer.

When that instance is already locked, the supervisor enables allow_session_lock_restore before Quickshell connects. The lock plugin's existing stranded-lock recovery can then put the password screen back. The desktop stays covered.

Verification

On a running 0.56.2 / Omarchy 4.0.4 session:

  • hyprctl monitors with a dead HYPRLAND_INSTANCE_SIGNATURE exits 4. hyprctl instances still lists the live compositor.
  • hyprctl eval 'hl.config({ misc = { allow_session_lock_restore = true }})' returns ok.
  • Replacing the script and restarting the supervisor brought Quickshell back under the new process, with the bar up and the session unlocked. Hyprland itself was not restarted.

I have not run ./test/all.

Fixes #12612

start-hyprland relaunches a crashed compositor as --safe-mode --locked.
The supervisor still held the dead instance signature, so hyprctl monitors
failed and it exited without relaunching Quickshell. Safe mode also skips
allow_session_lock_restore, and requesting that stranded lock is fatal to
Quickshell.

Follow hyprctl instances onto the live compositor, and enable lock restore
before starting the shell when a lock is already held.
@llstrk

llstrk commented Sep 29, 2026

Copy link
Copy Markdown

Automated AI review

Community review: Independent automated community review, unaffiliated with the Omarchy team, intended to help prepare PRs for their review.

Outcome: The shell can start on another session's compositor.

Shell can attach to another session's compositor

At every launch, login included, adopt_live_instance takes the first answering entry of hyprctl instances (oldest first), even if the inherited one answers. Impact: with a nested Hyprland or second login, the newer session's shell targets the older compositor and (per Quickshell source, not run) usually exits as a duplicate: no bar.

Suggested change: Keep the inherited signature while it answers, else try instances newest first.

Reproducer (fails at b589086)

Reproducer: a live compositor's shell is moved to another compositor

Save as test/shell.d/launch-shell-live-instance-test.sh and run from the repository root with bash test/shell.d/launch-shell-live-instance-test.sh.

The supervisor is started by a compositor that is alive and answering (mine_1100_2, socket wayland-2). A second, older compositor of the same user (older_1000_1, socket wayland-1) is also alive, as with a nested Hyprland or a second login. hyprctl instances -j lists instances oldest first, which is how hyprctl sorts them.

#!/bin/bash

set -euo pipefail

source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"

test_tmp=$(mktemp -d)
trap 'rm -rf "$test_tmp"' EXIT

fake_bin="$test_tmp/bin"
shell_root="$test_tmp/root"
qs_log="$test_tmp/quickshell.log"
mkdir -p "$fake_bin" "$shell_root/shell"
: >"$qs_log"

# Two compositors of this user share $XDG_RUNTIME_DIR/hypr and both answer: an
# older one, and the one that started this supervisor (a nested Hyprland, or a
# second login). hyprctl lists instances oldest first.
cat >"$fake_bin/hyprctl" <<'SH'
#!/bin/bash

case "$*" in
  "instances -j")
    printf '[\n{\n    "instance": "older_1000_1",\n    "time": 1000,\n    "pid": 1000,\n    "wl_socket": "wayland-1"\n},\n{\n    "instance": "mine_1100_2",\n    "time": 1100,\n    "pid": 1100,\n    "wl_socket": "wayland-2"\n}\n]\n'
    ;;
  "-j monitors")
    [[ $HYPRLAND_INSTANCE_SIGNATURE == "older_1000_1" || $HYPRLAND_INSTANCE_SIGNATURE == "mine_1100_2" ]] || exit 4
    printf '[{"name":"eDP-1","solitaryBlockedBy":["WINDOWED","CANDIDATE"]}]\n'
    ;;
  *)
    exit 1
    ;;
esac
SH

cat >"$fake_bin/quickshell" <<'SH'
#!/bin/bash

printf '%s %s\n' "$HYPRLAND_INSTANCE_SIGNATURE" "$WAYLAND_DISPLAY" >>"$OMARCHY_TEST_QS_LOG"
SH

cat >"$fake_bin/systemd-cat" <<'SH'
#!/bin/bash

while (( $# > 0 )); do
  [[ $1 == "--" ]] && { shift; break; }
  shift
done
exec "$@"
SH

cat >"$fake_bin/logger" <<'SH'
#!/bin/bash
SH

chmod +x "$fake_bin/hyprctl" "$fake_bin/quickshell" "$fake_bin/systemd-cat" "$fake_bin/logger"
ln -s "$ROOT/bin/omarchy-hyprland-session-locked" "$fake_bin/omarchy-hyprland-session-locked"

PATH="$fake_bin:$PATH" \
OMARCHY_PATH="$shell_root" \
OMARCHY_TEST_QS_LOG="$qs_log" \
HYPRLAND_INSTANCE_SIGNATURE=mine_1100_2 \
WAYLAND_DISPLAY=wayland-2 \
  timeout 30 "$ROOT/bin/omarchy-launch-shell" || fail "a clean launch succeeds"

[[ $(<"$qs_log") == "mine_1100_2 wayland-2" ]] ||
  fail "a shell started by a live compositor stays on that compositor" "quickshell started against: $(<"$qs_log")"
pass "a shell started by a live compositor stays on that compositor"

Actual output at the PR head (b589086):

$ bash test/shell.d/launch-shell-live-instance-test.sh
quickshell started against: older_1000_1 wayland-1
not ok - a shell started by a live compositor stays on that compositor
$ echo $?
1

Actual output at the merge base (3faafba):

$ bash test/shell.d/launch-shell-live-instance-test.sh
ok - a shell started by a live compositor stays on that compositor
$ echo $?
0

What happens: run_shell calls adopt_live_instance before every launch, including the first one at login. It ignores the inherited HYPRLAND_INSTANCE_SIGNATURE, even while that compositor answers, and exports the first listed instance that answers, which is the oldest one.

Not reproduced here, from Quickshell v0.3.1 source (launchFromCommand and getDisplayConnection in src/launch/command.cpp): quickshell -n treats an instance with the same config path and WAYLAND_DISPLAY as a duplicate. In a real session the launch would therefore usually exit 0 as a duplicate of the older session's shell, and the supervisor would stop, leaving the newer session without a shell. If the older session had no shell running, a second one would start there.

With the supervisor keeping its inherited signature while hyprctl -j monitors answers, and adopting another instance only after that fails, this test passes at the head (checked), and the watchdog-restart case still works.

Details: suggested launcher change

Checked in the sandbox: with this change and the stub updates below, launch-shell-test.sh, restart-shell-test.sh, this reproducer, the stop test under More findings and the watchdog-restart test all pass. The last hunk is the fix from More findings.

--- a/bin/omarchy-launch-shell
+++ b/bin/omarchy-launch-shell
@@ -45,6 +45,12 @@
 adopt_live_instance() {
   local sig socket
 
+  # Stay with the compositor that started this supervisor while it answers.
+  if [[ -n ${HYPRLAND_INSTANCE_SIGNATURE:-} ]] && hyprctl -j monitors >/dev/null 2>&1; then
+    return 0
+  fi
+
+  # Otherwise follow the watchdog's replacement: the newest instance first.
   while IFS=$'\t' read -r sig socket; do
     [[ -n $sig ]] || continue
     if HYPRLAND_INSTANCE_SIGNATURE=$sig hyprctl -j monitors >/dev/null 2>&1; then
@@ -54,7 +60,7 @@
       fi
       return 0
     fi
-  done < <(hyprctl instances -j 2>/dev/null | jq -r '.[] | "\(.instance)\t\(.wl_socket // "")"')
+  done < <(hyprctl instances -j 2>/dev/null | jq -r 'reverse | .[] | "\(.instance)\t\(.wl_socket // "")"' 2>/dev/null)
 
   return 1
 }
@@ -78,6 +84,7 @@
   local attempt
 
   for (( attempt = 1; attempt <= 10; attempt++ )); do
+    (( terminating )) && return 1
     if adopt_live_instance; then
       return 0
     fi

Existing launcher tests fail

The hyprctl stubs list no instance, so no shell starts: launch-shell-test.sh fails, restart-shell-test.sh times out. Impact: ./test/shell fails; the crash path is untested.

Suggested change: Have both stubs list an instance, start "compositor gone" after the first shell, and add a watchdog test (below).

Reproducer (fails at b589086)

Reproducer: the existing launcher tests fail at the PR head

Run from the repository root at the PR head (b589086), with no changes:

bash test/shell.d/launch-shell-test.sh
bash test/shell.d/restart-shell-test.sh

Actual output at b589086:

$ bash test/shell.d/launch-shell-test.sh
not ok - a shell that exits cleanly is not relaunched
$ echo $?
1

$ bash test/shell.d/restart-shell-test.sh
ok - shell IPC calls time out when Quickshell is unresponsive
ok - shell IPC calls fail while Quickshell is still starting
ok - quiet best-effort IPC calls tolerate a starting shell
ok - shell IPC targets the newest live Quickshell instance
$ echo $?
124

Actual output at the merge base (3faafba), same commands: launch-shell-test.sh prints its 8 ok lines and exits 0; restart-shell-test.sh prints its 9 ok lines and exits 0.

Why: both tests stub hyprctl without an answer for hyprctl instances -j (the launcher test's stub prints [] for every command, the restart test's stub prints nothing for it). run_shell now calls adopt_live_instance before starting Quickshell, finds no instance, and returns 1, so no shell is ever started. In the restart test the stubbed hyprctl dispatch runs the supervisor in the foreground, which then spends about 4.5 s in the widened compositor_alive loop, and the test's timeout 5 omarchy-restart-shell expires (exit 124).

Letting both stubs answer instances -j with one instance, and in launch-shell-test.sh making "compositor gone" take effect after the first shell has started, makes both files pass at the head (checked; the stub change is below).

--- a/test/shell.d/launch-shell-test.sh
+++ b/test/shell.d/launch-shell-test.sh
@@ -55,7 +55,10 @@
 cat >"$fake_bin/hyprctl" <<'SH'
 #!/bin/bash
 
-[[ ${OMARCHY_TEST_COMPOSITOR_GONE:-0} == 1 ]] && exit 4
+# The compositor goes away with the first shell, not before it.
+if [[ ${OMARCHY_TEST_COMPOSITOR_GONE:-0} == 1 && -s $OMARCHY_TEST_QS_LOG ]]; then
+  exit 4
+fi
 
 # Refuse the first OMARCHY_TEST_HYPRCTL_MISSES queries, then answer.
 if (( ${OMARCHY_TEST_HYPRCTL_MISSES:-0} > 0 )); then
@@ -66,7 +69,11 @@
   fi
 fi
 
-printf '[]\n'
+if [[ $* == "instances -j" ]]; then
+  printf '[\n{\n    "instance": "test_1000_1",\n    "time": 1000,\n    "pid": 1000,\n    "wl_socket": "wayland-1"\n}\n]\n'
+else
+  printf '[]\n'
+fi
 SH
 
 cat >"$fake_bin/logger" <<'SH'
--- a/test/shell.d/restart-shell-test.sh
+++ b/test/shell.d/restart-shell-test.sh
@@ -131,7 +131,9 @@
 cat >"$restart_bin/hyprctl" <<'SH'
 #!/bin/bash
 
-if [[ ${1:-} == "-j" && ${2:-} == "monitors" ]]; then
+if [[ ${1:-} == "instances" && ${2:-} == "-j" ]]; then
+  printf '[\n{\n    "instance": "test_1000_1",\n    "time": 1000,\n    "pid": 1000,\n    "wl_socket": "wayland-1"\n}\n]\n'
+elif [[ ${1:-} == "-j" && ${2:-} == "monitors" ]]; then
   # Hyprland reports an active session lock as a reason the monitor cannot hand
   # a client the whole screen, not as a workspace.
   if [[ ${OMARCHY_TEST_SESSION_LOCKED:-0} == 1 ]]; then
Suggested test: watchdog restart (fails at the merge base, passes at b589086)

Suggested test: the supervisor follows a watchdog restart (passes at the head, fails at the merge base)

This covers the behaviour the PR adds and would catch a regression of it. Save as test/shell.d/launch-shell-watchdog-test.sh and run from the repository root with bash test/shell.d/launch-shell-watchdog-test.sh.

#!/bin/bash

set -euo pipefail

source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"

test_tmp=$(mktemp -d)
trap 'rm -rf "$test_tmp"' EXIT

fake_bin="$test_tmp/bin"
shell_root="$test_tmp/root"
qs_log="$test_tmp/quickshell.log"
hyprctl_log="$test_tmp/hyprctl.log"
state="$test_tmp/compositor"
mkdir -p "$fake_bin" "$shell_root/shell"

# $state names the compositor that is up: "crashed" before the first shell
# dies, "replacement" or "replacement-locked" after start-hyprland restarts it.
cat >"$fake_bin/hyprctl" <<'SH'
#!/bin/bash

printf '%s %s\n' "$HYPRLAND_INSTANCE_SIGNATURE" "$*" >>"$OMARCHY_TEST_HYPRCTL_LOG"
state=$(<"$OMARCHY_TEST_STATE")
if [[ $state == "crashed" ]]; then
  live=crashed_1000_1 socket=wayland-1
else
  live=replacement_2000_3 socket=wayland-3
fi

case "$*" in
  "instances -j")
    printf '[\n{\n    "instance": "%s",\n    "time": 1000,\n    "pid": 1000,\n    "wl_socket": "%s"\n}\n]\n' "$live" "$socket"
    ;;
  "-j monitors")
    [[ $HYPRLAND_INSTANCE_SIGNATURE == "$live" ]] || exit 4
    if [[ $state == "replacement-locked" ]]; then
      printf '[{"name":"eDP-1","solitaryBlockedBy":["WINDOWED","LOCK","CANDIDATE"]}]\n'
    else
      printf '[{"name":"eDP-1","solitaryBlockedBy":["WINDOWED","CANDIDATE"]}]\n'
    fi
    ;;
  "eval "*)
    [[ $HYPRLAND_INSTANCE_SIGNATURE == "$live" ]] || exit 4
    printf 'ok\n'
    ;;
  *)
    exit 1
    ;;
esac
SH

# The first shell dies with the compositor, and the watchdog's replacement is
# up by the time the supervisor looks again.
cat >"$fake_bin/quickshell" <<'SH'
#!/bin/bash

printf '%s %s\n' "$HYPRLAND_INSTANCE_SIGNATURE" "$WAYLAND_DISPLAY" >>"$OMARCHY_TEST_QS_LOG"
if [[ $(wc -l <"$OMARCHY_TEST_QS_LOG") == 1 ]]; then
  printf '%s\n' "$OMARCHY_TEST_REPLACEMENT" >"$OMARCHY_TEST_STATE"
  exit 255
fi
SH

cat >"$fake_bin/systemd-cat" <<'SH'
#!/bin/bash

while (( $# > 0 )); do
  [[ $1 == "--" ]] && { shift; break; }
  shift
done
exec "$@"
SH

cat >"$fake_bin/logger" <<'SH'
#!/bin/bash
SH

chmod +x "$fake_bin/hyprctl" "$fake_bin/quickshell" "$fake_bin/systemd-cat" "$fake_bin/logger"
ln -s "$ROOT/bin/omarchy-hyprland-session-locked" "$fake_bin/omarchy-hyprland-session-locked"

launch_shell() {
  : >"$qs_log"
  : >"$hyprctl_log"
  printf 'crashed\n' >"$state"

  PATH="$fake_bin:$PATH" \
  OMARCHY_PATH="$shell_root" \
  OMARCHY_TEST_QS_LOG="$qs_log" \
  OMARCHY_TEST_HYPRCTL_LOG="$hyprctl_log" \
  OMARCHY_TEST_STATE="$state" \
  OMARCHY_TEST_REPLACEMENT="$1" \
  HYPRLAND_INSTANCE_SIGNATURE=crashed_1000_1 \
  WAYLAND_DISPLAY=wayland-1 \
    timeout 30 "$ROOT/bin/omarchy-launch-shell"
}

launch_shell replacement || fail "the supervisor exits cleanly"
[[ $(wc -l <"$qs_log") == 2 ]] || fail "the shell is relaunched after a watchdog restart" "$(<"$qs_log")"
[[ $(sed -n 2p "$qs_log") == "replacement_2000_3 wayland-3" ]] ||
  fail "the relaunched shell connects to the replacement compositor" "$(<"$qs_log")"
pass "the shell follows a watchdog restart to the replacement compositor"

launch_shell replacement-locked || fail "the supervisor exits cleanly"
[[ $(wc -l <"$qs_log") == 2 ]] || fail "the shell is relaunched after a locked watchdog restart" "$(<"$qs_log")"
grep -Fx 'replacement_2000_3 eval hl.config({ misc = { allow_session_lock_restore = true }})' "$hyprctl_log" >/dev/null ||
  fail "lock restore is enabled on the locked replacement" "$(<"$hyprctl_log")"
pass "lock restore is enabled on a replacement that came back locked"

Actual output at the PR head (b589086):

$ bash test/shell.d/launch-shell-watchdog-test.sh
ok - the shell follows a watchdog restart to the replacement compositor
ok - lock restore is enabled on a replacement that came back locked
$ echo $?
0

Actual output at the merge base (3faafba):

$ bash test/shell.d/launch-shell-watchdog-test.sh
crashed_1000_1 wayland-1
not ok - the shell is relaunched after a watchdog restart
$ echo $?
1

It also passes with the suggested launcher change (keep the inherited signature while it answers, newest instance first otherwise, check terminating in the loop).

More findings

Stop request ignored during the widened check. compositor_alive now makes 10 attempts with 0.5 s sleeps and never checks terminating, so a SIGTERM that lands in the loop waits it out: 4.19 s at the head against 0.66 s at the merge base. Suggested change: add (( terminating )) && return 1 at the top of the loop, as #11827 does (0.16 s with the suggested change above).

Reproducer: a stop request during the widened compositor check is ignored for about 4 seconds

Save as test/shell.d/launch-shell-stop-test.sh and run from the repository root with bash test/shell.d/launch-shell-stop-test.sh.

The compositor goes away together with the shell and nothing replaces it (the session is ending). While the supervisor is checking whether a compositor is still there, it receives SIGTERM, as it does when the session unit is stopped.

#!/bin/bash

set -euo pipefail

source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"

test_tmp=$(mktemp -d)
launch_pid=""

cleanup() {
  if [[ -n $launch_pid ]]; then
    kill -KILL "$launch_pid" 2>/dev/null || true
    wait "$launch_pid" 2>/dev/null || true
  fi
  rm -rf "$test_tmp"
}
trap cleanup EXIT

fake_bin="$test_tmp/bin"
shell_root="$test_tmp/root"
qs_log="$test_tmp/quickshell.log"
gone="$test_tmp/compositor-gone"
mkdir -p "$fake_bin" "$shell_root/shell"
: >"$qs_log"

# The session ends: the compositor goes with the shell and nothing replaces it.
# hyprctl then lists no instances, which it prints as a bare "]".
cat >"$fake_bin/hyprctl" <<'SH'
#!/bin/bash

if [[ -f $OMARCHY_TEST_GONE ]]; then
  if [[ $* == "instances -j" ]]; then
    printf '\n]\n'
    exit 0
  fi
  exit 4
fi

case "$*" in
  "instances -j")
    printf '[\n{\n    "instance": "session_1000_1",\n    "time": 1000,\n    "pid": 1000,\n    "wl_socket": "wayland-1"\n}\n]\n'
    ;;
  "-j monitors")
    printf '[{"name":"eDP-1","solitaryBlockedBy":["WINDOWED","CANDIDATE"]}]\n'
    ;;
  *)
    exit 1
    ;;
esac
SH

cat >"$fake_bin/quickshell" <<'SH'
#!/bin/bash

printf 'launched\n' >>"$OMARCHY_TEST_QS_LOG"
touch "$OMARCHY_TEST_GONE"
exit 255
SH

cat >"$fake_bin/systemd-cat" <<'SH'
#!/bin/bash

while (( $# > 0 )); do
  [[ $1 == "--" ]] && { shift; break; }
  shift
done
exec "$@"
SH

cat >"$fake_bin/logger" <<'SH'
#!/bin/bash
SH

chmod +x "$fake_bin/hyprctl" "$fake_bin/quickshell" "$fake_bin/systemd-cat" "$fake_bin/logger"
ln -s "$ROOT/bin/omarchy-hyprland-session-locked" "$fake_bin/omarchy-hyprland-session-locked"

PATH="$fake_bin:$PATH" \
OMARCHY_PATH="$shell_root" \
OMARCHY_TEST_QS_LOG="$qs_log" \
OMARCHY_TEST_GONE="$gone" \
HYPRLAND_INSTANCE_SIGNATURE=session_1000_1 \
WAYLAND_DISPLAY=wayland-1 \
  "$ROOT/bin/omarchy-launch-shell" 2>/dev/null &
launch_pid=$!

for (( waited = 0; waited < 100; waited++ )); do
  [[ -f $gone ]] && break
  sleep 0.05
done
[[ -f $gone ]] || fail "the supervised shell ran and exited"
sleep 0.3

kill -TERM "$launch_pid"
signalled_at=$EPOCHREALTIME
wait "$launch_pid" || fail "a signalled supervisor exits cleanly"
launch_pid=""
stopped_after=$(awk -v a="$signalled_at" -v b="$EPOCHREALTIME" 'BEGIN { printf "%.2f", b - a }')

awk -v s="$stopped_after" 'BEGIN { exit !(s < 1.5) }' ||
  fail "a supervisor asked to stop while checking the compositor stops promptly" "exited ${stopped_after}s after SIGTERM"
pass "a supervisor asked to stop while checking the compositor stops promptly (${stopped_after}s)"

Actual output at the PR head (b589086):

$ bash test/shell.d/launch-shell-stop-test.sh
exited 4.19s after SIGTERM
not ok - a supervisor asked to stop while checking the compositor stops promptly
$ echo $?
1

Actual output at the merge base (3faafba):

$ bash test/shell.d/launch-shell-stop-test.sh
ok - a supervisor asked to stop while checking the compositor stops promptly (0.66s)
$ echo $?
0

Related measurement from an equivalent setup without a signal: after the shell died and no compositor came back, the supervisor stood down after 4.54 s at the head and 1.01 s at the merge base.

What happens: the stop trap sets terminating, but compositor_alive does not check it, so the loop runs all 10 attempts (9 sleeps of 0.5 s) before the main loop sees the flag. The same was true before, with 3 attempts. Adding (( terminating )) && return 1 at the top of the loop makes this test pass at the head (0.16 s, measured with the full suggested launcher change).

Silent stand-down remains (from code reading, not reproduced). When adoption fails before a launch, run_shell returns 1. If compositor_alive then fails, the supervisor still exits without a log line (see #10930). If it succeeds, the log reports a shell exit with status 1 although no shell ran, and one of the 5 attempts is spent. Suggested change: log the stand-down.

Details: verified, optional note and related work

Verified (Hyprland v0.56.2 source, and a stubbed watchdog restart):

  • The respawned compositor gets a new signature, hyprctl against the old one exits 4, and hyprctl instances lists the replacement with instance and wl_socket independent of the signature.
  • Safe mode loads a recovery config without allow_session_lock_restore, and --locked denies a new lock client unless that option is set.
  • hyprctl eval 'hl.config(...)' goes through the Lua config manager in safe mode, and hyprctl exits 7 on an error: reply, so the logger branch fires.
  • In the stubbed restart, the head relaunches Quickshell against the replacement's signature and socket and issues the eval on the locked replacement; the merge base stands down.

Optional note (hypothesis, not reproduced): omarchy-hyprland-session-locked exits 2 when no monitor has a workspace yet, and allow_lock_restore treats 2 as unlocked, so the eval is skipped in that window. hyprctl -j locked exists in v0.56.2 and does not depend on workspaces. Using it, or enabling restore unless the helper exits 1, would remove that dependency.

Related: #12612 describes this crash-while-locked scenario. #11827 conflicts in compositor_alive, and its 30 s wait follows the inherited signature's socket file, which a crash leaves behind, so a combined version needs one design. #13628 and #13314 conflict trivially at the top of run_shell.


Review information

Test scope: Source and stubbed sandbox tests at b5890869; no real crash-to-lock run.

AI process: Opus 5.5 Medium coordination and synthesis, Opus 5.5 Xhigh technical review and final fact check, GPT 6 Sol Xhigh search for related issues, Opus 5.5 Medium editorial check.

Opt out: To stop receiving these reviews, reply to this comment saying so.

Adopting an instance before every launch moved a shell started by a live compositor onto whichever answering instance hyprctl listed first, and after a crash, before start-hyprland's replacement was up, onto another Hyprland of the same user: a nested one, or a second login. It also left the launcher tests with no shell at all, since their stubs list no instances.

The main loop already adopts in compositor_alive before every relaunch, so the first launch keeps what the compositor handed it, a relaunch keeps it while it answers, and a dead one is replaced only by an instance whose parent is the start-hyprland that ran it. That is the supervisor's grandparent, read at startup because the compositor execs it before hyprctl lists the instance, and checked by name so a compositor started without the watchdog stands down as before. A stop request is honoured in the widened check and before launching, instead of waiting out ten attempts or starting a shell into a session that is ending.

The launcher test now runs with a signature as a real session does, misses only monitor queries made after the shell dies so the pre-launch lock check doesn't use them up, and covers a relaunch beside another session and a locked watchdog restart.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Codex Medium <noreply@openai.com>
@omarchybot omarchybot added the verified Omarchy Triage has verified that this issue is ready for final review label Oct 3, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed and tested on an Omarchy VM (Hyprland 0.56.2), and I pushed one commit on top, 08b00cc, which fixes what the review below found.

The bug is real and this fixes it. On the VM I locked the session and killed Hyprland with SIGABRT. start-hyprland brought it back as --safe-mode --locked under a new signature. On quattro the shell supervisor and Quickshell were both gone after that, with nothing in the journal: the stranded lock from #12612. At this head the supervisor relaunched Quickshell on the replacement's signature and socket and turned on misc:allow_session_lock_restore, the lock plugin logged lock-stranded: recovering, and the lock screen came back (secure=true). With the change reverted, it failed the same way again.

What 08b00cc changes, and why:

  • Adopting an instance before every launch moved a healthy shell onto whichever answering compositor hyprctl instances listed first. It also broke the existing tests: launch-shell-test.sh failed and restart-shell-test.sh timed out, because their stubs list no instances. compositor_alive already adopts before every relaunch, so the first launch now keeps the instance the compositor handed it.
  • After a crash, the first answering instance is often another Hyprland of the same user (a nested one, or a second login), because the shell dies before the replacement is up. A dead compositor is now replaced only by a child of the start-hyprland process that ran it. That process is the supervisor's grandparent, read at startup, because hyprctl instances is still empty when autostart runs. It is checked by name, so a compositor started without the watchdog stands down exactly as on quattro.
  • A stop request is honoured inside the widened ten-attempt check and before launching. Before this, it waited out up to 4.5 s, or started a shell into a session that was ending.
  • launch-shell-test.sh now runs with an inherited signature, as a real session does. It covers a relaunch beside another session, and a locked watchdog restart (the shell follows the replacement, and lock restore goes only to the replacement). The locked-restart case fails on quattro.

Tests on the VM: launch-shell-test.sh 10/10, restart-shell-test.sh 9/9, hyprland-session-locked-test.sh and lock-stranded-recovery-test.sh green. ./test/cli has one failure, vscode generated theme references current theme file, and it fails identically on quattro.

Second opinion: Codex at medium effort reviewed this over three rounds. It contributed the other-session adoption case, the stop arriving during the pre-launch lock check, and the unverified grandparent, all fixed above. Its last round on 08b00cc found nothing. The earlier community review's findings (broken tests, oldest-first adoption, the stop delay) hold and are covered by the same commit.

This links #12612. It overlaps #11827 in compositor_alive, so whichever lands second will need a rebase. Next it waits on CI, then on the maintainer.

@omarchybot omarchybot removed the verified Omarchy Triage has verified that this issue is ready for final review label Oct 3, 2026
@greptile-apps

greptile-apps Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 4/5

[Medium risk] Shell supervisor restart logic after compositor lock.

The PR should not merge until a locked restart with initially unreadable output state can reliably restore the unlock screen.

Findings

  1. P1 Lock restoration can be skipped ▶
  2. P2 Empty socket shifts instance fields ▶
  3. P2 Test accepts any eval command ▶

Summary

The PR teaches the shell supervisor to follow a responsive replacement Hyprland instance belonging to its session watchdog, updates its Wayland display, and attempts to enable session-lock restoration before relaunching Quickshell.

  • Adds restart polling and same-watchdog instance selection.
  • Adds tests for a second session and a locked replacement.
  • The restoration check needs to account for an initially undetermined lock state.
Diagram
%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Quickshell exits] --> B{Inherited compositor responds?}
  B -- Yes --> E[Keep inherited instance]
  B -- No --> C[Poll instances for watchdog child]
  C -- Found --> D[Export signature and Wayland socket]
  C -- Retry window expires --> X[Supervisor exits]
  D --> F[Check session lock]
  E --> F
  F -- Locked --> G[Enable lock restoration]
  F -- Unlocked or undetermined --> H[Launch Quickshell]
  G --> H
Loading

Reviews (1) · Last reviewed commit: "Follow only this session's watchdog afte..."

Comment thread bin/omarchy-launch-shell
# normally set. A lock request against a stranded session is then a fatal
# Wayland error and Quickshell exits instead of drawing the unlock screen.
allow_lock_restore() {
if omarchy-hyprland-session-locked; then

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Lock restoration can be skipped If the replacement compositor answers while its outputs still have no workspace, omarchy-hyprland-session-locked returns “undetermined.” This check then skips enabling lock restoration. Quickshell retries its stranded-lock check later, but its attempt to reacquire the lock can fail fatally, leaving no unlock screen. Retry the lock-state check before launching Quickshell, or enable restoration for the safe-mode replacement without treating “undetermined” as unlocked.

Comment thread bin/omarchy-launch-shell
fi
[[ -n $watchdog_pid ]] || return 1

while IFS=$'\t' read -r sig socket pid; do

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Empty socket shifts instance fields If an instance has a missing or empty wl_socket, the jq output contains two adjacent tabs. Bash read collapses them, putting the PID in socket and leaving pid empty. The parent-PID check then skips that instance before checking whether it responds, so the supervisor cannot adopt a live replacement in this case. Parse the fields without losing empty columns.

Comment on lines +79 to +82
eval*)
printf '%s\n' "$HYPRLAND_INSTANCE_SIGNATURE" >>"$OMARCHY_TEST_EVAL_LOG"
printf 'ok\n'
exit 0

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Test accepts any eval command The fake returns success for every eval invocation, while the crash test checks only which instance received it. The test would still pass with a wrong setting name or expression, missing a failure that prevents the unlock screen from returning. Check the command argument and cover a failed response.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

@lionelkanyowa

Copy link
Copy Markdown

Another real-world case of the problem this PR fixes, on an unlocked session. It also shows a knock-on effect: omarchy-crash-watch never reports a compositor crash.

System: Omarchy 4.0.4-1, Hyprland 0.56.2-2, linux-omarchy 7.2.5-3, RX 6600 (Navi 23). An amdgpu page fault from Hyprland:cs0 makes Hyprland abort in CHyprOpenGLImpl::begin. That crash is upstream's problem, and I mention it only as the trigger.

What happened on 2026-10-14:

07:53:59  Hyprland 1369 SIGABRT (session not locked)
07:54:00  quickshell[1451]: Error reading events from display: Broken pipe
07:54:00  start-hyprland: Hyprland exit not-cleanly, restarting   -> Hyprland --watchdog-fd 4 --safe-mode
08:03:33  Hyprland 11083 (the safe-mode instance) SIGABRT, restarted again in --safe-mode
08:05:12  quickshell first starts again, and only because `omarchy-restart-shell` was run by hand

The shell, including notifications and the polkit agent, was gone for about 11 minutes and through both crashes. omarchy-launch-shell was still running but never relaunched Quickshell. That matches the stale HYPRLAND_INSTANCE_SIGNATURE described here.

Knock-on effect: omarchy-crash-watch saw both Hyprland core dumps. announce() then calls omarchy-notification-wait, which waited 10 s for a notification server that wasn't coming back, so each toast was dropped. Because the watcher follows journalctl -f -n 0, a missed toast is never retried, and nothing is logged. On this machine the stock watcher has never once reported a Hyprland crash over about 7 weeks and more than a dozen crashes. Compositor crashes are the ones most worth reporting, and they are the only ones it can't deliver.

Once this PR restores the shell after the watchdog restart, crash-watch should work again as long as Quickshell claims org.freedesktop.Notifications within the 10 s wait. It might be worth checking that timing when testing this PR, and adding a test where Hyprland is restarted without a lock as well as the locked case.

Filed by Claude Opus 5.5 via Claude Code.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Hard lockout after Hyprland crash while idle-locked — lockdead screen has no local recovery

4 participants