Skip to content

Restart the shell when plugin reload can't clear the QML component cache - #9606

Closed
aTotland wants to merge 4 commits into
omacom:quattrofrom
aTotland:fix/plugin-hot-reload-stale-qml-cache
Closed

aTotland wants to merge 4 commits into
omacom:quattrofrom
aTotland:fix/plugin-hot-reload-stale-qml-cache

Conversation

@aTotland

@aTotland aTotland commented Sep 1, 2026

Copy link
Copy Markdown

Fixes #6981.

Problem

Edits to bar-widget plugin .qml under ~/.config/omarchy/plugins/ are detected (the watcher fires, the shell re-registers the plugin), but the widget keeps rendering the old compiled QML until a full omarchy restart shell.

The reload path in shell/qml/shell.qml:757 relied on:

if (typeof Qt.clearComponentCache === "function") Qt.clearComponentCache()

Qt.clearComponentCache is a C++-only method on QQmlEngine and is not exposed to the QML Qt object, so the guard is silently always false. The engine's in-memory component cache (keyed by URL, not mtime-invalidated) is never dropped, and the subsequent Qt.createComponent(url) in loadPluginWidget() returns the cached stale Component for the same URL.

Fix

When the cache cannot be cleared from QML, fall back to a supervised shell restart — the only way to force the engine to drop its compiled-component cache and recompile from source — delegating to omarchy-restart-shell so lock-client, session-environment, and no-duplicate-launch handling already implemented there is preserved.

A pluginRestartPending flag coalesces the reload so rapid saves (one save can fire several inotify events) do not pile up restarts.

Notes

This is the documented workaround made automatic: every save under ~/.config/omarchy/plugins/ now takes effect immediately (with a journal warning when a restart is used) instead of silently showing stale code.

The plugin reload path relied on Qt.clearComponentCache() to force a
recompile of edited plugin QML, but that method is C++-only
(QQmlEngine::clearComponentCache) and is not exposed on the QML `Qt`
object, so the guard was silently always false. Qt.createComponent()
then returned the stale compiled component for the plugin's unchanged
URL, and edits under ~/.config/omarchy/plugins never took effect until a
full shell restart.

When the cache can't be cleared, fall back to a supervised shell restart
via omarchy-restart-shell so the fresh engine recompiles from source.
Reference: omacom#6981
@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed on a disposable worker VM built from the Omarchy ISO (quickshell 0.3.1-1, qt6-declarative 6.11.2-1, hyprland 0.56.2-1), running this branch as the live session shell. Reviewed by Claude Opus 5 in Claude Code, with an independent second opinion from Codex at xhigh reasoning; codex can read this session's transcript, so its agreement is not guaranteed to be independent, but two of the findings below are its own and are marked as such. Nothing was pushed to your branch — the defects here are not ones I should paper over, and whether a whole-shell restart is the right answer at all is the maintainer's call.

Your premise checks out. On the worker, typeof Qt.clearComponentCache is undefined while typeof Qt.callLater is function, so the guard at finishPluginReload() really is always false. That is also the problem: the else is not a fallback, it is the only branch. Every accepted watcher event restarts the whole shell, and so does every omarchy-shell shell rescanPlugins (shell.qml:916) — which is the last thing omarchy-plugin-add, omarchy-plugin-update, omarchy-plugin-remove and omarchy-plugin-clone each do. Installing a plugin now kills and relaunches the shell.

It breaks the repo's own runtime smoke test. test/shell.d/runtime-smoke-test.sh fails at not ok - installed plugin changes reload without an explicit rescan, twice in two runs, and the failure aborts the remaining 12 assertions. Reverting only this diff on the same worker gives 14 passed, 0 failed, so the regression is this change.

The restart is not scoped to the instance that asked for it. omarchy-restart-shell resolves its target from systemctl --user show-environment, so it restarts whatever shell the session points at. That is what made the smoke test fail: the test's shell runs from /tmp/tmp.XXXX/omarchy, it hit your restart branch, and the journal shows the session shell (pid 779, running from ~/work/omarchy-pr-9606/shell) exiting "due to IPC request" and relaunching, while the test's own shell was never restarted and kept serving stale code. Anyone running a second shell from a checkout — the test harness, a fork under quickshell -p — gets their real shell killed and no fresh engine.

A save while the screen is locked drops the session lock. omarchy-restart-shell has a guard for this: it refuses when omarchy-hyprland-session-locked succeeds and omarchy-shell lock status reports .secure or .requested. Your path defeats that guard, because reloadPlugins() tears down first and decides afterwards — unloadPluginServices() has already destroyed omarchy.lock (and with it the lock IPC target) by the time the script asks. The script reads the missing answer as a dead lock client, treats it as stranded-lock recovery, and kills the shell. Measured on the worker with the session genuinely locked and secure=true, writing one file under ~/.config/omarchy/plugins/:

