Skip to content

Fix local plugin reloads - #8766

Open
catlee wants to merge 7 commits into
omacom:quattrofrom
catlee:fix/plugin-hot-reload
Open

catlee wants to merge 7 commits into
omacom:quattrofrom
catlee:fix/plugin-hot-reload

Conversation

@catlee

@catlee catlee commented Aug 28, 2026 •

Copy link
Copy Markdown
Contributor

What changed

  • Watch direct symlinked plugin directories as well as the normal plugin tree.
  • Rebuild that watcher when a top-level plugin entry changes.
  • Use a soft Quickshell reload for plugin rescans, so QML and imported JavaScript load from disk again.

Why

I am working on a local plugin installed through a symlink under ~/.config/omarchy/plugins. Editing the checkout behind that link did not trigger a reload. A manual rescan found manifest changes, but could still run an old imported JavaScript module.

The watcher now includes direct external symlink targets. Rescanning creates a fresh QML engine without unnecessarily recreating windows.

Testing

  • bash test/shell.d/local-plugin-watcher-test.sh
  • bash test/shell.d/plugin-registry-contract-test.sh
  • bash test/shell.d/runtime-smoke-test.sh
  • qmllint shell/shell.qml shell/services/PluginRegistry.qml
  • bash test/shell reaches an unrelated package-checkout failure because OMARCHY_PKGS_PATH is not configured in this worktree.

Fixes #6981

Fixes #11740

@catlee
catlee force-pushed the fix/plugin-hot-reload branch from 319efd8 to 2ca9f1d Compare August 28, 2026 15:47
@catlee
catlee marked this pull request as ready for review August 28, 2026 16:07
Copilot AI balanced review requested due to automatic review settings August 28, 2026 16:07

Copilot AI left a comment

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.

Pull request overview

Fixes local plugin hot reloads for symlinked development directories and stale imported JavaScript.

Changes:

  • Watches external symlink targets and rebuilds watches after plugin-root changes.
  • Uses soft Quickshell reloads for fresh QML engines.
  • Adds watcher and runtime regression tests.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
shell/scripts/watch-local-plugins Watches plugin trees and external symlink targets.
shell/services/PluginRegistry.qml Integrates and rebuilds the watcher.
shell/shell.qml Replaces manual plugin unloading with soft reloads.
test/shell.d/local-plugin-watcher-test.sh Tests symlink target and replacement events.
test/shell.d/runtime-smoke-test.sh Covers linked plugins and JavaScript reloading.
test/shell.d/fixtures/plugin-registry/shell.qml Tests plugin-root change classification.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Copilot AI left a comment

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.

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Comment thread shell/scripts/watch-local-plugins Resolved
Comment thread test/shell.d/runtime-smoke-test.sh Resolved

Copilot AI left a comment

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.

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Comment thread shell/services/PluginRegistry.qml Resolved

Copilot AI left a comment

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.

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

shell/shell.qml:717

  • This changes the reload lifecycle for the entire shell, but the listed tests only verify that IPC and plugin data recover; they do not verify the stated window-preservation behavior. AGENTS.md:120 requires running-UI visual verification for changes with visual effects. Please verify and document that an open bar/panel remains correctly mapped without flicker, stale state, or focus regressions across a plugin rescan.
    Quickshell.reload(false)

@jorgeccastro

jorgeccastro commented Aug 29, 2026 •

Copy link
Copy Markdown

I reran the full smoke test on a two-monitor session and tracked the apparent 3 -> 8 IPC-handler increase. It is a test-accounting issue, not a runtime handler leak.

The warning count is cumulative across engine generations:

current quattro: 1 generation, 3 warnings per target
PR #8766:        8 generations, 8 warnings per target

In Quickshell 0.3.1 the IPC registry is scoped to an EngineGeneration, and the new handlers register after the old generation is destroyed. The PR's imported-JavaScript marker and all subsequent IPC checks also confirm that calls reach the new engine.

The existing assertion only allows (screens - 1) warnings for the entire log. With the new soft reload coverage, it needs to account for every loaded generation:

generations=$(grep -c "Configuration Loaded" "$log" || true)
(( generations > 0 )) || generations=1
allowed_collisions=$((generations * (screens - 1)))

Then compare worst with allowed_collisions. I applied that test-only change locally on top of f2b1fb5a and removed the unused hyprlandPluginState property from shell.qml.

