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

omarchy-install-ai-hermes never writes the Hermes Desktop bootstrap marker, so the theme-sync/readiness check gets stuck

Reported by rootjmo · filed Sep 16, 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-install-ai-hermes never writes the Hermes Desktop bootstrap marker, so the theme-sync/readiness check gets stuckrevision 1 · captured 2026-09-28 21:23 UTC via poll

What happened

After installing Hermes Desktop via omarchy install ai hermes, Omarchy's own readiness probe for Hermes (omarchy-install-hermes-cli --check → desktop_hermes_ready()) never passes, even though the install is fully functional (hermes chat --help works fine, the CLI wrapper is correctly pointed at ~/.hermes).

The practical symptom: omarchy-theme-set-hermes --activate — including the one-shot migration 1788619462.sh ("Hand Hermes Desktop the Omarchy theme as a skin") that's supposed to backfill this on update — permanently reports:

Hermes is not ready, so the Omarchy skin is published but not active.
Once Hermes runs, activate it with: hermes config set display.skin omarchy

Since that migration only runs once, this leaves the theme→Hermes skin sync silently broken forever on any machine where it hits this path, with no automatic recovery.

Root cause

desktop_hermes_ready() in omarchy-install-hermes-cli requires this file to exist:

[[ -f $HOME/.hermes/hermes-agent/.hermes-bootstrap-complete ]] || return 1

That marker is normally written by Hermes Desktop's Electron bootstrap flow (apps/desktop/electron/main.ts, writeBootstrapMarker()), at the end of its first-run bootstrap wizard.

But omarchy-install-ai-hermes (/usr/share/omarchy/bin/omarchy-install-ai-hermes) provisions the runtime via:

bash /usr/share/hermes-desktop/install.sh --skip-setup --branch main --commit "$release_commit" --force-commit --dir "$runtime" --hermes-home "$HERMES_HOME"

This headless path reconstructs the same repo+venv layout the Electron bootstrap wizard would produce, but never goes through bootstrap-runner.ts, so .hermes-bootstrap-complete never gets written. Hermes Desktop itself handles this gracefully by design (apps/desktop/electron/active-runtime-state.ts — classifyActiveRuntime() explicitly treats a missing/stale marker as fine as long as the runtime is otherwise usable, logging "...usable but the bootstrap marker is missing or stale; skipping first-run bootstrap." and launching it directly). So this isn't a Hermes Desktop bug — it's that Omarchy's own readiness probe relies on a marker that Omarchy's own install path never produces.

A comment in bootstrap-runner.ts ("Prefer a real pin already written by install.ps1's bootstrap-marker stage") suggests the Windows installer (install.ps1) does write an equivalent marker as part of its scripted install — so this looks like a Linux/install.sh --skip-setup gap relative to install.ps1, or something omarchy-install-ai-hermes needs to write itself after calling install.sh.

Expected

omarchy install ai hermes should leave the install in a state where omarchy-install-hermes-cli --check succeeds (and therefore omarchy-theme-set-hermes --activate / the one-shot migration succeeds) without a manual step.

Steps to reproduce

  1. omarchy install ai hermes on a machine that doesn't already have Hermes set up.
  2. Let it finish and launch.
  3. Run omarchy-theme-set-hermes --activate (or just switch themes and wait for the next Omarchy update to run migration 1788619462.sh).
  4. Observe: "Hermes is not ready, so the Omarchy skin is published but not active." — even though Hermes is fully installed and running.
  5. Check: ~/.hermes/hermes-agent/.hermes-bootstrap-complete does not exist.

Workaround

Manually run hermes config set display.skin omarchy after each theme change, or write a marker file matching the schema in writeBootstrapMarker() ({schemaVersion: 1, pinnedCommit: <current HEAD sha, >=7 hex chars>, pinnedBranch, completedAt, desktopVersion}) at ~/.hermes/hermes-agent/.hermes-bootstrap-complete.

System details

  • Omarchy version: 4.0.4-1
  • hermes-desktop package: 2026.8.31-3 (Hermes Agent v0.21.3 / v2026.9.14)
  • CPU: Intel(R) Core(TM) i5-6300U CPU @ 2.40GHz
  • GPU: Intel Corporation Skylake-U GT2 [HD Graphics 520]