12:23:55.539  locked=true secure=true sessionLocked=true
12:23:55.5    WARN qml: Plugin reload: cannot clear QML component cache from QML; restarting the shell
12:23:55.5    INFO: Exiting due to IPC request.
12:23:55.812  omarchy-shell is not running
12:23:56.16   omarchy lock lock-stranded: recovering
12:23:56.231  secure=false sessionLocked=false pending=true
12:23:56.690  secure=true

Hyprland's LOCK blocker held throughout, so the desktop was not exposed — but for ~0.7s no client held the ext-session-lock, and the new shell came up through lock-stranded: recovering → requestSessionLock. That is the same path as the open SIGABRT reports (#9654, #9709, #9727, #9736, #9745), where recreating a lock surface aborts with "Tried to show lockscreen surfaces without active lock". This branch makes a plugin file changing under a locked screen — a git pull, a sync tool, a scheduled omarchy plugin update — a routine trigger for it.

If the restart does not happen, the shell stays broken for the rest of the session. The early return skips pluginRegistry.rescan(), and onScanFinished() is the only thing that clears pluginReloading and rebuilds services, panelEntries and the widget registrations that reloadPlugins() just tore down. execDetached discards the exit status, so when omarchy-restart-shell exits 1 — the lock refusal, a missing shell.qml, a failed hyprctl dispatch — nothing notices: pluginReloading and pluginRestartPending both stay true forever, so no later save retries, and the user is left with no panels, no plugin services and no plugin widgets until a manual restart.

The coalescing flag does not bound restarts. pluginRestartPending lives in the process that is about to die; the replacement starts with it false. omarchy-launch-shell's five-relaunches-in-60s budget does not apply either, since a deliberate restart exits cleanly and omarchy-restart-shell dispatches a fresh launcher with a fresh counter. Any plugin or tool that writes under ~/.config/omarchy/plugins/ after the shell starts loops without a floor — #9745 is what that looks like when it happens for a different reason.

Codex found two things I had not reasoned about. omarchy-plugin-clone allows 40 × 50ms for the new plugin to be discovered after rescanPlugins (bin/omarchy-plugin-clone:149), and its cleanup trap rm -rfs the target directory when that budget is missed (:141) — so a restart slower than two seconds makes omarchy plugin clone delete the plugin it just created. omarchy-plugin-add --enable has the same two-second discovery window at :164, without the deletion. My clone attempt on the worker finished in 111ms and won the race, so I have not reproduced the loss, only the budget.

One small thing: shell.qml:784 builds the command by concatenating literal quotes. Util.execArgv([path]) is the right call here — it needs no shell interpretation at all — and Util.qml:61 says as much.

Worth reading before you go further: #8766 replaces the same guard with Quickshell.reload(false). typeof Quickshell.reload is function on the worker and WlSessionLock inherits Reloadable, so an in-process fresh engine that keeps the lock is reachable — but bin/omarchy-launch-shell sets QS_DISABLE_FILE_WATCHER=1 for a stated reason ("a failed reload leaves a second engine generation behind that turns the next restart's IPC kill into a crash"), and #8766 is currently held on quickshell-mirror/quickshell#956. There is also a third option on #6981 from @Rockzmash: give Qt.createComponent() a unique URL per load, which never touches engine lifetime. Which of the three Omarchy wants is David's call, not mine.

Also worth rebasing: quattro has moved to d3d23fd, which makes keepLoaded services survive plugin hot-reload precisely so tearing down a bar widget cannot destroy omarchy.lock. It merges cleanly, but it changes what the teardown above does, and you will want to re-measure the lock behaviour on top of it.

@aTotland
aTotland marked this pull request as draft September 5, 2026 17:06
@aTotland
aTotland marked this pull request as ready for review September 5, 2026 18:43
@omarchybot

Copy link
Copy Markdown
Collaborator

Re-reviewed at 8c9d109d. This is a delta review against e3cbd218, the head of the last pass, so it covers only what the new commit changed.

8c9d109d makes shell/shell.qml unparseable, and the Omarchy shell does not start at all.

The commit deleted the else branch and, with it, the closing brace of finishPluginReload(). At head, the function opens at shell/shell.qml:774, the if at :780 is closed by the } at :783, and :786–:790 define and close restartShellForPluginReload — so finishPluginReload's own body is never closed and swallows the Connections { declaration at :792 as JavaScript. The file is one { short overall (218 open, 217 close).

Measured on a disposable worker built from the Omarchy ISO, with the branch linked in as the live session tree:

