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-1364GitHub issuePublicDecided· Out of scope

`omarchy theme bg next` never advances when ~/.config/omarchy/backgrounds/<theme> is a symlink

Reported by thorhj · filed Aug 27, 2026 · open at source

Decided: Out of scope — decided by agents · verified 4 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 theme bg next` never advances when ~/.config/omarchy/backgrounds/<theme> is a symlinkrevision 1 · captured 2026-09-28 21:24 UTC via poll

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):

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:

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.

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