View raw text
## What happened

After installing Hermes Desktop via `omarchy install ai hermes`, Omarchy's own readiness probe for Hermes (`omarchy-install-hermes-cli --check` → `desktop_hermes_ready()`) never passes, even though the install is fully functional (`hermes chat --help` works fine, the CLI wrapper is correctly pointed at `~/.hermes`).

The practical symptom: `omarchy-theme-set-hermes --activate` — including the one-shot migration `1788619462.sh` ("Hand Hermes Desktop the Omarchy theme as a skin") that's supposed to backfill this on update — permanently reports:

```
Hermes is not ready, so the Omarchy skin is published but not active.
Once Hermes runs, activate it with: hermes config set display.skin omarchy
```

Since that migration only runs once, this leaves the theme→Hermes skin sync silently broken forever on any machine where it hits this path, with no automatic recovery.

## Root cause

`desktop_hermes_ready()` in `omarchy-install-hermes-cli` requires this file to exist:

```
[[ -f $HOME/.hermes/hermes-agent/.hermes-bootstrap-complete ]] || return 1
```

That marker is normally written by Hermes Desktop's Electron bootstrap flow (`apps/desktop/electron/main.ts`, `writeBootstrapMarker()`), at the end of its **first-run bootstrap wizard**.

But `omarchy-install-ai-hermes` (`/usr/share/omarchy/bin/omarchy-install-ai-hermes`) provisions the runtime via:

```bash
bash /usr/share/hermes-desktop/install.sh --skip-setup --branch main --commit "$release_commit" --force-commit --dir "$runtime" --hermes-home "$HERMES_HOME"
```

This headless path reconstructs the same repo+venv layout the Electron bootstrap wizard would produce, but never goes through `bootstrap-runner.ts`, so `.hermes-bootstrap-complete` never gets written. Hermes Desktop itself handles this gracefully by design (`apps/desktop/electron/active-runtime-state.ts` — `classifyActiveRuntime()` explicitly treats a missing/stale marker as fine as long as the runtime is otherwise usable, logging `"...usable but the bootstrap marker is missing or stale; skipping first-run bootstrap."` and launching it directly). So this isn't a Hermes Desktop bug — it's that Omarchy's own readiness probe relies on a marker that Omarchy's own install path never produces.

A comment in `bootstrap-runner.ts` ("Prefer a real pin already written by install.ps1's bootstrap-marker stage") suggests the Windows installer (`install.ps1`) *does* write an equivalent marker as part of its scripted install — so this looks like a Linux/`install.sh --skip-setup` gap relative to `install.ps1`, or something `omarchy-install-ai-hermes` needs to write itself after calling `install.sh`.

## Expected

`omarchy install ai hermes` should leave the install in a state where `omarchy-install-hermes-cli --check` succeeds (and therefore `omarchy-theme-set-hermes --activate` / the one-shot migration succeeds) without a manual step.

## Steps to reproduce

1. `omarchy install ai hermes` on a machine that doesn't already have Hermes set up.
2. Let it finish and launch.
3. Run `omarchy-theme-set-hermes --activate` (or just switch themes and wait for the next Omarchy update to run migration `1788619462.sh`).
4. Observe: "Hermes is not ready, so the Omarchy skin is published but not active." — even though Hermes is fully installed and running.
5. Check: `~/.hermes/hermes-agent/.hermes-bootstrap-complete` does not exist.

## Workaround

Manually run `hermes config set display.skin omarchy` after each theme change, or write a marker file matching the schema in `writeBootstrapMarker()` (`{schemaVersion: 1, pinnedCommit: <current HEAD sha, >=7 hex chars>, pinnedBranch, completedAt, desktopVersion}`) at `~/.hermes/hermes-agent/.hermes-bootstrap-complete`.

## System details

- Omarchy version: 4.0.4-1
- `hermes-desktop` package: 2026.8.31-3 (Hermes Agent v0.21.3 / v2026.9.14)
- CPU: Intel(R) Core(TM) i5-6300U CPU @ 2.40GHz
- GPU: Intel Corporation Skylake-U GT2 [HD Graphics 520]

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

  • Related PRpr/12836· 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 14:37 UTC