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

`omarchy debug` is advertised in `--help` but not routable (packaged in `/usr/bin` instead of the scanned bin dir)

Reported by aimonkeymind · filed Oct 2, 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 debug` is advertised in `--help` but not routable (packaged in `/usr/bin` instead of the scanned bin dir)revision 1 · captured 2026-10-02 02:38 UTC via poll

omarchy debug is advertised in --help but not routable (packaged in /usr/bin instead of the scanned bin dir)

Summary

omarchy --help lists omarchy debug under "Common commands", but invoking it
fails:

$ omarchy debug
Unknown Omarchy command: omarchy debug
Run 'omarchy commands --all' to discover available commands.
$ omarchy debug --no-sudo --print
Unknown Omarchy command: omarchy debug --no-sudo --print
$ omarchy debug --help
Unknown Omarchy command: omarchy debug --help

The binary exists and works when called directly, which is what the bundled
Omarchy skill documentation tells users to do as a workaround.

Cause

The resolver only scans the directory that the omarchy script itself lives in:

OMARCHY_BIN_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
...
for file in "$OMARCHY_BIN_DIR"/omarchy-*; do

On this system that resolves to /usr/share/omarchy/bin, and every
omarchy-* binary is there except one:

$ ls -la /usr/share/omarchy/bin/omarchy-debug
ls: cannot access '/usr/share/omarchy/bin/omarchy-debug': No such file or directory

$ ls -la /usr/bin/omarchy-debug
-rwxr-xr-x 1 root root 2269 Sep 16 09:04 /usr/bin/omarchy-debug

$ command -v omarchy
/usr/share/omarchy/bin/omarchy

So /usr/bin/omarchy-debug is invisible to the resolver. The packaging is
inconsistent in general: even /usr/bin/omarchy is only a symlink to
/usr/share/omarchy/bin/omarchy, and /usr/bin/omarchy-debug is a real file.

Meanwhile the help text hardcodes the route regardless:

$ grep -n 'omarchy debug' /usr/share/omarchy/bin/omarchy
532:  omarchy debug               Print debugging information

The annotation inside the binary is correct, so nothing is wrong with the
command itself:

# omarchy:summary=Print debugging information
# omarchy:args=[--no-sudo] [--print]
# omarchy:examples=omarchy debug --print --no-sudo
# omarchy:requires-sudo=true

Impact

This is the command used to collect diagnostics for bug reports, so it is
exactly the command a user needs when something is broken and cannot find.
Following the bundled skill documentation (omarchy debug --no-sudo --print)
produces a confusing "Unknown Omarchy command" rather than a log.

It also means omarchy commands --all and omarchy commands --json omit
debug entirely, so the discovery path advertised in the error message does not
list it either.

Steps to reproduce

  1. omarchy --help and observe omarchy debug listed under Common commands.
  2. omarchy debug and observe Unknown Omarchy command.
  3. omarchy commands --all | grep debug and observe no omarchy debug route.
  4. /usr/bin/omarchy-debug --no-sudo --print and observe it works.

Suggested change

Install omarchy-debug into /usr/share/omarchy/bin like every other
omarchy-* binary, or teach the resolver to also scan /usr/bin.

System

  • Omarchy 4.0.4-1
  • kernel 7.2.5-3-omarchy
  • Hyprland 0.56.2-2, quickshell 0.3.1-1
  • Lenovo B340 AIO, Intel Celeron G1610, NVIDIA GeForce 610M (nouveau)
View raw text
# `omarchy debug` is advertised in `--help` but not routable (packaged in `/usr/bin` instead of the scanned bin dir)

## Summary

`omarchy --help` lists `omarchy debug` under "Common commands", but invoking it
fails:

```
$ omarchy debug
Unknown Omarchy command: omarchy debug
Run 'omarchy commands --all' to discover available commands.
$ omarchy debug --no-sudo --print
Unknown Omarchy command: omarchy debug --no-sudo --print
$ omarchy debug --help
Unknown Omarchy command: omarchy debug --help
```

The binary exists and works when called directly, which is what the bundled
Omarchy skill documentation tells users to do as a workaround.

## Cause

The resolver only scans the directory that the `omarchy` script itself lives in:

```bash
OMARCHY_BIN_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
...
for file in "$OMARCHY_BIN_DIR"/omarchy-*; do
```

On this system that resolves to `/usr/share/omarchy/bin`, and every
`omarchy-*` binary is there except one:

```
$ ls -la /usr/share/omarchy/bin/omarchy-debug
ls: cannot access '/usr/share/omarchy/bin/omarchy-debug': No such file or directory

$ ls -la /usr/bin/omarchy-debug
-rwxr-xr-x 1 root root 2269 Sep 16 09:04 /usr/bin/omarchy-debug

$ command -v omarchy
/usr/share/omarchy/bin/omarchy
```

So `/usr/bin/omarchy-debug` is invisible to the resolver. The packaging is
inconsistent in general: even `/usr/bin/omarchy` is only a symlink to
`/usr/share/omarchy/bin/omarchy`, and `/usr/bin/omarchy-debug` is a real file.

Meanwhile the help text hardcodes the route regardless:

```
$ grep -n 'omarchy debug' /usr/share/omarchy/bin/omarchy
532:  omarchy debug               Print debugging information
```

The annotation inside the binary is correct, so nothing is wrong with the
command itself:

```bash
# omarchy:summary=Print debugging information
# omarchy:args=[--no-sudo] [--print]
# omarchy:examples=omarchy debug --print --no-sudo
# omarchy:requires-sudo=true
```

## Impact

This is the command used to collect diagnostics for bug reports, so it is
exactly the command a user needs when something is broken and cannot find.
Following the bundled skill documentation (`omarchy debug --no-sudo --print`)
produces a confusing "Unknown Omarchy command" rather than a log.

It also means `omarchy commands --all` and `omarchy commands --json` omit
`debug` entirely, so the discovery path advertised in the error message does not
list it either.

## Steps to reproduce

1. `omarchy --help` and observe `omarchy debug` listed under Common commands.
2. `omarchy debug` and observe `Unknown Omarchy command`.
3. `omarchy commands --all | grep debug` and observe no `omarchy debug` route.
4. `/usr/bin/omarchy-debug --no-sudo --print` and observe it works.

## Suggested change

Install `omarchy-debug` into `/usr/share/omarchy/bin` like every other
`omarchy-*` binary, or teach the resolver to also scan `/usr/bin`.

## System

- Omarchy `4.0.4-1`
- kernel `7.2.5-3-omarchy`
- Hyprland `0.56.2-2`, quickshell `0.3.1-1`
- Lenovo B340 AIO, Intel Celeron G1610, NVIDIA GeForce 610M (nouveau)

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 20:36 UTC