Results on Omarchy 4.0.1, Quickshell 0.3.1, Hyprland 0.56.2, two monitors:

local-plugin-watcher-test.sh: PASS
runtime-smoke-test.sh:       PASS

One minor caveat remains: IPC calls can briefly return NoCurrentGeneration during a soft reload. The current smoke test retries through that window, so I would not block the PR on it.

I can provide the two small commits if useful.

@catlee

catlee commented Aug 30, 2026

Copy link
Copy Markdown
Contributor Author

I can provide the two small commits if useful.
Sure, that would be great!

hyprlandPluginState came from another branch I'm working on - #8396. It leaked into this PR.

@willisiswillis

willisiswillis commented Aug 30, 2026 •

Copy link
Copy Markdown

@catlee

Compatibility warning for the current Quickshell package:

This PR changes reloadPlugins() to call Quickshell.reload(false), so plugin changes deliberately destroy an EngineGeneration. The runtime fixture also creates an IpcHandler and drives repeated reloads while asynchronous events remain active.

Quickshell 0.3.1-1 has a confirmed use-after-free at exactly this lifecycle boundary: quickshell#956. We symbolized two crashes on Omarchy 4.0.1-1 / Quickshell 0.3.1-1 / Qt 6.11.2:

__dynamic_cast
IpcHandler::updateRegistration()  ipchandler.cpp:318
IpcHandler::onPostReload()         ipchandler.cpp:278
QQmlObjectCreator::finalize
QQmlComponent::createObject
...
Process::onFinished
QSocketNotifier::event

In both cores, EngineGeneration::destroy() had deleted the IPC registry extension while the generation remained discoverable. A pending Process::onFinished callback then completed a new IpcHandler and attempted to cast the freed extension. One core showed the extension’s vtable cleared; the other showed its memory already reused for UTF-16 manifest JSON.

Quickshell master now contains an apparent direct fix: 2d3b3e9 moves extension destruction into the generation destructor, after JavaScript interruption and engine teardown. Arch’s current quickshell 0.3.1-1 predates it.

This does not mean the watcher/cache design in this PR is wrong, but merging this against unpatched 0.3.1 would exercise the vulnerable generation-teardown boundary on every plugin change, increasing exposure to the timing-dependent use-after-free. Could the PR either wait until Omarchy consumes a Quickshell build containing 2d3b3e9, or explicitly require/carry that fix?

A useful regression test would start a Process-driven IpcHandler construction, trigger a soft reload or IPC kill while completion is in flight, and assert a clean exit/reload. The current smoke test verifies eventual recovery but does not exercise that teardown race.

@jorgeccastro

Copy link
Copy Markdown

Adding the two data points I have from the same lifecycle boundary, since my
run above drove it repeatedly.

On Omarchy 4.0.1-1 / Quickshell 0.3.1-1 / Hyprland 0.56.2, two monitors, the
smoke test loaded eight generations without a crash. IPC calls did return
NoCurrentGeneration for a short window during each soft reload, and the test
retries through it. So the teardown path is reachable and observably not atomic
here; my runs simply did not land on the freed extension.

My two commits on this PR are test-only accounting plus the stray property, so
they neither exercise nor avoid the race you name. A regression test of the
shape you describe would be new coverage either way.

I have not tried to reproduce quickshell#956 directly and I take no position on
whether it should gate this merge.

@willisiswillis

willisiswillis commented Aug 30, 2026 •

Copy link
Copy Markdown

Thanks for the follow-up. I think we’re mostly agreeing, but I want to make the distinction clear.

Your test shows that eight reloads can complete successfully. I believe that result. The problem is that this is a timing-dependent crash, so eight successful reloads do not tell us whether the teardown is safe—they only tell us those eight reloads missed the bad timing window.

I went back and tested that window directly. I built QuickShell 0.3.1 twice from the same source:

  • One build was unchanged.
  • The other had only the small upstream teardown fix from 2d3b3e9.

Using this PR’s actual plugin watcher and real plugin-file edits, the unpatched build crashed in five out of six runs. Most crashes happened after only one to four edits. The build with the QuickShell fix completed 100 consecutive edits without crashing.

I also tested the reload operation by itself with randomized timing. The unpatched build crashed in 27 of 30 runs. The fixed build survived all 30 runs and loaded 909 generations.

