Skip to content

Only reload local plugins when loadable sources change - #12189

Open
DonnieFi wants to merge 8 commits into
omacom:quattrofrom
DonnieFi:fix/12158-plugin-watcher-allowlist
Open

DonnieFi wants to merge 8 commits into
omacom:quattrofrom
DonnieFi:fix/12158-plugin-watcher-allowlist

Conversation

@DonnieFi

@DonnieFi DonnieFi commented Sep 16, 2026 •

Copy link
Copy Markdown

Summary

  • Allowlist the local plugin filesystem watcher to manifest.json / *.manifest.json / *.qml / *.js so runtime state writes (e.g. data.json, caches, binaries) no longer tear down the whole bar.
  • Filter both in inotifywait --include and in localPluginIdForPath as defense in depth.
  • Update docs and registry contract assertions for the new behavior.

Fixes #12158

This is intentionally an allowlist rather than extending the denylist approach in related PRs like #12020 / #10705 — those still fire on arbitrary files such as data.json.

Test plan

  • bash test/shell.d/plugin-registry-contract-test.sh
  • Smoke-tested inotifywait --include '(manifest\.json$|\.manifest\.json$|\.(qml|js)$)' — data.json suppressed; .qml / manifest.json / .js still fire
  • Manual: install/enable a plugin that writes runtime state under its plugin dir and confirm journal no longer floods with Local plugin changed, reloading
  • Manual: edit a plugin .qml / manifest.json and confirm hot-reload still works

Runtime state writes under a plugin dir (data.json, caches, binaries)
were triggering full bar teardowns via the recursive inotify watch.
Allowlist manifest/QML/JS paths so helper churn cannot storm-reload the shell.

Fixes omacom#12158
@sprajs

sprajs commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

The new filter also suppresses whole-plugin directory moves. I checked inotifywait in a temporary tree: moving a pre-populated directory containing manifest.json into plugins/acme.clock emits the directory path with the old watcher, but emits nothing with this PR's --include regex. There is no separate manifest write for the filter to catch. localPluginIdForPath() now rejects that directory path as well.

Could directory create/move/delete events remain eligible for rescanning while runtime-file writes stay filtered? A regression test that moves a populated plugin directory into the watched tree would cover this without needing a running desktop.

omarchybot and others added 4 commits October 1, 2026 07:18
quattro rewrote shell/README.md and dropped its hot-reload paragraph, so the conflict resolves to quattro's version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
inotifywait drops every directory event once --include is set, whatever the pattern, so moving a populated plugin directory into or out of ~/.config/omarchy/plugins no longer reloaded anything. Filter in localPluginIdForPath alone and let a top-level plugin directory through.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Renaming a populated subdirectory such as components/ inside a plugin produces only a directory event, so the filter dropped it and the plugin kept running stale components. Print the event with each path and let moved directories through; created and deleted ones stay filtered, so a plugin making cache directories still cannot reload the shell.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Codex Medium <noreply@openai.com>
Helper scripts and data files are outside the allowlist too, so editing one now needs a rescan; the docs only mentioned runtime state.

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 Oct 1, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed and run on an Omarchy ISO worker with the shell loaded from this branch. The fix works, and I pushed three commits and a merge of quattro to the branch.

What was checked. On the worker I counted Local plugin changed reloads for each kind of write under ~/.config/omarchy/plugins. Twenty atomic rewrites of a plugin's data.json caused 80 reloads on quattro and 0 on this branch, and 80 again with PluginRegistry.qml put back to quattro. Ten cache.bin writes went from 11 to 0. QML and manifest edits still reload.

What I changed:

  • shell/services/PluginRegistry.qml: @sprajs was right about directory moves. inotifywait drops every directory event once --include is set, whatever the pattern. So renaming a populated plugin directory into or out of the plugins dir reloaded nothing: 0 reloads at the original head, 1 on quattro. The --include is gone. The filter now lives only in localPluginIdForPath, and the watcher prints the event type, so a directory that is moved (MOVED_*,ISDIR) gets through. That covers a whole plugin and a subdirectory such as components/ renamed within one. Created and deleted directories stay filtered, so a plugin making cache directories cannot reload the shell either: 10 reloads on quattro, 0 here. The registry contract fixture has assertions for all three cases.
  • The manual and default/agents/skills/omarchy/plugins.md now say that helper scripts and data files also need omarchy-shell shell rescanPlugins after an edit. That is a real change from quattro, where any saved file reloaded.
  • I merged quattro in to resolve the shell/README.md conflict. quattro rewrote that file and dropped the hot-reload paragraph, so the conflict resolves to its version.

