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 theme bg next` never advances when ~/.config/omarchy/backgrounds/<theme> is a symlink
Reported by thorhj · filed Aug 27, 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
System details
Omarchy 4.0.0-1 · AMD Ryzen 5 7600X · NVIDIA RTX 3070 (+ AMD Raphael iGPU)
What's wrong?
Description
If the user backgrounds directory ~/.config/omarchy/backgrounds/<theme>/ is a symlink (e.g. into a stow/chezmoi-managed dotfiles repo), omarchy theme bg next always selects the alphabetically first image and never advances. The same index lookup in omarchy-theme-set (choose_theme_background) has the identical problem.
Root cause is a path-canonicalisation mismatch between two scripts:
bin/omarchy-theme-bg-set:12stores the current background asrealpath "$1", i.e. with the symlink resolved (/home/u/dotfiles/.../foo.jpg).bin/omarchy-theme-bg-nextbuilds the candidate list withfind -L "$HOME/.config/omarchy/backgrounds/$THEME_NAME/", which yields unresolved paths (/home/u/.config/omarchy/backgrounds/<theme>/foo.jpg), then does a plain string compare againstreadlinkof the state symlink.
The two strings never match, so INDEX stays -1 and the script falls through to BACKGROUNDS[0] on every invocation. The first call "works"; every call after that is a no-op.
The background switcher is unaffected because it calls bg-set with an explicit file. Stock theme backgrounds are unaffected because current/theme/backgrounds/ is a real copied directory.
Steps to reproduce
Isolated, without touching the live setup (stubs omarchy-shell so the wallpaper isn't actually changed):
S=$(mktemp -d)
mkdir -p "$S/home/.local/state/omarchy/current/theme/backgrounds" \
"$S/home/.config/omarchy/backgrounds" "$S/real-walls" "$S/stubs"
echo t > "$S/home/.local/state/omarchy/current/theme.name"
for f in a b c; do printf x > "$S/real-walls/$f.jpg"; done
printf '#!/bin/sh\nexit 0\n' > "$S/stubs/omarchy-shell"
cp "$S/stubs/omarchy-shell" "$S/stubs/omarchy-notification-send"; chmod +x "$S/stubs"/*
ln -s "$S/real-walls" "$S/home/.config/omarchy/backgrounds/t"
for i in 1 2 3 4; do
HOME="$S/home" PATH="$S/stubs:$PATH" omarchy-theme-bg-next
readlink "$S/home/.local/state/omarchy/current/background"
doneOr on a real install: ln -s ~/Pictures/walls ~/.config/omarchy/backgrounds/catppuccin, run omarchy theme bg next a few times, watch omarchy theme bg current.
Expected: cycles a.jpg → b.jpg → c.jpg → a.jpg, as it does when the directory is real (verified with cp -r in place of ln -s).
Actual: a.jpg four times.
Suggested fix
Compare canonical paths on both sides, in bg-next and in choose_theme_background:
CURRENT_BACKGROUND=$(readlink -f "$CURRENT_BACKGROUND_LINK")
...
if [[ $(realpath "${BACKGROUNDS[$i]}") == "$CURRENT_BACKGROUND" ]]; thenAlternatively drop realpath from bg-set — but resolving on the comparison side is more robust (also covers bg set with a relative path).
Related but distinct: #7668 (choose_theme_background fails the same lookup on theme switch, for a different reason). Both would benefit from a canonical-path comparison.
View raw text
### System details
Omarchy 4.0.0-1 · AMD Ryzen 5 7600X · NVIDIA RTX 3070 (+ AMD Raphael iGPU)
### What's wrong?
### Description
If the user backgrounds directory `~/.config/omarchy/backgrounds/<theme>/` is a symlink (e.g. into a stow/chezmoi-managed dotfiles repo), `omarchy theme bg next` always selects the alphabetically first image and never advances. The same index lookup in `omarchy-theme-set` (`choose_theme_background`) has the identical problem.
Root cause is a path-canonicalisation mismatch between two scripts:
- `bin/omarchy-theme-bg-set:12` stores the current background as `realpath "$1"`, i.e. with the symlink **resolved** (`/home/u/dotfiles/.../foo.jpg`).
- `bin/omarchy-theme-bg-next` builds the candidate list with `find -L "$HOME/.config/omarchy/backgrounds/$THEME_NAME/"`, which yields **unresolved** paths (`/home/u/.config/omarchy/backgrounds/<theme>/foo.jpg`), then does a plain string compare against `readlink` of the state symlink.
The two strings never match, so `INDEX` stays `-1` and the script falls through to `BACKGROUNDS[0]` on every invocation. The first call "works"; every call after that is a no-op.
The background switcher is unaffected because it calls `bg-set` with an explicit file. Stock theme backgrounds are unaffected because `current/theme/backgrounds/` is a real copied directory.
### Steps to reproduce
Isolated, without touching the live setup (stubs `omarchy-shell` so the wallpaper isn't actually changed):
```bash
S=$(mktemp -d)
mkdir -p "$S/home/.local/state/omarchy/current/theme/backgrounds" \
"$S/home/.config/omarchy/backgrounds" "$S/real-walls" "$S/stubs"
echo t > "$S/home/.local/state/omarchy/current/theme.name"
for f in a b c; do printf x > "$S/real-walls/$f.jpg"; done
printf '#!/bin/sh\nexit 0\n' > "$S/stubs/omarchy-shell"
cp "$S/stubs/omarchy-shell" "$S/stubs/omarchy-notification-send"; chmod +x "$S/stubs"/*
ln -s "$S/real-walls" "$S/home/.config/omarchy/backgrounds/t"
for i in 1 2 3 4; do
HOME="$S/home" PATH="$S/stubs:$PATH" omarchy-theme-bg-next
readlink "$S/home/.local/state/omarchy/current/background"
done
```
Or on a real install: `ln -s ~/Pictures/walls ~/.config/omarchy/backgrounds/catppuccin`, run `omarchy theme bg next` a few times, watch `omarchy theme bg current`.
**Expected:** cycles `a.jpg → b.jpg → c.jpg → a.jpg`, as it does when the directory is real (verified with `cp -r` in place of `ln -s`).
**Actual:** `a.jpg` four times.
### Suggested fix
Compare canonical paths on both sides, in `bg-next` and in `choose_theme_background`:
```bash
CURRENT_BACKGROUND=$(readlink -f "$CURRENT_BACKGROUND_LINK")
...
if [[ $(realpath "${BACKGROUNDS[$i]}") == "$CURRENT_BACKGROUND" ]]; then
```
Alternatively drop `realpath` from `bg-set` — but resolving on the comparison side is more robust (also covers `bg set` with a relative path).
Related but distinct: #7668 (`choose_theme_background` fails the same lookup on theme switch, for a different reason). Both would benefit from a canonical-path comparison.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 09:30 UTC