Interestingly, when I used an exact 150 ms interval every time, the unpatched build survived 400 generations. That likely explains why your eight-generation smoke test passed: repeating at a fixed interval can consistently miss a timing-sensitive race.

So I am not saying every plugin edit will crash the shell. I am saying every successful plugin edit now triggers a full QuickShell generation teardown, and on the currently packaged QuickShell 0.3.1-1, that teardown contains the use-after-free described in quickshell#956. Each edit gives the race another opportunity to happen.

This PR did not create the QuickShell bug. It just makes that buggy teardown path part of the normal plugin-edit workflow. My recommendation is therefore straightforward: merge or release this only after Omarchy’s QuickShell package includes 2d3b3e9. Once that fix is present, I have no objection based on this issue.

TLDR: The upstream QuickShell fix does not replace this PR—it makes the soft-reload behavior added by this PR safe to use. My only concern is release ordering: Omarchy should consume 2d3b3e9 before shipping #8766. Once the packaged QuickShell contains that fix, this concern is resolved.

@jorgeccastro

Copy link
Copy Markdown

Here they are: catlee#1 (the test accounting and the stray property, on top of f2b1fb5a).

@Rockzmash

Copy link
Copy Markdown

Adding a third option that I don't think has come up yet, since the teardown-safety
question above is currently what gates this.

Keep the in-place reload, and give Qt.createComponent() a unique URL instead.