Tests on the worker: plugin-registry-contract, plugin-add, plugin-clone, plugin-enable, plugin-validate and menu-plugin pass. ./test/cli has one failure, vscode generated theme references current theme file. plugins-test and plugin-auth-boundary-test fail because the worker has no node. All three fail the same way on quattro. This PR has no CI checks.

Second opinion (Codex Medium). It was asked separately to choose between this PR, #12020 and #10705, and chose this one. #12020 and #10705 exclude named paths, so data.json and other runtime files still reload the shell. It also found the subdirectory-move gap fixed above. Its second round on the final head found nothing open. It can read this session's working, so its agreement is not guaranteed to be independent.

What happens next. This waits on the maintainer. The suite was not fully green on the worker, for the reasons above, so the PR is labelled verified and not ready. #12020 and #10705 are competing fixes for the same storm; whichever lands, the others should close.

@greptile-apps

greptile-apps Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 4/5

[Medium risk] Changes when local plugins trigger a reload.

The PR appears safe to merge, with non-blocking gaps around moved runtime directories, QML import metadata, and watcher-level test coverage.

Findings

  1. P2 Runtime directory moves still reload ▶
  2. P2 QML import metadata is missed ▶
  3. P2 Watcher parsing remains untested ▶

Summary

The PR narrows automatic local-plugin reloads to manifest, QML, and JavaScript changes, while retaining reloads for moved directories and documenting manual rescans.

  • Runtime-state files are ignored by the path filter.
  • Directory moves still bypass that filter, and QML import metadata is omitted.
  • The added contract assertions do not exercise watcher event parsing.
Diagram
%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Filesystem event] --> B[inotifywait event and path]
  B --> C{Moved directory?}
  C -->|Yes| E[Resolve plugin ID]
  C -->|No| D{Allowed filename?}
  D -->|Yes| E
  D -->|No| F[Ignore]
  E --> G[Reload plugins]
Loading

Reviews (1) · Last reviewed commit: "Say which plugin files no longer reload ..."

Comment thread shell/services/PluginRegistry.qml Outdated
// Hidden entries are not plugins: clone staging dirs, remove backups.
if (relative.indexOf(".") === 0) return ""
if (relative.indexOf("/.git/") !== -1 || relative.endsWith("/.git")) return ""
if (!movedDirectory && !isWatchedPluginPath(relative)) return ""

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 Runtime directory moves still reload Moving a runtime-state directory, such as renaming cache.tmp to cache, bypasses the source-file filter. It triggers a plugin reload even when the directory contains no plugin code, so cache updates can still cause the reloads this change aims to prevent.

Comment on lines +738 to +742
if (baseName === "manifest.json") return true
if (baseName.endsWith(".manifest.json")) return true
if (baseName.endsWith(".qml")) return true
if (baseName.endsWith(".js")) return true
return false

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 QML import metadata is missed Plugins can use directory imports whose qmldir file defines loadable metadata. Editing that file no longer triggers a reload because it is outside this allowlist, leaving the running plugin with stale import metadata until a manual rescan.

