Proof Portal

Project overview

Omarchy

ProbeLabs65 findings · 95 requirements

A 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.

Inbox
ReportR-882GitHub issuePublicFixed

omarchy-hyprland-monitor-external-active is fooled by the synthetic FALLBACK monitor, so the internal panel never recovers when the external monitor is unplugged

Reported by gtf-inet · filed Sep 7, 2026 · open at source

Decided: Out of scope — decided by agents · verified 3 days ago.

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

omarchy-hyprland-monitor-external-active is fooled by the synthetic FALLBACK monitor, so the internal panel never recovers when the external monitor is unpluggedrevision 1 · captured 2026-09-28 21:23 UTC via poll

What happened

On a laptop + external monitor setup where the internal panel (eDP-1) has
been soft-disabled via omarchy-hyprland-monitor-internal off (external-only
mode), physically unplugging the external monitor does not re-enable the
internal panel. The screen goes black instead of falling back to the laptop
display, even though omarchy-hyprland-monitor-watch is running and the
monitorremoved event fires correctly.

Root cause

When the external monitor is unplugged while eDP-1 is config-disabled,
Hyprland/aquamarine has no remaining real output and creates a synthetic
FALLBACK headless monitor so it isn't left with zero monitors.

omarchy-hyprland-monitor-external-active (in
omarchy-hyprland-monitor-clamshell) checks:

hyprctl monitors all -j | jq -e '.[] | select(.name | test("^(eDP|LVDS|DSI)-") | not) | select(.disabled == false)'

This matches FALLBACK too (it isn't named eDP*/LVDS*/DSI* and isn't
disabled), so the function reports "an external monitor is active" even
though the real one was just removed. omarchy-hyprland-monitor-internal's
recover() then short-circuits on that check and never removes the
internal-monitor-disable toggle flag, leaving eDP-1 disabled forever
(until the user manually intervenes).

Steps to reproduce

  1. Laptop with an internal panel + an external monitor connected.
  2. omarchy-hyprland-monitor-internal off (disable internal, external-only).
  3. Physically unplug the external monitor's cable.
  4. Expected: internal panel re-enables automatically.
  5. Actual: screen stays black. hyprctl monitors all -j shows eDP-1 still

"disabled": true and a FALLBACK monitor in its place.

Confirmed live via socat -U - UNIX-CONNECT:$SOCKET on .socket2.sock: the
correct monitorremoved>>HDMI-A-1 / monitorremovedv2>>... events do fire,
but omarchy-hyprland-monitor-external-active still exits 0 immediately
after, because of the FALLBACK monitor.

Evidence

Live capture of Hyprland's socket2 IPC events at the moment of unplugging,
with the state of omarchy-hyprland-monitor-external-active and the toggle
flag checked immediately after each event:

22:42:26.577910760 EVENT: monitorremoved>>HDMI-A-1
  external-active exit=0
  toggle-flag-present=yes
    eDP-1 disabled=True
    FALLBACK disabled=False
22:42:26.615480742 EVENT: monitorremovedv2>>2,HDMI-A-1,LG Electronics LG ULTRAGEAR+ 512NTQDGB572
  external-active exit=0
  toggle-flag-present=yes
    eDP-1 disabled=True
    FALLBACK disabled=False
22:42:26.650419651 EVENT: monitoradded>>FALLBACK
  external-active exit=0
  toggle-flag-present=yes
    eDP-1 disabled=True
    FALLBACK disabled=False
22:42:26.689077230 EVENT: monitoraddedv2>>1,FALLBACK,
  external-active exit=0
  toggle-flag-present=yes
    eDP-1 disabled=True
    FALLBACK disabled=False

external-active exit=0 (true) right after HDMI-A-1 is removed and only
FALLBACK remains confirms the check is fooled by the synthetic monitor,
which is why internal-monitor-disable's toggle flag (toggle-flag-present=yes)
never gets cleared.

Expected behavior

omarchy-hyprland-monitor-external-active (and any other check relying on
"is a real external monitor connected") should exclude Hyprland's synthetic
FALLBACK output, e.g.:

hyprctl monitors all -j | jq -e '.[] | select(.name != "FALLBACK") | select(.name | test("^(eDP|LVDS|DSI)-") | not) | select(.disabled == false)'

System info

  • Omarchy: 4.0.2-1
  • Hyprland: 0.56.2 (commit efb50993780079460b0cbed1363e2166a2de1d9f)
  • CPU: AMD Ryzen 7 6800H
  • GPU: NVIDIA GeForce RTX 3050 Ti Mobile (GA107M) + AMD Radeon 680M (Rembrandt) — hybrid graphics laptop
  • Monitors: internal eDP-1 (1920x1200@165) + external HDMI-A-1, LG UltraGear 4K (3840x2160@144)

