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.
4.0.3: PluginShellApi drops shellConfig, breaking third-party panel/overlay/menu plugins' own settings reads
Reported by tonyfarson · filed Sep 10, 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
Version: omarchy 4.0.2 → 4.0.3 (2026-09-10 update)
4.0.3 replaces the raw shell object injected into third-partypanel/overlay/menu plugins with a new capability-scopedPluginShellApi (shell/services/PluginShellApi.qml), viashell.qml's pluginShellFor(manifest):
// 4.0.2, shell/shell.qml
if ("shell" in target) target.shell = shell
// 4.0.3, shell/shell.qml
if ("shell" in target) target.shell = shell.pluginShellFor(manifest)PluginShellApi exposes appLibrary, bar, barConfig, idleConfig, and a
few write-only callbacks (updateEntryInline, mutateShellConfig) — but noshellConfig. Any third-party plugin that reads its own entry out ofshell.json's plugins[] via shell.shellConfig.plugins (the documented,
working pattern under 4.0.2) now silently gets undefined back, with no
error. The plugin doesn't crash — it just stops seeing any of its own
persisted settings.
Hit this with a user-installed dock plugin (bogdart/omarchy-minimizable-dock,kinds: ["panel"]) after today's update: pinned apps, icon color, and every
other shell.json-backed setting silently reset to defaults on every reload,
with no warning anywhere. Confirmed by diffing the actual shell.qml shipped
in the omarchy-4.0.2 and omarchy-4.0.3 packages, and by instrumenting the
plugin to log what it receives — shell.shellConfig is undefined, every
time, post-4.0.3.
Worked around it locally by having the plugin read ~/.config/omarchy/shell.json
directly via its own FileView rather than going through shell.shellConfig —
but that's a plugin-side patch, and every third-party panel/overlay/menu
plugin that relied on the old contract is presumably silently broken the same
way right now, with nothing in the changelog to flag it.
Ask: either restore read access to a plugin's own shell.json entry
through PluginShellApi (a narrow settings/getEntry() accessor mirroring
the existing updateEntryInline write path would do it), or, if the removal
was deliberate, document the new contract so plugin authors know they need to
read their own config another way now.
View raw text
**Version:** `omarchy` 4.0.2 → 4.0.3 (2026-09-10 update)
`4.0.3` replaces the raw shell object injected into third-party
`panel`/`overlay`/`menu` plugins with a new capability-scoped
`PluginShellApi` (`shell/services/PluginShellApi.qml`), via
`shell.qml`'s `pluginShellFor(manifest)`:
```qml
// 4.0.2, shell/shell.qml
if ("shell" in target) target.shell = shell
// 4.0.3, shell/shell.qml
if ("shell" in target) target.shell = shell.pluginShellFor(manifest)
```
`PluginShellApi` exposes `appLibrary`, `bar`, `barConfig`, `idleConfig`, and a
few write-only callbacks (`updateEntryInline`, `mutateShellConfig`) — but no
`shellConfig`. Any third-party plugin that reads its own entry out of
`shell.json`'s `plugins[]` via `shell.shellConfig.plugins` (the documented,
working pattern under 4.0.2) now silently gets `undefined` back, with no
error. The plugin doesn't crash — it just stops seeing any of its own
persisted settings.
Hit this with a user-installed dock plugin (`bogdart/omarchy-minimizable-dock`,
`kinds: ["panel"]`) after today's update: pinned apps, icon color, and every
other `shell.json`-backed setting silently reset to defaults on every reload,
with no warning anywhere. Confirmed by diffing the actual `shell.qml` shipped
in the `omarchy-4.0.2` and `omarchy-4.0.3` packages, and by instrumenting the
plugin to log what it receives — `shell.shellConfig` is `undefined`, every
time, post-4.0.3.
Worked around it locally by having the plugin read `~/.config/omarchy/shell.json`
directly via its own `FileView` rather than going through `shell.shellConfig` —
but that's a plugin-side patch, and every third-party panel/overlay/menu
plugin that relied on the old contract is presumably silently broken the same
way right now, with nothing in the changelog to flag it.
**Ask:** either restore read access to a plugin's own `shell.json` entry
through `PluginShellApi` (a narrow `settings`/`getEntry()` accessor mirroring
the existing `updateEntryInline` write path would do it), or, if the removal
was deliberate, document the new contract so plugin authors know they need to
read their own config another way now.
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 11:38 UTC