Comment on lines +459 to +461
root.assertEqual(registry.localPluginIdForPath(cloneBase, true), "dhh.clock", "a plugin directory moved in or out whole is watched")
root.assertEqual(registry.localPluginIdForPath(cloneBase + "/components", true), "dhh.clock", "a source directory moved within a plugin is watched")
root.assertEqual(registry.localPluginIdForPath(cloneBase + "/cache", false), "", "a runtime directory created by a plugin is ignored")

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 Watcher parsing remains untested These assertions supply the directory-move flag directly, so they do not test how the watcher parses %e %w%f output or classifies real file and directory events. A mistake in that path could change reload behavior while these tests still pass; a watcher-level test would cover the new contract.

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 3 commits October 14, 2026 10:35
quattro added the orphaned-watcher reaper beside the watcher this branch filters; both are kept. The reaper finds watchers by their flags up to the event list, so the new --format still matches it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A plugin copied into ~/.config/omarchy/plugins with cp -r, or moved there from another filesystem, arrives as CREATE,ISDIR followed by files the recursive watch can miss, since inotifywait only adds the new directory once it sees it. Filtering on file names dropped the directory event, so on a worker cp -r of a plugin reloaded the shell zero times where quattro reloads four. A directory created at the top level is a new plugin; one created inside a plugin stays ignored, so a plugin making its own cache directory still reloads nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A directory created inside a plugin does not reload the shell, so a plugin making its own runtime directories stays quiet, and a source folder copied in by hand can land before the recursive watch reaches it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Codex Medium <noreply@openai.com>
@omarchybot omarchybot added verified Omarchy Triage has verified that this issue is ready for final review ready Good to merge labels Oct 14, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

This stopped merging cleanly when quattro gained the orphaned plugin watcher reaper, so I merged quattro in again and ran it on an Omarchy ISO worker with the shell loaded from this branch. The fix still works, and I pushed the merge plus two small commits.

The merge. quattro added reapOrphanedPluginWatchers right above the watcher this PR filters. The conflict resolves to both. The reaper finds watchers by their flags up to the event list, so it still matches this branch's new --format "%e %w%f". On the worker it killed an orphaned watcher started with that format and left the live shell's watcher alone.

What was checked. Reloads counted from the shell log for each kind of write under ~/.config/omarchy/plugins:

quattro this branch this branch, PluginRegistry.qml put back
20 data.json rewrites 21 0 21
cache dir + 5 binary writes 7 0 7
QML edit 1 1 1
plugin dir renamed in / out 1 / 1 1 / 1 1 / 1
plugin dir copied in with cp -r 4 4 1

What I changed:

  • shell/services/PluginRegistry.qml: before this push, a plugin copied in with cp -r, or moved in from another filesystem such as /tmp, reloaded the shell 0 times. That kind of copy shows up as CREATE,ISDIR followed by files the recursive watch can miss, because inotifywait only adds a watch on the new directory after it sees it. A directory created at the top level of the plugins dir now counts as a new plugin. A directory created inside a plugin is still ignored, so a plugin making its own cache directory still reloads nothing. omarchy plugin add and clone were never affected, since they rename and rescan explicitly. The contract fixture covers both cases.
  • manual/32-shell-plugins.md: copying a source folder into an existing plugin by hand can hit the same race, and it was missed in 1 of 3 runs on the worker. Catching it would mean reloading on every directory a plugin creates, so the manual now says to run omarchy-shell shell rescanPlugins after doing that.

Tests on the worker: ./test/cli passes, and so do all ten plugin shell tests, including plugin-auth-boundary, plugin-manifest-scan, plugins and the full plugin-watcher-reap, with node installed on the worker. The worker image lacks node, which is why those were reported as failing before.

Second opinion (Codex Medium). Its first round confirmed the merge composes, and it found the nested-copy race above. Asked to weigh fixing it against documenting it, it recommended documenting it. Its third round, on this head, found nothing open. It can read this session's working, so its agreement is not guaranteed to be independent. Asked separately to choose among this PR, #12020 and the newer #15093, it chose this one: #12020 and #15093 ignore Python bytecode by name, so data.json and other runtime writes still reload the shell. It noted two things they keep that this PR gives up: helper script edits (.py, .sh) still reload automatically, and a moved __pycache__ directory is ignored. The first is the documented trade-off here. #8766 touches the same watcher for a different bug, symlinked plugins, and will conflict with whichever lands first.

What happens next. It is labelled verified and ready and waits on the maintainer. If it lands, #12020 and #15093 should close.

@omarchybot omarchybot removed verified Omarchy Triage has verified that this issue is ready for final review ready Good to merge labels Oct 14, 2026
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

Development

Successfully merging this pull request may close these issues.

Shell reload loop: PluginRegistry watches pluginsDir recursively without filtering, so plugin state writes tear down the whole bar

3 participants