Workaround

Until this is fixed upstream, a small user-level watcher script listening for
the specific external monitor's monitorremoved event, excluding FALLBACK
from the active-check, and clearing the toggle flag + hyprctl reload when no
real external remains. Save as e.g. ~/.config/hypr/scripts/external-monitor-recovery-fix.sh,
set EXTERNAL to your external monitor's connector name (hyprctl monitors),
chmod +x it, and start it with o.launch_on_start(...) in
~/.config/hypr/autostart.lua:

#!/bin/bash
# Fixes a bug in Omarchy's own laptop-panel recovery: when eDP-1 is soft-disabled
# (via `omarchy-hyprland-monitor-internal off`) and the external monitor is
# unplugged, Hyprland creates a synthetic "FALLBACK" headless output so it's
# never left with zero monitors. Omarchy's `omarchy-hyprland-monitor-external-active`
# check doesn't exclude FALLBACK, so it thinks an external monitor is still
# active and never re-enables eDP-1 -- the screen stays on the invisible
# FALLBACK output. This script watches for the specific external monitor being
# removed and, if no *real* external monitor remains, re-enables eDP-1 itself.

EXTERNAL="HDMI-A-1"  # <- set to your external monitor's connector name
LOCK="${XDG_RUNTIME_DIR:-/tmp}/omarchy-external-monitor-fix.lock"
TOGGLE_FLAG="$HOME/.local/state/omarchy/toggles/hypr/internal-monitor-disable.lua"
SOCKET="$XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock"

exec 9>"$LOCK"
flock -n 9 || exit 0

real_external_active() {
  hyprctl monitors all -j | jq -e \
    '.[] | select(.name != "FALLBACK") | select(.name | test("^(eDP|LVDS|DSI)-") | not) | select(.disabled == false)' \
    >/dev/null 2>&1
}

recover_if_stuck() {
  [[ -f $TOGGLE_FLAG ]] || return 0
  real_external_active && return 0
  rm -f "$TOGGLE_FLAG"
  hyprctl reload >/dev/null 2>&1
  hyprctl dispatch 'hl.dsp.dpms({ action = "enable" })' >/dev/null 2>&1
}

while read -r event; do
  case "$event" in
    monitorremoved">>"$EXTERNAL | monitorremovedv2">>"*,$EXTERNAL,*)
      # Give Hyprland a moment to settle on FALLBACK before checking.
      sleep 0.3
      recover_if_stuck
      ;;
  esac
done < <(socat -U - "UNIX-CONNECT:$SOCKET")
View raw text
## What happened

On a laptop + external monitor setup where the internal panel (`eDP-1`) has
been soft-disabled via `omarchy-hyprland-monitor-internal off` (external-only
mode), physically unplugging the external monitor does **not** re-enable the
internal panel. The screen goes black instead of falling back to the laptop
display, even though `omarchy-hyprland-monitor-watch` is running and the
`monitorremoved` event fires correctly.

## Root cause

When the external monitor is unplugged while `eDP-1` is config-disabled,
Hyprland/aquamarine has no remaining real output and creates a synthetic
`FALLBACK` headless monitor so it isn't left with zero monitors.

`omarchy-hyprland-monitor-external-active` (in
`omarchy-hyprland-monitor-clamshell`) checks:

```bash
hyprctl monitors all -j | jq -e '.[] | select(.name | test("^(eDP|LVDS|DSI)-") | not) | select(.disabled == false)'
```

This matches `FALLBACK` too (it isn't named `eDP*`/`LVDS*`/`DSI*` and isn't
disabled), so the function reports "an external monitor is active" even
though the real one was just removed. `omarchy-hyprland-monitor-internal`'s
`recover()` then short-circuits on that check and never removes the
`internal-monitor-disable` toggle flag, leaving `eDP-1` disabled forever
(until the user manually intervenes).

## Steps to reproduce

1. Laptop with an internal panel + an external monitor connected.
2. `omarchy-hyprland-monitor-internal off` (disable internal, external-only).
3. Physically unplug the external monitor's cable.
4. Expected: internal panel re-enables automatically.
5. Actual: screen stays black. `hyprctl monitors all -j` shows `eDP-1` still
   `"disabled": true` and a `FALLBACK` monitor in its place.

Confirmed live via `socat -U - UNIX-CONNECT:$SOCKET` on `.socket2.sock`: the
correct `monitorremoved>>HDMI-A-1` / `monitorremovedv2>>...` events do fire,
but `omarchy-hyprland-monitor-external-active` still exits 0 immediately
after, because of the `FALLBACK` monitor.

## Evidence

Live capture of Hyprland's socket2 IPC events at the moment of unplugging,
with the state of `omarchy-hyprland-monitor-external-active` and the toggle
flag checked immediately after each event:

