Skip to content

Reload shell safely when local plugin sources change - #11408

Open
thelonewander3r wants to merge 9 commits into
omacom:quattrofrom
thelonewander3r:fix/plugin-qml-hot-reload
Open

thelonewander3r wants to merge 9 commits into
omacom:quattrofrom
thelonewander3r:fix/plugin-qml-hot-reload

Conversation

@thelonewander3r

@thelonewander3r thelonewander3r commented Sep 12, 2026 •

Copy link
Copy Markdown

Local plugin source edits now trigger a debounced Quickshell.reload(false) so compiled QML and imported JavaScript refresh. .qml, .js, .mjs, and qmldir count as source changes; other files retain the registry-only rescan.

Source reloads stay queued while any private authentication service holds a lock, then reload once after unlock. This avoids tearing down an active WlSessionLock on a source edit. The lock query returns only a boolean and preserves the private authentication object boundary.

The unreachable Qt.clearComponentCache guard is removed. Focused behavioral tests execute the real JavaScript classifier, lock store, and reload decision rather than matching source text.

Validation on macOS:

  • bash -n test/shell.d/plugin-hot-reload-test.sh
  • bash test/shell.d/plugin-hot-reload-test.sh: all 16 assertions pass.
  • bash test/shell.d/plugin-auth-boundary-test.sh: static checks pass; compositor runtime test skips.
  • git diff --check: clean.

Live locked/unlocked Quickshell verification still needs an Omarchy VM. The reported upstream teardown use-after-free remains outside this patch.

Fixes #11397
Fixes #6981

@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed at 40a195e, run on a disposable worker VM built from the Omarchy ISO. The shell was served from this branch merged into current quattro (821ae58), which merges cleanly.

The fix works for what it targets. I used a local service plugin with a sibling Helper.qml that writes its own version to a file each time it loads. On quattro, editing the entry file and then the helper re-created the plugin both times, but it still ran the old code. With this branch, it picked up both edits. The branch changes nothing else apart from the new test, so with the fix reverted the tree is quattro. I have linked #6981, which this fixes for the file-watcher path. 40 rapid edits at random intervals gave 28 soft reloads, with no crash and no core dump. That does not rule out quickshell-mirror/quickshell#956, the use-after-free at generation teardown raised on #8766. That crash depends on timing, and Arch still ships quickshell 0.3.1-1.

One blocking finding. If a local plugin's QML changes while the session is locked, the lock screen dies. Quickshell.reload(false) in shell/shell.qml rebuilds the whole engine generation, and that includes the WlSessionLock in omarchy.lock. On quattro, that service is keepLoaded and survives a plugin reload. I locked the worker with omarchy-shell lock lock, confirmed the lock was held, and edited the plugin. On this branch, both runs ended on Hyprland's "the lockscreen app died" screen: the session stayed locked, and the only way out is from another TTY. On quattro, the same edit left the password prompt in place. This can happen without anyone at the keyboard: omarchy plugin update run over ssh, or a plugin directory synced from another machine.

Two smaller gaps, found by reading the code. localPluginQmlChangedForPath matches only .qml, so editing a plugin's imported .js file or its qmldir still goes through the cached rescan and stays stale. And the new plugin-hot-reload-test.sh checks the source text rather than exercising a reload.

Tests on the worker: plugin-registry-contract-test passes 1 of 1 and runtime-smoke-test passes 20 of 20. plugin-hot-reload-test and plugin-auth-boundary-test could not run, because the worker has no node. ./test/cli has one failure, vscode generated theme references current theme file, which is in code this PR does not touch. Nothing was pushed: how a soft reload should coexist with keepLoaded services is a design choice, not a contained defect fix.

Related: #8766 takes the same Quickshell.reload(false) route and is waiting on its author. #10576 busts entry-file URLs, and its review recommended this PR over it. #7259 handles omarchy plugin update/remove separately. #12189 narrows which writes reload at all, and touches the same watcher in PluginRegistry.qml.

Only one model reviewed this, Claude Opus 5.5. The configured second opinion, Codex Medium, answered a ping but did not run, because today's review budget was spent.

Next step is yours: keep the soft reload from taking down the lock screen, for example by not reloading while the session is locked. Whether this should also wait for a Quickshell build that carries the upstream teardown fix is the maintainer's call.

@greptile-apps

greptile-apps Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 3/5

[Medium impact] The change affects how the shell refreshes loaded local plugins.

Changes are needed before merging: source reloads can run before update checks finish, and the multiple-screen smoke-test failure remains.

Findings

  1. P1 Rejected updates can run ▶
  2. P1 Multiple screens fail the test ▶
  3. P2 Tests break the placement rule ▶
  4. P2 Locked sessions keep waking ▶

Summary