The stale-code symptom follows from Qt.clearComponentCache never existing on the QML
Qt global (as @rishwanth-th establishes in #6981), so the guard in
finishPluginReload() is always false and nothing is ever evicted. The type loader then
returns the previously compiled unit for an unchanged URL. Making the URL unique per load
sidesteps the cache without touching engine lifetime:

-    var comp = Qt.createComponent(url, Component.Asynchronous)
+    var reloadUrl = url + (url.indexOf("?") === -1 ? "?" : "&") + "omarchyReload=" + Date.now()
+    var comp = Qt.createComponent(reloadUrl, Component.Asynchronous)

The reason this might be worth a look here: it does not destroy an EngineGeneration,
so it does not go near quickshell-mirror/quickshell#956 at all.

What I verified

Omarchy 4.0.1-1, quickshell 0.3.1-1, qt6-declarative 6.11.2-1, Arch, kernel 7.1.9,
single monitor. Tested against a copy of the shell tree via OMARCHY_PATH, not the
packaged one.

With a throwaway bar-widget plugin logging a BUILD=<n> marker on completion, two
consecutive live edits were both picked up with no restart:

17:41:01  Local plugin changed, reloading: zz.reloadprobe
17:41:01  loadPluginWidget ... BarWidget.qml?omarchyReload=1788212461069
17:41:01  RELOADPROBE BUILD=D
17:41:18  RELOADPROBE BUILD=E

Unpatched, the same edit re-instantiates the widget and re-runs the old marker.

I also instrumented syncPluginWidgets() to check the bookkeeping, since @battisti
raised the reuse branch above: during a reload the existing && existing.url === url
branch is never taken, because unloadPluginWidgets() has already emptied
pluginWidgetComponents. loadPluginWidget() is called every time, with the right URL.
So on this path the reuse branch is not a compounding cause — the cache is.

A third-party plugin using a relative .js import and a sibling QML type kept loading
correctly with the query string present, which was my main worry about this approach.

Limits, stated plainly

  • I only patched and tested the bar-widget site. Panels load via
    Loader { source: sourceUrl } and services via
    Qt.createComponent(url, Component.PreferSynchronous); both would need the same
    treatment, so this is three call sites, not one. Quickshell.reload(false) covers
    all of them at once, which is a real advantage of this PR's approach.
  • Compilation units accumulate, one per reload per plugin, for the life of the
    process. Fine for an edit loop; it is a trade, not a clean win.
  • I have not tried to reproduce quickshell#956, and I take no position on whether
    it should gate this merge.

Not suggesting this should replace the approach here — posting it as a data point in
case a change that avoids the generation boundary is useful while #956 is open.

Measurements run by an AI agent on my machine; I reviewed the results and the
claims above are limited to what was actually observed.

@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed at 2a6f31c, with tests run on a disposable worker VM built from the Omarchy ISO, the shell served from the tree under test.

On its own base the branch does what it says: local-plugin-watcher-test passes 2 of 2 and runtime-smoke-test passes 18 of 18, including the imported-JavaScript reload check. The problem is real on current quattro too: the watcher there still runs a plain recursive inotifywait on the plugins directory, and finishPluginReload() still guards on Qt.clearComponentCache, which the QML Qt object does not have, so nothing is evicted (#6981).

It conflicts with quattro in shell/shell.qml, and the conflict is not mechanical. Since this branched, quattro made plugin hot-reload keep keepLoaded services alive (#9485, so omarchy.lock is not destroyed while Hyprland holds the session lock), keep authentication services alive across rescans (#9618), and keep panel loaders across plugin changes (#13439). Quickshell.reload(false) tears down the whole engine generation, so it discards all three. I merged quattro into this branch locally, keeping the soft reload and quattro's new code, and ran it on the worker: runtime-smoke-test fails "plugin rescan keeps the keepLoaded service instance mounted", and plugin-auth-boundary-test fails "keepLoaded authentication services survive plugin rescans". Both pass on quattro alone. Nothing was pushed to your branch, because choosing how a soft reload should coexist with those guarantees is a design decision rather than a defect fix.

The concern raised above about quickshell-mirror/quickshell#956 still stands: the issue is open, Arch still ships quickshell 0.3.1-1, which predates the upstream fix, and with this change every local plugin edit goes through that generation teardown.

Related: #7259 fixes omarchy plugin update and remove by restarting the shell and is waiting on the maintainer; it does not touch the file-watcher path this PR is about. The symlink watching in watch-local-plugins is independent of the reload mechanism and would stand on its own.

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

Next step is yours: bring the branch up to date with quattro in a way that keeps keepLoaded and authentication services mounted across a plugin reload. Whether it should then wait for a Quickshell build carrying the #956 fix is the maintainer's call.

@neilofneils404

Copy link
Copy Markdown

Tested this with a symlinked plugin checkout, coming from #14387 (closed as a duplicate of #6981). It fixes both problems for me.

Setup: Omarchy 4.0.4, quickshell 0.3.1, Qt 6.11.2. The plugin is a bar widget whose directory in ~/.config/omarchy/plugins/ is a symlink to a checkout elsewhere in $HOME. It has an entry BarWidget.qml, a Panel.qml loaded from it, sibling QML components, and an import "Model.js".

How I ran it: I applied the three shell/ files from this PR to a copy of the installed 4.0.4 shell and ran that copy in place of the stock one. So this is the PR's logic on 4.0.4, not the branch itself and not current quattro. One shell.qml hunk did not apply and I reconciled it by hand: 4.0.4 has a keepLoaded-aware unloadPluginServices() and an onPluginsChanged handler that also calls syncPluginApis(), so I only dropped the pluginReloading guard there. That is probably the same area that conflicts with quattro now.

Results

  • The watcher is started with the symlinked plugin as an explicit root: inotifywait -m -r ... ~/.config/omarchy/plugins ~/.config/omarchy/plugins/<id>.
  • Editing a QML file through the symlink, with no manual rescan: "Local plugin changed, reloading" is logged, the configuration reloads, and the edit is on screen.
  • Editing the imported Model.js: the new code runs after the automatic reload.
  • Editing a sibling QML component that is not an entry point: picked up as well.
  • omarchy-shell shell rescanPlugins by hand: returns ok, the shell answers IPC again within about 3 seconds, and there is still one shell process and one plugin watcher afterwards.
  • Reverting the edits reloaded back to the original UI.

On stock 4.0.4 none of these edits appear until omarchy restart shell.

Not covered: a rebase onto current quattro, a third-party bar plugin, and reloading while the session is locked.

@neilofneils404

Copy link
Copy Markdown

I rebased this onto current quattro (81145eb) in case it saves time: https://github.com/neilofneils404/omarchy/tree/rebase-8766-plugin-hot-reload

The rebase itself is small, but it runs into a contract that landed on quattro after this PR was written, so I don't think it can go in as-is.

Conflicts (all in shell/shell.qml, first commit only)

  • Dropped unloadPluginServices(), serviceKeepLoaded() and unloadPanels(), in line with this PR removing the in-engine reload.
  • Kept the newer onPluginsChanged handlers (syncPluginApis(), syncPanelEntries()) and only removed their pluginReloading guards.
  • Updated one comment that still referred to unloadPanels.

The other six commits applied cleanly. qmllint passes on shell.qml and PluginRegistry.qml.

Tests on the rebased branch

  • pass: local-plugin-watcher-test.sh, plugin-registry-contract-test.sh
  • fail: plugins-test.sh ("unloadPluginServices honors keepLoaded"), panel-entries-test.sh ("a full plugin reload still rebuilds every panel from fresh code"), plugin-auth-boundary-test.sh ("keepLoaded authentication services survive plugin rescans")
  • not run: runtime-smoke-test.sh, because it starts a second shell on my live session

The three failures are source-pattern checks for the functions this PR removes, so they would need rewriting either way. The part that needs a decision is what they stand for: since #9485 and #13439, quattro requires a keepLoaded service to keep its instance across a plugin rescan, and runtime-smoke-test.sh now asserts exactly that (the acme-keep marker must still read "survived" after rescanPlugins, and the lock must not report lock-stranded). Quickshell.reload(false) starts a new generation, so I'd expect that marker check to fail here, and I have not tested a reload while the session is locked.

So the open question for whoever picks this up: does a soft Quickshell reload keep the session lock and the other keepLoaded services safe enough to replace the #9485 behaviour, or does the reload need to stay in-engine for those and use the new generation only for everything else? The watcher half of this PR (watch-local-plugins plus the registry changes) is independent of that question and passes its test on current quattro.

@omarchybot

Copy link
Copy Markdown
Collaborator

Looked again at 2a6f31c after the two comments above. The head has not moved and it still conflicts with quattro (982290f), so the earlier finding stands: on the worker, with quattro merged in and the soft reload kept, runtime-smoke-test failed "plugin rescan keeps the keepLoaded service instance mounted" and plugin-auth-boundary-test failed "keepLoaded authentication services survive plugin rescans". That answers the open question in the rebase note: the acme-keep check does fail under Quickshell.reload(false).

This time the second opinion, Codex Medium, did run. It read the code without running it. It agreed with the finding above, but it can see this session's own notes, so its agreement is not guaranteed independent. It also raised points of its own, which I checked against the source:

  • Locked session: on quattro, authentication services, the lock included, are created with no QObject parent and held in AuthServiceStore.js (shell/shell.qml around line 914). A generation reload therefore destroys the live lock object instead of handing it over, so a plugin edit while locked would drop the lock client. This is from reading the code; reloading while locked has not been tested.
  • Watcher, PluginRegistry.qml restartLocalPluginWatcher(): when a top-level plugin entry changes, the watcher stops and only restarts a second later, and nothing rescans afterwards, so an edit made in that window is missed.
  • Watcher, watch-local-plugins line 15: a plugin symlinked to a hidden directory inside the plugins tree (plugins/acme.foo -> plugins/.sources/foo) is skipped as internal, and its events then arrive under .sources/..., which localPluginIdForPath() ignores. quattro behaves the same, so this is not a regression, just a case the fix does not cover.
  • runtime-smoke-test.sh: the collision allowance is generations * (screens - 1) across the whole log, so on more than one screen a generation where a widget was absent leaves slack that can hide a duplicate in another. It is stricter to count per target and generation. On a single screen the allowance is 0 and nothing changes.

I linked #6981, which this fixes.

Next step is still yours, @catlee: bring the branch up to date with quattro without dropping keepLoaded and authentication services across a plugin reload. Whether it then waits for a Quickshell build carrying the quickshell#956 fix is the maintainer's call.

@omarchybot

Copy link
Copy Markdown
Collaborator

Looked again at 2a6f31c. The head has not moved, but there are now five open pull requests for this bug, so I compared them. This one is not the one I'm recommending to the maintainer.

The competing fixes, oldest first:

The part of this pull request none of the others has is the symlink watching: shell/scripts/watch-local-plugins watching symlinked plugin directories directly, and the registry rebuilding the watcher when a top-level entry changes. The others only fix the cache, so edits to a plugin linked in from a checkout elsewhere, the case you described, would still go unnoticed. That half is independent of the reload mechanism and could stand as a pull request of its own against quattro.

This was checked by reading the five diffs against quattro. Nothing new was run on a worker, since the head is unchanged and the worker results above still apply. Codex Medium compared the five separately, without being given my answer. It reached the same conclusion about this pull request, judged #10576 the one to recommend, and singled out the symlink watcher as the part worth keeping. It can read this session's notes, so its agreement is not guaranteed independent.

Waiting on the maintainer to choose among #10576, #11408 and #13911.

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

Labels

bug Something isn't working

Projects

None yet

7 participants