```
22:42:26.577910760 EVENT: monitorremoved>>HDMI-A-1
  external-active exit=0
  toggle-flag-present=yes
    eDP-1 disabled=True
    FALLBACK disabled=False
22:42:26.615480742 EVENT: monitorremovedv2>>2,HDMI-A-1,LG Electronics LG ULTRAGEAR+ 512NTQDGB572
  external-active exit=0
  toggle-flag-present=yes
    eDP-1 disabled=True
    FALLBACK disabled=False
22:42:26.650419651 EVENT: monitoradded>>FALLBACK
  external-active exit=0
  toggle-flag-present=yes
    eDP-1 disabled=True
    FALLBACK disabled=False
22:42:26.689077230 EVENT: monitoraddedv2>>1,FALLBACK,
  external-active exit=0
  toggle-flag-present=yes
    eDP-1 disabled=True
    FALLBACK disabled=False
```

`external-active exit=0` (true) right after `HDMI-A-1` is removed and only
`FALLBACK` remains confirms the check is fooled by the synthetic monitor,
which is why `internal-monitor-disable`'s toggle flag (`toggle-flag-present=yes`)
never gets cleared.

## Expected behavior

`omarchy-hyprland-monitor-external-active` (and any other check relying on
"is a real external monitor connected") should exclude Hyprland's synthetic
`FALLBACK` output, e.g.:

```bash
hyprctl monitors all -j | jq -e '.[] | select(.name != "FALLBACK") | select(.name | test("^(eDP|LVDS|DSI)-") | not) | select(.disabled == false)'
```

## System info

- Omarchy: 4.0.2-1
- Hyprland: 0.56.2 (commit efb50993780079460b0cbed1363e2166a2de1d9f)
- CPU: AMD Ryzen 7 6800H
- GPU: NVIDIA GeForce RTX 3050 Ti Mobile (GA107M) + AMD Radeon 680M (Rembrandt) — hybrid graphics laptop
- Monitors: internal `eDP-1` (1920x1200@165) + external `HDMI-A-1`, LG UltraGear 4K (3840x2160@144)

## Workaround

Until this is fixed upstream, a small user-level watcher script listening for
the specific external monitor's `monitorremoved` event, excluding `FALLBACK`
from the active-check, and clearing the toggle flag + `hyprctl reload` when no
real external remains. Save as e.g. `~/.config/hypr/scripts/external-monitor-recovery-fix.sh`,
set `EXTERNAL` to your external monitor's connector name (`hyprctl monitors`),
`chmod +x` it, and start it with `o.launch_on_start(...)` in
`~/.config/hypr/autostart.lua`:

```bash
#!/bin/bash
# Fixes a bug in Omarchy's own laptop-panel recovery: when eDP-1 is soft-disabled
# (via `omarchy-hyprland-monitor-internal off`) and the external monitor is
# unplugged, Hyprland creates a synthetic "FALLBACK" headless output so it's
# never left with zero monitors. Omarchy's `omarchy-hyprland-monitor-external-active`
# check doesn't exclude FALLBACK, so it thinks an external monitor is still
# active and never re-enables eDP-1 -- the screen stays on the invisible
# FALLBACK output. This script watches for the specific external monitor being
# removed and, if no *real* external monitor remains, re-enables eDP-1 itself.

EXTERNAL="HDMI-A-1"  # <- set to your external monitor's connector name
LOCK="${XDG_RUNTIME_DIR:-/tmp}/omarchy-external-monitor-fix.lock"
TOGGLE_FLAG="$HOME/.local/state/omarchy/toggles/hypr/internal-monitor-disable.lua"
SOCKET="$XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock"

exec 9>"$LOCK"
flock -n 9 || exit 0

real_external_active() {
  hyprctl monitors all -j | jq -e \
    '.[] | select(.name != "FALLBACK") | select(.name | test("^(eDP|LVDS|DSI)-") | not) | select(.disabled == false)' \
    >/dev/null 2>&1
}

recover_if_stuck() {
  [[ -f $TOGGLE_FLAG ]] || return 0
  real_external_active && return 0
  rm -f "$TOGGLE_FLAG"
  hyprctl reload >/dev/null 2>&1
  hyprctl dispatch 'hl.dsp.dpms({ action = "enable" })' >/dev/null 2>&1
}

while read -r event; do
  case "$event" in
    monitorremoved">>"$EXTERNAL | monitorremovedv2">>"*,$EXTERNAL,*)
      # Give Hyprland a moment to settle on FALLBACK before checking.
      sleep 0.3
      recover_if_stuck
      ;;
  esac
done < <(socat -U - "UNIX-CONNECT:$SOCKET")
```

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

  • Fixed bypr/7146· confirmed

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 11:02 UTC