Local plugin source edits now request a debounced shell reload so QML and imported JavaScript refresh.

  • Loaded local plugin source edits now refresh the shell engine.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Local plugin file event] --> B{Source file?}
  B -->|Yes, installed plugin| C[Queue shell reload]
  B -->|No| D[Queue plugin reload or rescan]
  C --> E[Wait for quiet period]
  E --> F{Private lock active?}
  F -->|Yes| G[Retry after one second]
  G --> F
  F -->|No| H[Reload shell]
  D --> I[Reload plugins or rescan registry]
Loading

Reviews (5) · Last reviewed commit: "Read the lock through currentlyLocked() ..." · Reviewed by Greptile

Comment thread test/shell.d/plugin-hot-reload-test.sh Resolved
@thelonewander3r

Copy link
Copy Markdown
Author

Addressed the locked-session reload issue in 5e3a40dc. Source edits now stay queued while any private authentication service reports an active lock; the timer retries until unlock, then performs the soft reload once. The lock check returns only a boolean and keeps the authentication QObjects private.

The source classifier now includes .qml, .js, .mjs, and qmldir. I replaced the source-text assertions with tests that execute the real JavaScript classifier, lock store, and reload decision, including repeated lock deferrals, an authentication clone holding the lock, and exactly one reload after unlock.

bash -n test/shell.d/plugin-hot-reload-test.sh
bash test/shell.d/plugin-hot-reload-test.sh
bash test/shell.d/plugin-auth-boundary-test.sh

All 16 hot-reload assertions and the authentication-boundary static checks pass. The compositor runtime portion skips on this macOS host. I have not rerun the locked/unlocked Quickshell VM scenario, so that runtime verification remains needed; the reported upstream teardown use-after-free is also outside this fix.

@thelonewander3r thelonewander3r changed the title Reload shell when local plugin QML changes Reload shell safely when local plugin sources change Oct 2, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

Thanks for the two pushes, 5e3a40d and 26ee2ef, which answer the locked-session finding and the .js/qmldir gap from the last review. This run has not re-reviewed them yet. Every pull request here is classified and reviewed by two models, and today the configured second opinion, Codex Medium, had already used up its daily review budget. It answered a ping but did not run, so this head has not been classified, and nothing was run on a worker.

Only one model, Claude Opus 5.5, looked at this run, and it only read the diff of 5e3a40d. It has no findings to report from that reading. The locked-session reload and the new source classifier still need the worker run your comment asks for. That re-review, with the second opinion, happens on a later run. Until then this waits on that run, not on you.

Comment thread test/shell.d/runtime-smoke-test.sh Resolved
@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed at 4b5bfb2, merged into current quattro (84cfb93) with no conflicts, and run on a disposable worker VM built from the Omarchy ISO.

The fix works, and the locked-session finding from the last review is fixed. Your new runtime test fails on quattro for the reason the bug gives: after the QML edit it still reads qml-before. On this branch it passes, for the QML edit and for the edit to the imported Model.js. With the fix reverted the tree is quattro, so it fails again. Then I locked the live session with omarchy-shell lock lock and saved a local plugin's QML three times. The lock held, the shell was still the same process, and nothing reloaded. On unlock the queued reload ran exactly once. The session then locked and unlocked normally, with no core dumps.

One blocking finding: an open polkit prompt is torn down by a source edit. AuthServiceStore.hasActiveLock() (shell/services/AuthServiceStore.js:48) only checks .locked. The polkit agent is also an authentication service, and it has no locked property. On the worker I started pkexec /usr/bin/true from the session and, with the password prompt on screen, saved a local plugin's Panel.qml. The engine reloaded, the prompt disappeared, and pkexec exited 126. On quattro the same edit only rescans, and the keepLoaded polkit agent survives.

I tried the obvious fix: also defer while any authentication service has dialogVisible === true. It works in the live session: the prompt survived the edit, pkexec succeeded once answered, and the reload ran once afterwards. But it turns runtime-smoke-test.sh red on the worker. The test opens the network panel, NetworkManager asks polkit for network-control, and the test shell's agent takes that request and shows a prompt nobody answers. The queued reload then waits behind it and the qml-after check times out. So the guard needs a decision about how a prompt left open holds a reload, and the test needs a decision about isolating polkit. Both are yours, so I haven't pushed anything. While you are in there: the lock service says to read it through currentlyLocked() (shell/plugins/lock/Service.qml:77), because its bound locked property once missed a change notification. The guard should read the lock the same way.

Tests on the worker: runtime-smoke-test passes 24 of 24. plugin-hot-reload-test passes 16 of 16 and plugin-auth-boundary-test 13 of 13; both need node, which I installed on the worker. The rest of the plugin-* and lock-* files in test/shell.d and ./test/cli all pass.