omarchy-shell[781]: INFO: Launching config: ".../omarchy-pr-9606/shell/shell.qml"
omarchy-shell[781]: ERROR: Failed to load configuration
omarchy-shell[781]: ERROR:   caused by @shell.qml[792:15]: Expected token `,'
...
omarchy-shell[1251]: Giving up on the Omarchy shell after 6 relaunches in under a minute.

omarchy-launch-shell's five-in-sixty-seconds budget is exhausted in six seconds at login, before any plugin is touched, and pgrep -af quickshell then returns nothing: no bar, no menu, no OSD, no lock client. qmllint agrees with the runtime and isolates it to exactly that brace — 1 [syntax] error on the file as it stands, 0 after inserting a single } after line 783, nothing else changed.

Worth saying why nothing caught this: plugins-test.sh (2/0) and plugin-registry-contract-test.sh (1/0) still pass on this branch, because they read shell.qml as text and never parse it. runtime-smoke-test.sh is the only test that loads it, and it went from 1 passed / 1 failed at e3cbd218 to 0 passed / 1 failed here, with the same parse error in its log. On a machine without quickshell that test reports pass and skips, so a green local run does not mean the shell loads.

Below the parse error, three things in the same commit would still need fixing once it does parse. None is reachable today, so none is verified live:

  1. typeof restartShellForPluginReload === "function" at :780 can never be false. It is declared on the same object at :786. The old code guarded on Qt.clearComponentCache, which really is absent from the QML Qt object — that check meant something. This one is always true, so the restart is now the only path, unconditionally, on every accepted inotify event and every omarchy-shell shell rescanPlugins (:921) — which is the last thing omarchy-plugin-add, -update, -remove and -clone each do.
  2. Reusing pluginReloadPending as the restart's coalescing flag conflates two different states. It replaced the dedicated pluginRestartPending property that e3cbd218 had. It is written for "a reload is queued" at :764 and :777, read as "a restart is already in flight" at :787, and read again as "another reload was queued" at :799. That breaks both ways. A reload queued at :764 makes :787 suppress the restart. Worse, the restart path sets the flag at :788 and then :782 immediately calls rescan() — so if onScanFinished fires before the process actually dies, :799 reads the in-flight restart as a queued reload, clears the flag at :800, and calls reloadPlugins() again, which restarts again with the guard now open. That is a self-sustaining restart loop within one process lifetime. It has no floor when the restart cannot complete: omarchy-restart-shell:29-35 refuses while the session is locked, Util.execDetached discards the exit status, so nothing notices and the cycle repeats.
  3. Qt.clearComponentCache() is gone entirely. On any path where the restart is suppressed or refused, :782 rescans in the same engine and services and widgets are rebuilt from unchanged URLs at :294 and :826 — the original stale-cache bug, unchanged.

Two things that did improve since the last pass, both from merging quattro in rather than from the new commit. d3d23fdd (#9485) is now in the base, so unloadPluginServices() at :366-377 preserves keepLoaded services, which means omarchy.lock survives the teardown and omarchy-restart-shell's lock guard gets a real answer instead of a missing one. The lock-drop finding from the last review no longer holds on this base — the failure mode there becomes the refusal loop in point 2 instead. And the rebase request from the last review is answered.

On @h3nr1-d14z's corroboration on #6981 that service-kind plugins are affected too: confirmed in source. Services load through Qt.createComponent() at shell.qml:294, the same unchanging-URL path as widgets at :826, so they hit the identical stale cache. A full process restart is the one approach that also covers keepLoaded services (lock, idle, polkit) — those are deliberately never torn down at :369-371, so no in-process reload can pick up an edit to them at all. That is a genuine coverage advantage of this PR's approach over #8766's Quickshell.reload(false), and it is worth stating even though this revision cannot realise it.

Suggestion, for whatever it is worth: revert 8c9d109d rather than patch it. e3cbd218 parsed, kept a separate pluginRestartPending, and kept the Qt.clearComponentCache guard. The findings against it were about the design of a whole-shell restart, not about it being broken — and this commit trades all three of those properties away without answering any of them. I did not push a fix: adding the one brace would turn "no shell at all" into "restart loop", which is not an improvement I should make on your behalf.

Reviewed by Claude Opus 5 in Claude Code, with an independent second opinion from Codex at xhigh reasoning. Codex reached the parse failure, the always-true predicate, the flag aliasing and the missing cache call on its own read of the tree at 8c9d109d, with line numbers that match the file; its independence is not currently guaranteed, since it can read this session's transcript. One thing was genuinely its own: the onScanFinished direction of the flag aliasing in point 2 above — that a successful restart's flag is consumed at :799 as a queued reload, which is what closes the loop. I had only reasoned about the suppression direction. I verified it against the source before writing it here.

Nothing was pushed to your branch. This is waiting on you for the parse error, and on the maintainer for the choice between this approach and #8766.

@aTotland aTotland closed this Sep 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Plugin hot-reload never picks up changed plugin code (stale QML component cache)

2 participants