### Symptom

`Super + Space` (Omarchy menu) silently stops working. Nothing is printed anywhere:

- The Hyprland binding is still registered — `hyprctl binds | grep -B4 -A6 'key: SPACE'` shows
  `modmask 64, key: SPACE, dispatcher: __lua, description: Omarchy menu`.
- IPC still answers: `omarchy-shell shell ping` → `ok`.
- No window appears. `omarchy menu summon root` also does nothing visible.

It happened repeatedly between **2026-09-29 and 2026-10-01**, always right after an `omarchy update`,
and again after monitor power-off events.

### Why it happens

`omarchy-menu` is not a program the keybind launches — it is an IPC call into the running `quickshell`
process. The keybind therefore keeps looking registered while the receiver is broken, and the *only*
visible symptom is a dead key.

Two independent triggers, both visible in the journal:

**A. Package updates restart the shell, and a crash during that restart leaves a second engine generation.**

Every `omarchy update` rewrites the live QML tree under `/usr/share/omarchy/shell` and the shell is
restarted right after the transaction. Correlating `pacman.log` with `-t omarchy-shell`:

| package transaction | shell restart | delta |
| --- | --- | --- |
| Sep 29 09:16:59 `omarchy` r6663 → r6688 | Sep 29 09:17:16 | 17 s |
| Sep 29 21:28:52 `omarchy` r6688 → r6689 | Sep 29 21:28:55 | 3 s |
| Sep 30 10:33:57 `omarchy` r6689 → r6691 | Sep 30 10:34:00 | 3 s |
| Oct 1 14:50:13 `openssl` 3.6.4 → 3.6.5, `qt6-tools` | Oct 1 14:50:38 | 25 s |
| Oct 1 18:26:30 `harfbuzz`, `egl-wayland`, `omarchy` r6691 → r6692 | Oct 1 **18:27:02 → crash** | 28 s |

At 18:27:02 the restart turned into a real crash (`quickshell` 0.3.1 SIGSEGV during `exit()`; filed
upstream against quickshell separately, coredump kept). What matters *for Omarchy* is what the log
shows next:

```
18:27:02 quickshell: INFO: Exiting due to IPC request.
18:27:02 quickshell: ERROR: Quickshell has crashed under pid 2884857
18:27:02 quickshell: ERROR: Quickshell has been restarted.
18:27:02 quickshell: INFO: Launching config: "/usr/share/omarchy/shell/shell.qml"
18:27:02           new engine pid 2884859 starts as a child of the crashing supervisor
18:27:05 supervisor exits with status 255 -> omarchy-launch-shell relaunches (pid 2886626)
```

`omarchy-launch-shell` relaunches after the signal death **without first reaping the engine that
quickshell's crash handler already spawned**. From that moment there were 2 `quickshell` processes,
2 `by-id/*/ipc.sock` sockets, and the menu IPC could be served by the generation whose scene belongs
to a dead compositor session — i.e. `ping ok` but no menu, forever.

`omarchy-launch-shell` already knows the sibling hazard — its own header comment says:

> A package upgrade rewriting `$OMARCHY_PATH/shell` would otherwise reload it against a half-written
> tree, and **that failed reload leaves a second engine generation behind** that turns the next
> restart's IPC kill into a crash.

and `omarchy-restart-shell` already contains the correct collapse loop:

```bash
# /usr/share/omarchy/bin/omarchy-restart-shell
while timeout 5 quickshell kill -p "$CONFIG_DIR" --any-display >/dev/null 2>&1; do :; done
```

…but `omarchy-launch-shell` does not use it on the crash path.

**B. A shell started (or reloaded) while the compositor has no outputs binds a placeholder screen.**

19 occurrences in 3 days — around idle / monitor power-off and around login:

```
INFO qt.qpa.wayland: There are no outputs - creating placeholder screen
WARN: Layershell screen does not correspond to a real screen. Letting the compositor pick.
```

Each of these also re-registers every QML IPC handler inside the *live* instance, producing bursts of
`WARN scene: QML IpcHandler … Handler was registered but will not be used because another handler is
registered for target …` — 44 of them in one minute at 2026-09-30 20:19. Result: the bar draws, the
menu window does not exist.

### Why the recovery path is bad

The only documented recovery is `omarchy refresh shell`, which **factory-resets `~/.config/omarchy/shell.json`**
and wipes a customized bar layout (third-party widgets, per-widget timezone lists, etc.).
`omarchy restart shell` fixes the running session, but nothing detects or repairs the overlapping-generation
state on its own — I measured 2 instances sitting there for hours, with `ping` still answering `ok`, so
no health check noticed.

### Suggested fixes

1. **`omarchy-launch-shell`: reap before relaunching after a signal death.** Run the same
   `while timeout 5 quickshell kill -p "$CONFIG_DIR" --any-display; do :; done` loop that
   `omarchy-restart-shell` uses, so a crash-handler-spawned generation can never coexist with the
   supervised one.
2. **Refuse to launch when the compositor reports no enabled output**, and retry shortly instead:
   `hyprctl -j monitors | jq -e 'any(.[]; .disabled|not)'`. That removes trigger B entirely at login
   and after resume, and it also stops the `wayvnc` "No such output" crash loop I see in the same
   windows.
3. **Add a cheap `omarchy doctor` / `omarchy repair shell`** that reports instance count, per-instance
   `ipc.sock`, whether any instance bound a placeholder screen, and collapses duplicates. Right now the
   diagnosis requires reading `/run/user/$UID/quickshell/by-pid/*` by hand.
4. **Make the shell's health check IPC-plus-window**, not IPC-only. `ping` returning `ok` while the menu
   cannot open is what makes this look like a keybind bug rather than a shell bug.
5. *(optional)* Note in `omarchy restart shell` docs that it preserves `shell.json` and is the correct
   recovery, since `refresh shell` is the discoverable one and it destroys config.

### Environment

```
Omarchy 4.0.0.r6692.gc05d901-1 (omarchy-dev, Arch Linux)
quickshell 0.3.1-1, Qt 6.11.2-3, Hyprland 0.56.2, systemd-uwsm session, amdgpu
Config: /usr/share/omarchy/shell/shell.qml (shell.json untouched by the fix below)
```

### Workaround currently in place

A user-owned `~/.local/bin/omarchy-shell-guard` + systemd user timer (60 s) that pings the shell and,
when it finds >1 `quickshell` instance, collapses them with `omarchy-restart-shell`; when it finds an
instance that logged a placeholder screen, it restarts it once per instance id and only if a real output
exists again; and when the process is present but silent on IPC for 3 consecutive polls, it restarts it.
That keeps the menu alive, but it is a watchdog for a gap upstream could close in ~5 lines.