Competing fixes for #6981: this is the one I'm recommending over #8766, #10576 and #13911. #8766 is older, but it does an engine reload on every rescan, with no lock guard. #10576 and #13911 version only the entry-point URL, so a sibling Helper.qml or an imported .js stays cached. This branch's runtime test covers that case, and it passes here and fails on quattro. #7259 handles omarchy plugin update and remove, and #12189 narrows which writes reach the watcher. Both are separate changes to the same area.

Codex Medium reviewed this separately and found the polkit gap and the currentlyLocked() point. I reproduced the polkit gap on the worker as above; the currentlyLocked() point comes from reading the lock service. It also chose this pull request over the other three, for the same reasons. It can read this session's notes, so that agreement is not guaranteed independent.

Next step is yours: keep a source reload from taking down an open polkit prompt, in a way the runtime smoke test can still pass.

@paulogeyer

Copy link
Copy Markdown
Contributor

I reviewed the open PRs for local plugin hot reload picking up stale code (#6981), plus an offscreen check of the cache-busting approach on my laptop.

PR approach edits to a sibling QML file reload merges cleanly
#11408 full Quickshell.reload when QML/JS changes, held while the lock is up yes yes
#13911 ?v=N query on the plugin's entry URL fail: in my check the entry file reloaded but a component it imports stayed stale yes
#7771, #8766 no (conflicts)

I'd go with #11408. Reloading the engine is the only way to drop Qt's component cache for every file in a plugin. It holds the reload while the lock screen is up, and for edits that aren't code it keeps the cheap plugin reload. #13911, #7771 and #8766 duplicate it. #13911 also adds a new cache entry on every reload.

Suggestion for #11408: a full reload resets every panel's state, so a short debounce for edits that come in bursts (an omarchy plugin update writes many files) would avoid several reloads in a row.

thelonewander3r and others added 2 commits November 3, 2026 07:06
…shell

quattro runs the runtime smoke test on base-test.sh's scratch shell
(83f0400), so the source-version probe uses scratch_ipc and SCRATCH_PID.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`omarchy plugin update` fast-forwards, validates, and resets when
validation fails. With a 150ms quiet window a slow validation let the
shell reload onto the rejected code and again after the reset, and a
full reload resets every panel. Source edits now wait 500ms after the
last watcher event; registry-only rescans keep 150ms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment on lines +441 to +446
sed -i 's/qml-before/qml-after/' "$hot_reload_dir/Overlay.qml"
wait_source_version "qml-after:js-before"
pass "QML edits refresh the mounted plugin through the live watcher and shell reload"

sed -i 's/js-before/js-after/' "$hot_reload_dir/Model.js"
wait_source_version "qml-after:js-after"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Multiple screens fail the test

These source-edit checks reload the shell twice before the later duplicate-handler check reads the entire SCRATCH_LOG. With multiple screens, each shell load adds the expected per-screen handler collisions again. The combined count exceeds screens - 1, so a healthy shell fails the smoke test. Move the collision check before these reloads, or count only one shell load.

Comment thread shell/shell.qml
Comment on lines +81 to +84
if (shell.localPluginQmlReloadPending) {
// Keep the edit queued until unlock without polling the idle shell.
localPluginReloadTimer.interval = 1000
localPluginReloadTimer.start()

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Locked sessions keep waking

While a source edit is queued behind a lock, localPluginReloadTimer checks the lock every second until unlock. The shell guide requires events instead of polling whenever a change signal exists. The lock service's locked property already provides lockedChanged. Connect that signal inside the private store and notify the shell without exposing the service object. This repository requirement must be met before merging.

File Used: agents/skills/shell-dev.md (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

omarchybot and others added 2 commits November 16, 2026 23:51
quattro's omacom#18198 splits the watcher's timer into a full plugin reload for a plugin the shell already runs and a gentle rescan for one that just appeared. A source edit now takes the engine reload only for a loaded plugin, so a new plugin's files arriving still only add it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The lock service's bound locked property once missed a change notification and reported locked after an unlock, which is why its own decisions read currentlyLocked(). Read that here too, so a stale value neither holds a queued reload forever nor lets one through under a live lock.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@omarchybot omarchybot added the verified Omarchy Triage has verified that this issue is ready for final review label Nov 16, 2026
Comment on lines +9 to +10
function quietInterval(sourcePending) {
return sourcePending ? 500 : 150

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Rejected updates can run

quietInterval() treats 500 ms without file events as the end of a plugin update. But omarchy-plugin-update checks the new files only after Git has written them, and those read-only checks do not extend the timer. If the checks take longer than 500 ms, the shell loads the new QML or JavaScript before they finish—even if the command later rejects and rolls back the update. The rollback cannot undo work that code already started.

Coordinate reloads with the update command rather than using a fixed delay as proof that it finished.

Comment on lines +6 to +15
run_node_test <<'JS'
const fs = require('fs')
const vm = require('vm')
function loadModule(file) {
const context = vm.createContext({})
vm.runInContext(fs.readFileSync(root + '/shell/services/' + file, 'utf8'), context)
return context
}
const reload = loadModule('PluginReload.js')
const auth = loadModule('AuthServiceStore.js')

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Tests break the placement rule

This adds plugin-hot-reload-test.sh even though runtime-smoke-test.sh already covers local plugin reloads and is extended by this PR. The contributor guide requires extending the area's existing test file instead of adding another *-test.sh. Splitting this coverage adds maintenance work. Move these helper checks into an existing plugin test file before merging to meet that requirement.

File Used: AGENTS.md (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed at b736fe8. Since quattro's #18198 rewrote the same watcher handler, the branch no longer merged, so I pushed two commits to it. Everything below was run at the new head, 08b198f, on a disposable worker VM built from the Omarchy ISO.

Pushed:

  • 819ca3a merges current quattro (3b36b9e) and resolves the conflict in shell/shell.qml. Add new plugins without reloading the ones already running #18198 sends an edit to a plugin the shell already runs through a full plugin reload, and a plugin that just appeared through a gentle rescan. Now a .qml/.js/.mjs/qmldir edit to a loaded plugin takes your engine reload, and a new plugin's files arriving still only add it. Otherwise a fresh plugin install would close every panel, which is what Add new plugins without reloading the ones already running #18198 set out to stop.
  • 08b198f makes hasActiveLock() read currentlyLocked() when the service has it, with locked as the fallback (shell/services/AuthServiceStore.js). That is the lock-accessor point from the last review. The lock service's bound locked once missed a change, so a stale value could hold a queued reload forever, or let one through under a live lock. Two assertions in plugin-hot-reload-test.sh cover both directions.

The fix still works on current quattro. With only your runtime test applied, quattro still reads qml-before after the QML edit. #18198's full plugin reload does not refresh compiled code: Qt.clearComponentCache is not a function on the QML Qt object, so that line never ran. On this branch runtime-smoke-test passes 27 of 27, with one screen and with a second headless one. Then I tested the lock in the live session. I installed a local service plugin that records its version each time it loads, locked with omarchy-shell lock lock, and saved three edits. Nothing reloaded and the shell stayed the same process. On unlock it reloaded once, onto the last edit.

Still open, and blocking: an open polkit prompt is torn down by a source edit. This is the finding from the last review, and nothing has changed it: hasActiveLock() still only asks about the lock, and the polkit agent has no lock state. The causal path is the same one I reproduced at 4b5bfb2, where pkexec exited 126. I did not re-run that reproduction at this head.

Smaller points:

  • Greptile's 1-second retry while locked (shell/shell.qml) is polling for state that has a change signal, which agents/skills/shell-dev.md asks to avoid. It is one in-process timer that runs only while a reload is queued, so it costs little. It could go when the guard is reworked for polkit.
  • Greptile's multi-screen point does not hold. Commons/ShellIpc.qml enables only the leading handler per target, so the reloads add no collisions. On the two-screen run the log had none at all.
  • The comment in PluginReload.js says the 500ms quiet period waits out an omarchy plugin update validation and reset. It only does that when validation finishes within 500ms of the last write.
  • Only reload local plugins when loadable sources change #12189 narrows the watcher to manifest, .qml and .js files. If it lands as written, qmldir and .mjs edits never reach this branch's classifier.

Tests on the worker:

  • plugin-hot-reload-test: 21 of 21.
  • plugin-auth-boundary-test: 13 of 13.
  • The rest of the plugin-*, lock-* and polkit files in test/shell.d: all pass.
  • ./test/cli: 136 of 136.

Competing fixes for #6981: this is still the one I'm recommending. #7259 is the oldest, but it restarts the shell only after omarchy plugin update/remove, so a hand edit stays stale. #7771 and #8766 both reload the engine with no lock guard. #8766 also does it on every rescan, which undoes #18198. #8766's watching of symlinked plugin folders is a separate improvement this branch does not have.

Two models reviewed this separately: Codex Medium and muse-wonder (via pi, thinking high). Both found no defect in the merge resolution or in 08b198f. Both confirmed the polkit gap is still there. Both chose this pull request over the other three. Both explained why the multi-screen point does not hold, and raised the 500ms and #12189 points. They can read this session's notes, so their agreement is not guaranteed independent.

Next step is yours: keep a source reload from taking down an open polkit prompt, in a way the runtime smoke test can still pass.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working verified Omarchy Triage has verified that this issue is ready for final review

Projects

None yet

3 participants