kernel: generalize the inotify watcher into a Host::watch_file service

The hot-reload watcher was substrate-internal; expose it as a typed RAII primitive
any extension can use (config hot-reload is the first consumer), per "the kernel
owns the event/service bus; extensions never hold raw event-loop glue".

- New public watch.hpp: `class FileWatch` (move-only RAII; ~/reset() stop the
  watch) + `Host::watch_file(path, on_change) -> FileWatch`. on_change fires on the
  event-loop thread, COALESCED (one save = one call), EDITOR-SAFE (dir-watch the
  basename across temp+rename), fires on CREATE of a not-yet-existing file, and is
  ERROR-ISOLATED to the calling extension (carries its id; a throw disables only
  that extension). UNGATED — works without UNBOX_DEV.
- New src/file_watcher.{hpp,cpp}: ONE session-wide inotify instance on the
  wl_event_loop multiplexing all watched paths. The substrate's UI-asset hot-reload
  was refactored onto it (no second inotify); only the substrate's *decision* to
  watch UI assets stays UNBOX_DEV-gated. Created lazily on first watch; torn down
  leak-clean before the loop dies.

host.hpp/kernel.md documented. kernel 58 cases/254 assertions green on build +
build-asan (incl. the inotify path), no new suppressions. Edits confined to
packages/kernel/.

1 files changed, 24 insertions, 5 deletions

diff --git a/packages/kernel/src/server.cpp b/packages/kernel/src/server.cpp
index 5d78b70..cbd23c3 100644
--- a/packages/kernel/src/server.cpp
+++ b/packages/kernel/src/server.cpp
@@ -376,13 +376,25 @@ void Server::Impl::start_substrate() {
     }
     // A data-event/getter throw disables the owning extension via the same
     // isolation path the bus uses (Server::Impl is the DisableSink). The
-    // wl_event_loop lets the substrate poll the dev hot-reload inotify fd
-    // (UNBOX_DEV-gated) without ever blocking the loop.
-    substrate = Substrate::create(display_egl, allocator, renderer,
-                                  wl_display_get_event_loop(display),
+    // substrate uses the kernel's ONE shared FileWatcher for (UNBOX_DEV-gated)
+    // asset hot-reload — the same watcher Host::watch_file uses for config.
+    substrate = Substrate::create(display_egl, allocator, renderer, file_watcher(),
                                   [this](ExtensionId who) { disable(who); });
 }
 
+auto Server::Impl::file_watcher() -> FileWatcher* {
+    // Lazily create the ONE shared inotify watcher on first use (config watch or
+    // asset hot-reload), carrying the kernel's disable sink for error isolation.
+    if (watcher == nullptr) {
+        if (display == nullptr) {
+            return nullptr;
+        }
+        watcher = std::make_unique<FileWatcher>(wl_display_get_event_loop(display),
+                                                [this](ExtensionId who) { disable(who); });
+    }
+    return watcher.get();
+}
+
 void Server::Impl::shutdown() {
     // Destroy extensions FIRST, in reverse activation order: their RAII members
     // (Subscriptions, Listeners, scene nodes) release while the wlr objects
@@ -396,9 +408,16 @@ void Server::Impl::shutdown() {
     extensions.clear();
 
     // The ui substrate owns scene nodes + GL objects on a sibling context and
-    // borrows scene/renderer/allocator: tear it down before they die.
+    // borrows scene/renderer/allocator: tear it down before they die. (Its asset
+    // FileWatch handles release here, removing those watches from the watcher.)
     substrate.reset();
 
+    // The shared file watcher removes its wl_event_loop source + closes the
+    // inotify fd here — AFTER every FileWatch holder (extensions, substrate) is
+    // gone, and while the display/loop is still alive (the source must be
+    // removed before wl_display_destroy).
+    watcher.reset();
+
     if (display != nullptr) {
         wl_display_destroy_clients(display);
     }