Proof Portal
Omarchy
ProbeLabs65 findings · 95 requirementsA proof layer — requirements, tests and verified fixes — for two of Omarchy's subsystems: the application menu (launcher scripts, QML model, JSONC config, search and selection) and the lock screen (lock scripts, QML, PAM authentication). Scope is deliberately limited to those components of omacom/omarchy; the rest of the distribution is not covered.
omarchy-restart-shell trusts a stale HYPRLAND_INSTANCE_SIGNATURE, leaving the session with no shell after omarchy update
Reported by bezilaszlo · filed Sep 3, 2026 · open at source
At a glance
- 1 · What is claimed?
- Only the report text below — no validator has restated it as checkable claims yet.
- 2 · What does it affect?
- AreaOutside the audited area· Decided by agents · verified
- 3 · Is it reproducible?
- No validation has been run yet.
- 4 · What remains unclear?
- Not validated yet: no claims, no reproducer.
- 5 · What happens next?
- Decided by agents and verified by a second, independent agent — see the decision.
Original report
What happened
omarchy update finished its package transaction, then its shell restart step failed:
Restarting shell
All plugins have been reloaded
Omarchy shell did not become ready after restart.The session was left with no bar and no notifications, and the message gives no hint as to why. omarchy restart shell reproduced the same failure on every subsequent attempt.
Root cause
bin/omarchy-restart-shell only derives the Hyprland instance signature when the variable is unset, so a variable that is set but stale is trusted blindly:
https://github.com/basecamp/omarchy/blob/master/bin/omarchy-restart-shell#L14-L19
# Allow running from outside the session (e.g. over ssh) by deriving the
# Hyprland instance signature from the newest instance runtime dir.
if [[ -z ${HYPRLAND_INSTANCE_SIGNATURE:-} ]]; then
hypr_dir=$(find "${XDG_RUNTIME_DIR:-/run/user/$UID}/hypr" -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\n' | sort -n | tail -n 1 | cut -d' ' -f2-)
[[ -n $hypr_dir ]] && export HYPRLAND_INSTANCE_SIGNATURE=${hypr_dir##*/}
fiIf Hyprland has been restarted since a terminal was opened, that terminal still exports the previous instance signature. The script keeps it, and the hyprctl dispatch that spawns the shell then talks to a dead socket:
$ hyprctl version
Couldn't connect to /run/user/1000/hypr/<old-signature>/.socket.sock. (4)That dispatch's stderr is discarded, so the failure is silent; the script polls 20 times and reports only the generic "did not become ready" message.
Notably, line 8 already solves exactly this class of staleness for a different variable, with a comment describing the same reasoning:
session_omarchy_path=$(systemctl --user show-environment 2>/dev/null | sed -n 's/^OMARCHY_PATH=//p' | tail -n 1)The systemd user environment holds the correct, live signature — Hyprland updates it on session start — so the same treatment would have avoided this. On the affected machine:
$ systemctl --user show-environment | grep HYPRLAND_INSTANCE_SIGNATURE
HYPRLAND_INSTANCE_SIGNATURE=efb5099...1788366025_1900155456 # live
$ echo $HYPRLAND_INSTANCE_SIGNATURE # in the terminal
efb5099...1788257371_1303222695 # dead, ~30h olderTwo instance dirs were present in /run/user/1000/hypr/; only the newer one had a responding socket.
Steps to reproduce
- Open a terminal.
- Restart Hyprland (or log out and back in), leaving that terminal open.
- In that same terminal, run
omarchy restart shell(oromarchy update, which calls it). - It prints "Omarchy shell did not become ready after restart" and the session is left without a shell.
Expected
The shell restarts. A signature that no longer has a live socket should be discarded and re-derived, rather than trusted because it happens to be non-empty.
Suggested fix
Prefer the systemd user environment, and/or validate the socket before trusting the variable — e.g. treat a signature whose .socket.sock does not respond the same as an unset one, falling through to the existing newest-runtime-dir logic. Surfacing the hyprctl dispatch error would also turn a mystifying failure into a diagnosable one.
Workaround
Re-exporting the live signature, or launching omarchy-launch-shell directly, brings the shell back:
export HYPRLAND_INSTANCE_SIGNATURE=$(systemctl --user show-environment | sed -n 's/^HYPRLAND_INSTANCE_SIGNATURE=//p')
omarchy restart shellSystem details
- Omarchy 4.0.2-1 (
bin/omarchy-restart-shellonmasteris byte-identical to the installed copy) - Hyprland via uwsm, quickshell 0.3.1-1
- Linux 7.1.9-arch1-2
- Intel Core i7-7700HQ; Intel HD Graphics 630 + NVIDIA GTX 1050 Ti Mobile (
nvidia-580xx-dkms)
View raw text
### What happened
`omarchy update` finished its package transaction, then its shell restart step failed:
```
Restarting shell
All plugins have been reloaded
Omarchy shell did not become ready after restart.
```
The session was left with **no bar and no notifications**, and the message gives no hint as to why. `omarchy restart shell` reproduced the same failure on every subsequent attempt.
### Root cause
`bin/omarchy-restart-shell` only derives the Hyprland instance signature when the variable is **unset**, so a variable that is set but **stale** is trusted blindly:
https://github.com/basecamp/omarchy/blob/master/bin/omarchy-restart-shell#L14-L19
```bash
# Allow running from outside the session (e.g. over ssh) by deriving the
# Hyprland instance signature from the newest instance runtime dir.
if [[ -z ${HYPRLAND_INSTANCE_SIGNATURE:-} ]]; then
hypr_dir=$(find "${XDG_RUNTIME_DIR:-/run/user/$UID}/hypr" -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\n' | sort -n | tail -n 1 | cut -d' ' -f2-)
[[ -n $hypr_dir ]] && export HYPRLAND_INSTANCE_SIGNATURE=${hypr_dir##*/}
fi
```
If Hyprland has been restarted since a terminal was opened, that terminal still exports the **previous** instance signature. The script keeps it, and the `hyprctl dispatch` that spawns the shell then talks to a dead socket:
```
$ hyprctl version
Couldn't connect to /run/user/1000/hypr/<old-signature>/.socket.sock. (4)
```
That dispatch's stderr is discarded, so the failure is silent; the script polls 20 times and reports only the generic "did not become ready" message.
Notably, line 8 already solves exactly this class of staleness for a different variable, with a comment describing the same reasoning:
```bash
session_omarchy_path=$(systemctl --user show-environment 2>/dev/null | sed -n 's/^OMARCHY_PATH=//p' | tail -n 1)
```
The systemd user environment holds the **correct, live** signature — Hyprland updates it on session start — so the same treatment would have avoided this. On the affected machine:
```
$ systemctl --user show-environment | grep HYPRLAND_INSTANCE_SIGNATURE
HYPRLAND_INSTANCE_SIGNATURE=efb5099...1788366025_1900155456 # live
$ echo $HYPRLAND_INSTANCE_SIGNATURE # in the terminal
efb5099...1788257371_1303222695 # dead, ~30h older
```
Two instance dirs were present in `/run/user/1000/hypr/`; only the newer one had a responding socket.
### Steps to reproduce
1. Open a terminal.
2. Restart Hyprland (or log out and back in), leaving that terminal open.
3. In that same terminal, run `omarchy restart shell` (or `omarchy update`, which calls it).
4. It prints "Omarchy shell did not become ready after restart" and the session is left without a shell.
### Expected
The shell restarts. A signature that no longer has a live socket should be discarded and re-derived, rather than trusted because it happens to be non-empty.
### Suggested fix
Prefer the systemd user environment, and/or validate the socket before trusting the variable — e.g. treat a signature whose `.socket.sock` does not respond the same as an unset one, falling through to the existing newest-runtime-dir logic. Surfacing the `hyprctl dispatch` error would also turn a mystifying failure into a diagnosable one.
### Workaround
Re-exporting the live signature, or launching `omarchy-launch-shell` directly, brings the shell back:
```bash
export HYPRLAND_INSTANCE_SIGNATURE=$(systemctl --user show-environment | sed -n 's/^HYPRLAND_INSTANCE_SIGNATURE=//p')
omarchy restart shell
```
### System details
- Omarchy 4.0.2-1 (`bin/omarchy-restart-shell` on `master` is byte-identical to the installed copy)
- Hyprland via uwsm, quickshell 0.3.1-1
- Linux 7.1.9-arch1-2
- Intel Core i7-7700HQ; Intel HD Graphics 630 + NVIDIA GTX 1050 Ti Mobile (`nvidia-580xx-dkms`)
Validation
Not checked yet. A validator will restate this report as checkable claims, map it to the project's requirements and write a reproducer that the proof engine runs.
Linked
Not linked to any known issue, other report or change yet.
Decision
Decisions are recorded by our staff — or, where this project allows it, by agents: checked by a second, independent agent, or by a single agent where the project's policy says so. Any decision reached so far is shown below.
- Out of scopeDecided by agents · verified · 2026-10-09 10:39 UTC