From 2895955c5959b0da658bf17cf763b73ace74268b Mon Sep 17 00:00:00 2001
From: Mohamed Mansour <hello@mohamedmansour.com>
Date: Thu, 29 Oct 2026 16:06:20 -0700
Subject: [PATCH 1/2] fix: retarget the dev-server watcher instead of replacing
 it

Press replaced its file watcher after every rebuild. Dropping the old
notify-debouncer-mini watcher discards events still inside its 50 ms
debounce window, and the replacement only sees writes made after it
registers. A source edit landing just before the swap was lost, so
markdown-state-serve.test.ts intermittently waited 30 s for a rebuild
that never came.

- Add WatcherHandle::retarget, which updates subscriptions in place.
  Unchanged recursive roots and the debouncer stay registered; content
  baselines restart as for a new watcher.
- Re-register exact-file parents on every retarget so deleted and
  recreated generated directories are watched again. They use a
  separate notify backend so FSEvents stream restarts cannot interrupt
  source roots.
- Register remaining paths when one cannot be watched, then report the
  first failure.
- Retarget the Press watcher after each rebuild instead of replacing it.

Validation: on main, an edit just before a swap was lost 5/5 times on
both Windows and Linux. The e2e test failed 3/60 under parallel CPU
load; with the fix it passed 210/210, and the full Press suite passed
118/118. cargo xtask check passes.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 crates/webui-dev-server/README.md             |   4 +-
 crates/webui-dev-server/src/lib.rs            |   5 +-
 crates/webui-dev-server/src/watch.rs          | 423 +++++++++++-------
 crates/webui-dev-server/src/watch_backend.rs  |  92 ++++
 .../src/watch_subscriptions.rs                | 355 +++++++++++++++
 crates/webui-press/src/serve.rs               | 153 +++++--
 6 files changed, 837 insertions(+), 195 deletions(-)
 create mode 100644 crates/webui-dev-server/src/watch_backend.rs
 create mode 100644 crates/webui-dev-server/src/watch_subscriptions.rs

diff --git a/crates/webui-dev-server/README.md b/crates/webui-dev-server/README.md
index 8bf4a9869..6089e269a 100644
--- a/crates/webui-dev-server/README.md
+++ b/crates/webui-dev-server/README.md
@@ -8,7 +8,9 @@ This crate provides primitives that any WebUI dev server can compose:
   its own actix handler, generates the matching browser-side `<script>`,
   and injects it before `</body>`.
 - **`watch::spawn_watcher`** — Debounced filesystem watcher backed by
-  `notify`. Calls a closure once per debounce window.
+  `notify`. Calls a closure once per debounce window. When watched inputs
+  change, call `WatcherHandle::retarget` instead of replacing the watcher:
+  dropping a watcher discards events still inside its debounce window.
 - **`spawn_rebuild_worker`** — Coalesces watcher ticks and runs rebuilds on an
   owned `RebuildWorker`. Give the watcher a sender from `worker.sender()`, keep
   the worker alive while serving, then stop the watcher and call
diff --git a/crates/webui-dev-server/src/lib.rs b/crates/webui-dev-server/src/lib.rs
index c88a89993..7577c64f6 100644
--- a/crates/webui-dev-server/src/lib.rs
+++ b/crates/webui-dev-server/src/lib.rs
@@ -7,7 +7,8 @@
 //!
 //! - [`LiveReload`] / [`livereload::sse_handler`] — Server-Sent Events
 //!   broadcaster and actix handler for browser auto-reload.
-//! - [`watch::spawn_watcher`] — debounced filesystem watcher.
+//! - [`watch::spawn_watcher`] — debounced filesystem watcher, retargeted in
+//!   place with [`watch::WatcherHandle::retarget`].
 //! - [`path`] — segment-aware basePath stripping and traversal-safe path
 //!   resolution.
 //! - [`reporter::RebuildReporter`] — terminal UX for rebuild loops
@@ -32,5 +33,5 @@ pub mod worker;
 pub use livereload::{sse_handler, LiveReload, ReloadEvent};
 pub use reporter::{local_hms, RebuildReporter};
 pub use serve::{serve_file_response, serve_static_file, NotFoundStrategy, StaticServeConfig};
-pub use watch::{default_ignore_paths, spawn_watcher, WatchConfig, WatcherHandle};
+pub use watch::{default_ignore_paths, spawn_watcher, WatchConfig, WatchTargets, WatcherHandle};
 pub use worker::{spawn_rebuild_worker, RebuildError, RebuildWorker, TickSender};
diff --git a/crates/webui-dev-server/src/watch.rs b/crates/webui-dev-server/src/watch.rs
index 405f41ea0..497bf43a6 100644
--- a/crates/webui-dev-server/src/watch.rs
+++ b/crates/webui-dev-server/src/watch.rs
@@ -10,66 +10,87 @@
 
 use std::collections::{HashMap, HashSet};
 use std::path::{Path, PathBuf};
-use std::sync::Arc;
+use std::sync::{Arc, Mutex, PoisonError};
 use std::time::Duration;
 
 use anyhow::{Context, Result};
 use notify::{
     event::{AccessKind, AccessMode},
-    Event, EventHandler, EventKind, RecommendedWatcher, RecursiveMode, Watcher, WatcherKind,
+    Event, EventKind,
 };
 use notify_debouncer_mini::{
-    new_debouncer_opt, Config as DebouncerConfig, DebounceEventResult, Debouncer,
+    new_debouncer_opt, Config as DebouncerConfig, DebounceEventResult, DebouncedEvent, Debouncer,
 };
 
+#[path = "watch_backend.rs"]
+mod backend;
 #[path = "watch_hash.rs"]
 mod hash;
+#[path = "watch_subscriptions.rs"]
+mod subscriptions;
 
 #[cfg(test)]
 #[path = "watch_hash_tests.rs"]
 mod hash_tests;
 
+use backend::ContentChangeWatcher;
 use hash::{hash_file, HASH_BUFFER_SIZE};
+use subscriptions::Subscriptions;
 
 /// Owns the watcher background thread. Drop to stop watching.
 ///
 /// `notify-debouncer-mini` spawns its background thread inside the
-/// debouncer struct; dropping the struct kills the thread. Consumers
-/// should hold this handle for the lifetime of their server.
+/// debouncer struct; dropping the struct kills the thread and discards
+/// events still inside the debounce window. Consumers should hold this
+/// handle for the lifetime of their server and call
+/// [`WatcherHandle::retarget`] when their inputs change instead of
+/// replacing it.
 pub struct WatcherHandle {
-    _debouncer: Debouncer<ContentChangeWatcher>,
+    debouncer: Debouncer<ContentChangeWatcher>,
+    filter: Arc<Mutex<EventFilter>>,
+    subscriptions: Subscriptions,
 }
 
-struct ContentChangeWatcher(RecommendedWatcher);
-
-impl Watcher for ContentChangeWatcher {
-    fn new<F: EventHandler>(mut event_handler: F, config: notify::Config) -> notify::Result<Self> {
-        RecommendedWatcher::new(
-            move |event| {
-                if matches!(&event, Ok(event) if is_read_only_access_event(event)) {
-                    return;
-                }
-                event_handler.handle_event(event);
-            },
-            config,
-        )
-        .map(Self)
-    }
-
-    fn watch(&mut self, path: &Path, recursive_mode: RecursiveMode) -> notify::Result<()> {
-        self.0.watch(path, recursive_mode)
-    }
-
-    fn unwatch(&mut self, path: &Path) -> notify::Result<()> {
-        self.0.unwatch(path)
-    }
-
-    fn configure(&mut self, config: notify::Config) -> notify::Result<bool> {
-        self.0.configure(config)
-    }
-
-    fn kind() -> WatcherKind {
-        RecommendedWatcher::kind()
+impl WatcherHandle {
+    /// Replace the watched roots, exact files, and ignored subtrees in place.
+    ///
+    /// A replacement watcher would discard events this one has observed but
+    /// not yet debounced, losing edits made while a host refreshes its inputs.
+    /// Retargeting keeps the debouncer and unchanged roots registered, so those
+    /// events are still delivered. Content baselines restart as they would for
+    /// a new watcher: exact files are re-hashed and other paths forward their
+    /// next event.
+    ///
+    /// # Errors
+    ///
+    /// Returns the first error from a path that exists but cannot be watched.
+    /// The remaining paths are still registered, and the failed path is retried
+    /// on the next retarget.
+    pub fn retarget(&mut self, targets: WatchTargets) -> Result<()> {
+        let WatchTargets {
+            paths,
+            explicit_files,
+            ignore,
+        } = targets;
+        // Canonicalize ignore paths once. Non-existent entries are kept as-is
+        // so they still match if the path appears mid-session (e.g. a fresh
+        // `dist/` created by the first build).
+        let ignore = ignore
+            .into_iter()
+            .map(|path| std::fs::canonicalize(&path).unwrap_or(path))
+            .collect();
+        let explicit_files: Vec<PathBuf> = explicit_files
+            .iter()
+            .filter_map(|path| normalize_explicit_file(path))
+            .collect();
+        // Install the new filter before subscribing so events from new
+        // subscriptions are judged against the new targets.
+        self.filter
+            .lock()
+            .unwrap_or_else(PoisonError::into_inner)
+            .reset(ignore, explicit_files.clone());
+        self.subscriptions
+            .retarget(self.debouncer.watcher(), &paths, &explicit_files)
     }
 }
 
@@ -117,6 +138,89 @@ pub struct WatchConfig {
     pub retry_unchanged_when: Option<Arc<dyn Fn() -> bool + Send + Sync>>,
 }
 
+/// Inputs that [`WatcherHandle::retarget`] replaces on a running watcher.
+///
+/// Fields mean the same as their [`WatchConfig`] counterparts.
+pub struct WatchTargets {
+    /// Roots to watch recursively. Non-existent entries are skipped until a
+    /// later retarget finds them.
+    pub paths: Vec<PathBuf>,
+    /// Exact files to watch through their parent directories, bypassing
+    /// `ignore`.
+    pub explicit_files: Vec<PathBuf>,
+    /// Subtrees whose events are suppressed.
+    pub ignore: Vec<PathBuf>,
+}
+
+/// Event filtering state shared by the debouncer thread and
+/// [`WatcherHandle::retarget`].
+struct EventFilter {
+    ignore: Vec<PathBuf>,
+    explicit_files: Vec<PathBuf>,
+    content_hashes: HashMap<PathBuf, u64>,
+    hash_buffer: [u8; HASH_BUFFER_SIZE],
+}
+
+impl EventFilter {
+    fn new() -> Self {
+        Self {
+            ignore: Vec::new(),
+            explicit_files: Vec::new(),
+            content_hashes: HashMap::new(),
+            hash_buffer: [0; HASH_BUFFER_SIZE],
+        }
+    }
+
+    /// Filter by new targets and restart content baselines, as a new watcher
+    /// would: exact files compare with their current bytes.
+    fn reset(&mut self, ignore: Vec<PathBuf>, explicit_files: Vec<PathBuf>) {
+        self.ignore = ignore;
+        self.explicit_files = explicit_files;
+        self.content_hashes.clear();
+        for file in &self.explicit_files {
+            content_changed(&mut self.content_hashes, file, &mut self.hash_buffer);
+        }
+    }
+
+    /// Changed source paths in one debounce window.
+    fn changed_paths(&mut self, events: &[DebouncedEvent], retry_unchanged: bool) -> Vec<PathBuf> {
+        // Filter out ignored paths and dedupe (notify can emit
+        // duplicate events for the same path within a window).
+        let mut paths: Vec<PathBuf> = Vec::with_capacity(events.len());
+        let mut seen: HashSet<PathBuf> = HashSet::with_capacity(events.len());
+        for event in events {
+            collect_event_paths(
+                &event.path,
+                &self.ignore,
+                &self.explicit_files,
+                &mut seen,
+                &mut paths,
+            );
+        }
+        // Recursive backends emit directory metadata events alongside
+        // file writes. Existing directories are not source changes and
+        // would otherwise retrigger a rebuild after every build; keep
+        // missing paths so directory/file deletions still rebuild.
+        paths.retain(|path| !path.is_dir());
+        // Drop paths whose content is byte-identical to the last event.
+        // Editors fire a write on every Ctrl+S even when nothing changed;
+        // rebuilding then is pure wasted work, so a no-op save triggers no
+        // rebuild at all in the clean state. When the caller reports that a
+        // rebuild error is active, unchanged events are allowed through so a
+        // no-op save can retry transient failures. Deletions and oversized
+        // files always count as changed (see `content_changed`).
+        paths.retain(|path| {
+            should_forward_path(
+                &mut self.content_hashes,
+                path,
+                retry_unchanged,
+                &mut self.hash_buffer,
+            )
+        });
+        paths
+    }
+}
+
 /// Start a debounced recursive watcher.
 ///
 /// The closure `on_event` is invoked once per debounce window with the
@@ -132,7 +236,8 @@ pub struct WatchConfig {
 ///
 /// Non-existent paths in `cfg.paths` are silently skipped; this matches
 /// the dev-server use case where some watched directories (e.g. an
-/// optional `public/`) may not exist yet.
+/// optional `public/`) may not exist yet. Use [`WatcherHandle::retarget`]
+/// to change the watched paths later.
 ///
 /// # Errors
 ///
@@ -142,65 +247,31 @@ pub fn spawn_watcher<F>(cfg: WatchConfig, on_event: F) -> Result<WatcherHandle>
 where
     F: Fn(Vec<PathBuf>) + Send + 'static,
 {
-    // Canonicalize ignore paths once, up front. Non-existent ignore
-    // entries are kept as-is so they still match if the path appears
-    // mid-session (e.g. a fresh `dist/` created by the first build).
-    let ignore: Vec<PathBuf> = cfg
-        .ignore
-        .iter()
-        .map(|p| std::fs::canonicalize(p).unwrap_or_else(|_| p.clone()))
-        .collect();
-    let explicit_files: Vec<PathBuf> = cfg
-        .explicit_files
-        .iter()
-        .filter_map(|path| normalize_explicit_file(path))
-        .collect();
-
-    let mut content_hashes: HashMap<PathBuf, u64> = HashMap::new();
-    let mut hash_buffer = [0_u8; HASH_BUFFER_SIZE];
-    for file in &explicit_files {
-        content_changed(&mut content_hashes, file, &mut hash_buffer);
-    }
-    let retry_unchanged_when = cfg.retry_unchanged_when.clone();
-    let explicit_filter = explicit_files.clone();
+    let WatchConfig {
+        paths,
+        explicit_files,
+        ignore,
+        debounce,
+        retry_unchanged_when,
+    } = cfg;
+    let filter = Arc::new(Mutex::new(EventFilter::new()));
+    let events_filter = Arc::clone(&filter);
     let notify_config = notify::Config::default().with_follow_symlinks(false);
     let debouncer_config = DebouncerConfig::default()
-        .with_timeout(cfg.debounce)
+        .with_timeout(debounce)
         .with_notify_config(notify_config);
-    let mut debouncer = new_debouncer_opt::<_, ContentChangeWatcher>(
+    let debouncer = new_debouncer_opt::<_, ContentChangeWatcher>(
         debouncer_config,
         move |res: DebounceEventResult| match res {
             Ok(events) => {
-                // Filter out ignored paths and dedupe (notify can emit
-                // duplicate events for the same path within a window).
-                let mut paths: Vec<PathBuf> = Vec::with_capacity(events.len());
-                let mut seen: HashSet<PathBuf> = HashSet::with_capacity(events.len());
-                for e in events {
-                    collect_event_paths(&e.path, &ignore, &explicit_filter, &mut seen, &mut paths);
-                }
-                // Recursive backends emit directory metadata events alongside
-                // file writes. Existing directories are not source changes and
-                // would otherwise retrigger a rebuild after every build; keep
-                // missing paths so directory/file deletions still rebuild.
-                paths.retain(|path| !path.is_dir());
-                // Drop paths whose content is byte-identical to the last event.
-                // Editors fire a write on every Ctrl+S even when nothing changed;
-                // rebuilding then is pure wasted work, so a no-op save triggers no
-                // rebuild at all in the clean state. When the caller reports that a
-                // rebuild error is active, unchanged events are allowed through so a
-                // no-op save can retry transient failures. Deletions and oversized
-                // files always count as changed (see `content_changed`).
+                // Ask the host before taking the filter lock.
                 let retry_unchanged = retry_unchanged_when
                     .as_ref()
                     .is_some_and(|predicate| predicate());
-                paths.retain(|path| {
-                    should_forward_path(
-                        &mut content_hashes,
-                        path,
-                        retry_unchanged,
-                        &mut hash_buffer,
-                    )
-                });
+                let paths = events_filter
+                    .lock()
+                    .unwrap_or_else(PoisonError::into_inner)
+                    .changed_paths(&events, retry_unchanged);
                 if !paths.is_empty() {
                     on_event(paths);
                 }
@@ -212,46 +283,17 @@ where
     )
     .context("Cannot start file watcher")?;
 
-    let mut watched_roots = Vec::with_capacity(cfg.paths.len());
-    for p in &cfg.paths {
-        if p.exists() {
-            watched_roots.push(std::fs::canonicalize(p).unwrap_or_else(|_| p.clone()));
-            debouncer
-                .watcher()
-                .watch(p, RecursiveMode::Recursive)
-                .with_context(|| format!("Cannot watch {}", p.display()))?;
-        }
-    }
-    watch_explicit_parents(debouncer.watcher(), &explicit_files, &watched_roots)?;
-
-    Ok(WatcherHandle {
-        _debouncer: debouncer,
-    })
-}
-
-fn watch_explicit_parents(
-    watcher: &mut dyn Watcher,
-    explicit_files: &[PathBuf],
-    watched_roots: &[PathBuf],
-) -> Result<()> {
-    let mut explicit_parents = HashSet::new();
-    for file in explicit_files {
-        if watched_roots.iter().any(|root| file.starts_with(root)) {
-            continue;
-        }
-        while let Some(parent) = file.ancestors().skip(1).find(|parent| parent.is_dir()) {
-            if !explicit_parents.insert(parent.to_path_buf()) {
-                break;
-            }
-            watcher
-                .watch(parent, RecursiveMode::NonRecursive)
-                .with_context(|| format!("Cannot watch {}", parent.display()))?;
-            // A generator can create more parents during registration. Advance
-            // before returning without subscribing to unrelated descendants.
-        }
-    }
-
-    Ok(())
+    let mut handle = WatcherHandle {
+        debouncer,
+        filter,
+        subscriptions: Subscriptions::default(),
+    };
+    handle.retarget(WatchTargets {
+        paths,
+        explicit_files,
+        ignore,
+    })?;
+    Ok(handle)
 }
 
 fn normalize_explicit_file(path: &Path) -> Option<PathBuf> {
@@ -401,46 +443,115 @@ fn should_forward_path(
 #[allow(clippy::disallowed_methods)]
 mod tests {
     use super::*;
+    use notify_debouncer_mini::DebouncedEventKind;
+    use std::sync::mpsc::{self, RecvTimeoutError};
 
-    #[derive(Default)]
-    struct RecordingWatcher {
-        paths: Vec<(PathBuf, RecursiveMode)>,
+    fn event(path: &Path) -> DebouncedEvent {
+        DebouncedEvent::new(path.to_path_buf(), DebouncedEventKind::Any)
     }
 
-    impl Watcher for RecordingWatcher {
-        fn new<F: EventHandler>(_: F, _: notify::Config) -> notify::Result<Self> {
-            Ok(Self::default())
-        }
+    #[test]
+    fn reset_restarts_content_baselines_like_a_new_watcher() {
+        let dir = tempfile::tempdir().unwrap();
+        let exact = dir.path().join("state.json");
+        let source = dir.path().join("page.md");
+        std::fs::write(&exact, "1").unwrap();
+        std::fs::write(&source, "# Page").unwrap();
+        let mut filter = EventFilter::new();
+        filter.reset(Vec::new(), vec![exact.clone()]);
+
+        assert!(filter.changed_paths(&[event(&exact)], false).is_empty());
+        assert_eq!(
+            filter.changed_paths(&[event(&source)], false),
+            std::slice::from_ref(&source)
+        );
+        assert!(filter.changed_paths(&[event(&source)], false).is_empty());
 
-        fn watch(&mut self, path: &Path, mode: RecursiveMode) -> notify::Result<()> {
-            self.paths.push((path.to_path_buf(), mode));
-            Ok(())
-        }
+        std::fs::write(&exact, "2").unwrap();
+        filter.reset(Vec::new(), vec![exact.clone()]);
+        assert!(filter.changed_paths(&[event(&exact)], false).is_empty());
+        assert_eq!(filter.changed_paths(&[event(&source)], false), [source]);
+    }
 
-        fn unwatch(&mut self, _: &Path) -> notify::Result<()> {
-            Ok(())
-        }
+    #[test]
+    fn retarget_delivers_edits_observed_before_it() -> Result<()> {
+        let dir = tempfile::tempdir()?;
+        let source = dir.path().join("page.md");
+        std::fs::write(&source, "# One")?;
+        let (sender, receiver) = mpsc::channel();
+        let mut watcher = spawn_watcher(
+            WatchConfig {
+                paths: vec![dir.path().to_path_buf()],
+                explicit_files: Vec::new(),
+                ignore: Vec::new(),
+                debounce: Duration::from_millis(50),
+                retry_unchanged_when: None,
+            },
+            move |paths| {
+                let _ = sender.send(paths);
+            },
+        )?;
 
-        fn kind() -> WatcherKind {
-            RecommendedWatcher::kind()
-        }
+        std::fs::write(&source, "# Two")?;
+        // A host refreshing its inputs right after the edit must not drop it.
+        watcher.retarget(WatchTargets {
+            paths: vec![dir.path().to_path_buf()],
+            explicit_files: Vec::new(),
+            ignore: Vec::new(),
+        })?;
+        let changed = receiver.recv_timeout(Duration::from_secs(5))?;
+        let source = std::fs::canonicalize(&source)?;
+        assert!(
+            changed
+                .iter()
+                .any(|path| std::fs::canonicalize(path).is_ok_and(|path| path == source)),
+            "missing {} in {changed:?}",
+            source.display()
+        );
+        Ok(())
     }
 
     #[test]
-    fn missing_include_does_not_recursively_watch_ignored_ancestor() {
-        let root = tempfile::tempdir().unwrap();
-        let target = root.path().join("target");
-        std::fs::create_dir_all(target.join("debug/build/unrelated")).unwrap();
-        let file = normalize_explicit_file(&target.join("generated/new/state.json")).unwrap();
-        let mut watcher = RecordingWatcher::default();
-        watch_explicit_parents(&mut watcher, &[file], &[]).unwrap();
+    fn retarget_moves_exact_file_subscriptions() -> Result<()> {
+        let dir = tempfile::tempdir()?;
+        let first = dir.path().join("target/first/state.json");
+        let second = dir.path().join("target/second/state.json");
+        for file in [&first, &second] {
+            std::fs::create_dir_all(file.parent().context("state parent")?)?;
+            std::fs::write(file, "1")?;
+        }
+        let ignore = || vec![PathBuf::from("target")];
+        let (sender, receiver) = mpsc::channel();
+        let mut watcher = spawn_watcher(
+            WatchConfig {
+                paths: Vec::new(),
+                explicit_files: vec![first.clone()],
+                ignore: ignore(),
+                debounce: Duration::from_millis(25),
+                retry_unchanged_when: None,
+            },
+            move |paths| {
+                let _ = sender.send(paths);
+            },
+        )?;
+
+        watcher.retarget(WatchTargets {
+            paths: Vec::new(),
+            explicit_files: vec![second.clone()],
+            ignore: ignore(),
+        })?;
+        std::fs::write(&first, "2")?;
+        let stale = receiver.recv_timeout(Duration::from_millis(500));
+        assert!(
+            matches!(stale, Err(RecvTimeoutError::Timeout)),
+            "a released include must not rebuild: {stale:?}"
+        );
+        std::fs::write(&second, "2")?;
         assert_eq!(
-            watcher.paths,
-            vec![(
-                std::fs::canonicalize(target).unwrap(),
-                RecursiveMode::NonRecursive
-            )]
+            receiver.recv_timeout(Duration::from_secs(5))?,
+            [std::fs::canonicalize(&second)?]
         );
+        Ok(())
     }
 
     #[test]
diff --git a/crates/webui-dev-server/src/watch_backend.rs b/crates/webui-dev-server/src/watch_backend.rs
new file mode 100644
index 000000000..b2581c2d0
--- /dev/null
+++ b/crates/webui-dev-server/src/watch_backend.rs
@@ -0,0 +1,92 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+use std::collections::HashSet;
+use std::path::{Path, PathBuf};
+use std::sync::{Arc, Mutex, PoisonError};
+
+use notify::{
+    Config, Event, EventHandler, RecommendedWatcher, RecursiveMode, Watcher, WatcherKind,
+};
+
+use super::is_read_only_access_event;
+
+type SharedHandler = Arc<Mutex<dyn EventHandler>>;
+
+/// Notify backends that feed one debouncer.
+///
+/// Recursive roots and exact-file parents use separate backends. Exact-file
+/// parents are re-registered on every retarget, and FSEvents applies each
+/// subscription change by restarting its stream, which would also drop root
+/// events during the restart.
+pub(super) struct ContentChangeWatcher {
+    roots: RecommendedWatcher,
+    files: Option<RecommendedWatcher>,
+    file_paths: HashSet<PathBuf>,
+    handler: SharedHandler,
+    config: Config,
+}
+
+fn backend(handler: &SharedHandler, config: Config) -> notify::Result<RecommendedWatcher> {
+    let handler = Arc::clone(handler);
+    RecommendedWatcher::new(
+        move |event: notify::Result<Event>| {
+            if matches!(&event, Ok(event) if is_read_only_access_event(event)) {
+                return;
+            }
+            handler
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner)
+                .handle_event(event);
+        },
+        config,
+    )
+}
+
+impl Watcher for ContentChangeWatcher {
+    fn new<F: EventHandler>(event_handler: F, config: Config) -> notify::Result<Self> {
+        let handler: SharedHandler = Arc::new(Mutex::new(event_handler));
+        Ok(Self {
+            roots: backend(&handler, config)?,
+            files: None,
+            file_paths: HashSet::new(),
+            handler,
+            config,
+        })
+    }
+
+    fn watch(&mut self, path: &Path, recursive_mode: RecursiveMode) -> notify::Result<()> {
+        if recursive_mode == RecursiveMode::Recursive {
+            return self.roots.watch(path, recursive_mode);
+        }
+        let files = match self.files.take() {
+            Some(files) => files,
+            None => backend(&self.handler, self.config)?,
+        };
+        self.files.insert(files).watch(path, recursive_mode)?;
+        self.file_paths.insert(path.to_path_buf());
+        Ok(())
+    }
+
+    fn unwatch(&mut self, path: &Path) -> notify::Result<()> {
+        if !self.file_paths.remove(path) {
+            return self.roots.unwatch(path);
+        }
+        match &mut self.files {
+            Some(files) => files.unwatch(path),
+            None => Ok(()),
+        }
+    }
+
+    fn configure(&mut self, config: Config) -> notify::Result<bool> {
+        self.config = config;
+        if let Some(files) = &mut self.files {
+            files.configure(config)?;
+        }
+        self.roots.configure(config)
+    }
+
+    fn kind() -> WatcherKind {
+        RecommendedWatcher::kind()
+    }
+}
diff --git a/crates/webui-dev-server/src/watch_subscriptions.rs b/crates/webui-dev-server/src/watch_subscriptions.rs
new file mode 100644
index 000000000..9211362cd
--- /dev/null
+++ b/crates/webui-dev-server/src/watch_subscriptions.rs
@@ -0,0 +1,355 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+use std::collections::HashSet;
+use std::path::{Path, PathBuf};
+
+use anyhow::Result;
+use notify::{RecursiveMode, Watcher};
+
+/// A recursive root registered with the backend.
+struct Root {
+    /// Path passed to the backend, which reports events under this spelling.
+    path: PathBuf,
+    /// Canonical form used to compare roots and exact files.
+    canonical: PathBuf,
+}
+
+/// Subscriptions currently registered with a watcher backend.
+#[derive(Default)]
+pub(super) struct Subscriptions {
+    roots: Vec<Root>,
+    explicit_parents: HashSet<PathBuf>,
+}
+
+impl Subscriptions {
+    /// Register existing `paths` recursively and the nearest existing parents
+    /// of normalized `explicit_files`, releasing registrations that are no
+    /// longer needed.
+    ///
+    /// Unchanged roots stay registered so events already observed under them
+    /// are still delivered. Exact-file parents are always re-registered: some
+    /// backends drop a subscription without an event when its directory is
+    /// deleted, and generated directories are routinely recreated.
+    ///
+    /// A path that cannot be watched does not stop the others from being
+    /// registered; the first failure is returned afterwards.
+    pub(super) fn retarget(
+        &mut self,
+        watcher: &mut dyn Watcher,
+        paths: &[PathBuf],
+        explicit_files: &[PathBuf],
+    ) -> Result<()> {
+        for parent in self.explicit_parents.drain() {
+            // A deleted directory may already have released its subscription.
+            let _ = watcher.unwatch(&parent);
+        }
+        let desired = existing_roots(paths);
+        // Release roots before adding new ones: removing a recursive root also
+        // removes subscriptions a new nested root would share with it.
+        let mut index = 0;
+        while index < self.roots.len() {
+            if desired
+                .iter()
+                .any(|root| root.canonical == self.roots[index].canonical)
+            {
+                index += 1;
+                continue;
+            }
+            let root = self.roots.swap_remove(index);
+            let _ = watcher.unwatch(&root.path);
+        }
+        let mut failure = None;
+        for root in desired {
+            if self
+                .roots
+                .iter()
+                .any(|current| current.canonical == root.canonical)
+            {
+                continue;
+            }
+            let watched = watcher.watch(&root.path, RecursiveMode::Recursive);
+            if keep_first_failure(&mut failure, watched, &root.path) {
+                self.roots.push(root);
+            }
+        }
+        watch_explicit_parents(
+            watcher,
+            explicit_files,
+            &self.roots,
+            &mut self.explicit_parents,
+            &mut failure,
+        );
+        failure.map_or(Ok(()), Err)
+    }
+}
+
+/// Whether `result` succeeded, recording the first failure.
+fn keep_first_failure(
+    failure: &mut Option<anyhow::Error>,
+    result: notify::Result<()>,
+    path: &Path,
+) -> bool {
+    let Err(error) = result else {
+        return true;
+    };
+    if failure.is_none() {
+        *failure =
+            Some(anyhow::Error::new(error).context(format!("Cannot watch {}", path.display())));
+    }
+    false
+}
+
+/// Existing `paths` without entries nested inside another root.
+fn existing_roots(paths: &[PathBuf]) -> Vec<Root> {
+    let mut roots: Vec<Root> = Vec::with_capacity(paths.len());
+    for path in paths {
+        if !path.exists() {
+            continue;
+        }
+        let canonical = std::fs::canonicalize(path).unwrap_or_else(|_| path.clone());
+        if roots
+            .iter()
+            .any(|root| canonical.starts_with(&root.canonical))
+        {
+            continue;
+        }
+        roots.retain(|root| !root.canonical.starts_with(&canonical));
+        roots.push(Root {
+            path: path.clone(),
+            canonical,
+        });
+    }
+    roots
+}
+
+fn watch_explicit_parents(
+    watcher: &mut dyn Watcher,
+    explicit_files: &[PathBuf],
+    roots: &[Root],
+    registered: &mut HashSet<PathBuf>,
+    failure: &mut Option<anyhow::Error>,
+) {
+    for file in explicit_files {
+        if roots.iter().any(|root| file.starts_with(&root.canonical)) {
+            continue;
+        }
+        while let Some(parent) = file.ancestors().skip(1).find(|parent| parent.is_dir()) {
+            if registered.contains(parent)
+                || !keep_first_failure(
+                    failure,
+                    watcher.watch(parent, RecursiveMode::NonRecursive),
+                    parent,
+                )
+            {
+                break;
+            }
+            registered.insert(parent.to_path_buf());
+            // A generator can create more parents during registration. Advance
+            // before returning without subscribing to unrelated descendants.
+        }
+    }
+}
+
+#[cfg(test)]
+#[allow(clippy::disallowed_methods)]
+mod tests {
+    use super::super::normalize_explicit_file;
+    use super::*;
+    use notify::{EventHandler, RecommendedWatcher, WatcherKind};
+
+    #[derive(Debug, PartialEq)]
+    enum Call {
+        Watch(PathBuf, RecursiveMode),
+        Unwatch(PathBuf),
+    }
+
+    #[derive(Default)]
+    struct RecordingWatcher {
+        calls: Vec<Call>,
+        denied: Option<PathBuf>,
+    }
+
+    impl Watcher for RecordingWatcher {
+        fn new<F: EventHandler>(_: F, _: notify::Config) -> notify::Result<Self> {
+            Ok(Self::default())
+        }
+
+        fn watch(&mut self, path: &Path, mode: RecursiveMode) -> notify::Result<()> {
+            if self.denied.as_deref() == Some(path) {
+                return Err(notify::Error::generic("permission denied"));
+            }
+            self.calls.push(Call::Watch(path.to_path_buf(), mode));
+            Ok(())
+        }
+
+        fn unwatch(&mut self, path: &Path) -> notify::Result<()> {
+            self.calls.push(Call::Unwatch(path.to_path_buf()));
+            Ok(())
+        }
+
+        fn kind() -> WatcherKind {
+            RecommendedWatcher::kind()
+        }
+    }
+
+    #[test]
+    fn missing_include_does_not_recursively_watch_ignored_ancestor() {
+        let root = tempfile::tempdir().unwrap();
+        let target = root.path().join("target");
+        std::fs::create_dir_all(target.join("debug/build/unrelated")).unwrap();
+        let file = normalize_explicit_file(&target.join("generated/new/state.json")).unwrap();
+        let mut watcher = RecordingWatcher::default();
+        let mut registered = HashSet::new();
+        let mut failure = None;
+        watch_explicit_parents(&mut watcher, &[file], &[], &mut registered, &mut failure);
+        assert!(failure.is_none());
+        assert_eq!(
+            watcher.calls,
+            vec![Call::Watch(
+                std::fs::canonicalize(target).unwrap(),
+                RecursiveMode::NonRecursive
+            )]
+        );
+    }
+
+    #[test]
+    fn retarget_registers_remaining_paths_after_a_failure() {
+        let dir = tempfile::tempdir().unwrap();
+        let denied = dir.path().join("denied");
+        let content = dir.path().join("content");
+        let state = dir.path().join("state");
+        for directory in [&denied, &content, &state] {
+            std::fs::create_dir(directory).unwrap();
+        }
+        let file = normalize_explicit_file(&state.join("page.json")).unwrap();
+        let mut watcher = RecordingWatcher {
+            denied: Some(denied.clone()),
+            ..RecordingWatcher::default()
+        };
+        let mut subscriptions = Subscriptions::default();
+
+        let error = subscriptions
+            .retarget(&mut watcher, &[denied.clone(), content.clone()], &[file])
+            .unwrap_err();
+        assert!(error.to_string().contains("denied"), "{error:#}");
+        assert_eq!(
+            watcher.calls,
+            vec![
+                Call::Watch(content, RecursiveMode::Recursive),
+                Call::Watch(
+                    std::fs::canonicalize(&state).unwrap(),
+                    RecursiveMode::NonRecursive
+                ),
+            ]
+        );
+
+        // The failed root is retried on the next retarget.
+        watcher.denied = None;
+        watcher.calls.clear();
+        subscriptions
+            .retarget(&mut watcher, std::slice::from_ref(&denied), &[])
+            .unwrap();
+        assert!(watcher
+            .calls
+            .contains(&Call::Watch(denied, RecursiveMode::Recursive)));
+    }
+
+    #[test]
+    fn retarget_keeps_unchanged_roots_and_refreshes_exact_file_parents() {
+        let dir = tempfile::tempdir().unwrap();
+        let content = dir.path().join("content");
+        let state = dir.path().join("target/state");
+        std::fs::create_dir_all(&content).unwrap();
+        std::fs::create_dir_all(&state).unwrap();
+        let file = normalize_explicit_file(&state.join("page.json")).unwrap();
+        let parent = std::fs::canonicalize(&state).unwrap();
+        let mut watcher = RecordingWatcher::default();
+        let mut subscriptions = Subscriptions::default();
+
+        subscriptions
+            .retarget(
+                &mut watcher,
+                std::slice::from_ref(&content),
+                std::slice::from_ref(&file),
+            )
+            .unwrap();
+        assert_eq!(
+            watcher.calls,
+            vec![
+                Call::Watch(content.clone(), RecursiveMode::Recursive),
+                Call::Watch(parent.clone(), RecursiveMode::NonRecursive),
+            ]
+        );
+
+        watcher.calls.clear();
+        subscriptions
+            .retarget(
+                &mut watcher,
+                std::slice::from_ref(&content),
+                std::slice::from_ref(&file),
+            )
+            .unwrap();
+        assert_eq!(
+            watcher.calls,
+            vec![
+                Call::Unwatch(parent.clone()),
+                Call::Watch(parent, RecursiveMode::NonRecursive),
+            ]
+        );
+    }
+
+    #[test]
+    fn retarget_releases_replaced_roots_before_watching_their_ancestor() {
+        let dir = tempfile::tempdir().unwrap();
+        let parent = dir.path().join("docs");
+        let nested = parent.join("content");
+        std::fs::create_dir_all(&nested).unwrap();
+        let mut watcher = RecordingWatcher::default();
+        let mut subscriptions = Subscriptions::default();
+
+        subscriptions
+            .retarget(&mut watcher, &[nested.clone(), nested.clone()], &[])
+            .unwrap();
+        assert_eq!(
+            watcher.calls,
+            vec![Call::Watch(nested.clone(), RecursiveMode::Recursive)]
+        );
+
+        watcher.calls.clear();
+        subscriptions
+            .retarget(&mut watcher, &[nested.clone(), parent.clone()], &[])
+            .unwrap();
+        assert_eq!(
+            watcher.calls,
+            vec![
+                Call::Unwatch(nested),
+                Call::Watch(parent, RecursiveMode::Recursive),
+            ]
+        );
+    }
+
+    #[test]
+    fn retarget_follows_roots_that_disappear_and_return() {
+        let dir = tempfile::tempdir().unwrap();
+        let public = dir.path().join("public");
+        let mut watcher = RecordingWatcher::default();
+        let mut subscriptions = Subscriptions::default();
+        let roots = std::slice::from_ref(&public);
+
+        subscriptions.retarget(&mut watcher, roots, &[]).unwrap();
+        assert!(watcher.calls.is_empty());
+
+        std::fs::create_dir(&public).unwrap();
+        subscriptions.retarget(&mut watcher, roots, &[]).unwrap();
+        std::fs::remove_dir(&public).unwrap();
+        subscriptions.retarget(&mut watcher, roots, &[]).unwrap();
+        assert_eq!(
+            watcher.calls,
+            vec![
+                Call::Watch(public.clone(), RecursiveMode::Recursive),
+                Call::Unwatch(public),
+            ]
+        );
+    }
+}
diff --git a/crates/webui-press/src/serve.rs b/crates/webui-press/src/serve.rs
index 91341b8e4..ff2f3c038 100644
--- a/crates/webui-press/src/serve.rs
+++ b/crates/webui-press/src/serve.rs
@@ -34,7 +34,8 @@ use webui_dev_server::path::normalize_base_path;
 use webui_dev_server::shutdown::Control;
 use webui_dev_server::{
     default_ignore_paths, serve_static_file, spawn_rebuild_worker, spawn_watcher, sse_handler,
-    LiveReload, NotFoundStrategy, StaticServeConfig, TickSender, WatchConfig, WatcherHandle,
+    LiveReload, NotFoundStrategy, StaticServeConfig, TickSender, WatchConfig, WatchTargets,
+    WatcherHandle,
 };
 
 use crate::build::{build_docs_with_cache, BuildCache};
@@ -137,17 +138,21 @@ pub async fn run_serve(opts: ServeConfig, control: Option<Control>) -> Result<()
             let tx = sender
                 .get()
                 .ok_or_else(|| "Press watcher sender is unavailable".to_string())?;
-            let next = source_watcher(
-                &cfg,
-                &config_dir,
-                &config_path,
-                &guard.dependencies,
-                tx.clone(),
-            )
-            .map_err(|error| format!("Cannot refresh Press input watches: {error}"))?;
-            *watcher
-                .lock()
-                .map_err(|error| format!("Press watcher lock failed: {error}"))? = Some(next);
+            {
+                let mut slot = watcher
+                    .lock()
+                    .map_err(|error| format!("Press watcher lock failed: {error}"))?;
+                let handle = slot
+                    .as_mut()
+                    .ok_or_else(|| "Press watcher is unavailable".to_string())?;
+                refresh_source_watcher(
+                    handle,
+                    source_targets(&cfg, &config_dir, &config_path, &guard.dependencies),
+                    &guard.dependencies,
+                    tx,
+                )
+                .map_err(|error| format!("Cannot refresh Press input watches: {error}"))?;
+            }
             result.map_err(|e| format!("{e}"))?;
             // webui-press has no per-rebuild advisories to surface.
             Ok(Vec::new())
@@ -216,6 +221,7 @@ pub async fn run_serve(opts: ServeConfig, control: Option<Control>) -> Result<()
     Ok(())
 }
 
+/// Start the input watcher for the build that produced `dependencies`.
 fn source_watcher(
     config: &DocsConfig,
     config_dir: &Path,
@@ -223,29 +229,12 @@ fn source_watcher(
     dependencies: &StateDependencies,
     tx: TickSender,
 ) -> Result<WatcherHandle> {
-    let mut explicit_files = projection_manifest_paths(
-        config_dir,
-        config
-            .bundler
-            .as_ref()
-            .map_or(&[][..], |bundler| bundler.projection_manifests.as_slice()),
-    );
-    explicit_files.extend_from_slice(&dependencies.paths);
-    let mut ignore = default_ignore_paths();
-    ignore.push(PathBuf::from(&config.out_dir));
-    ignore.push(PathBuf::from(".webui-press/cache"));
-    ignore.push(config_dir.join(crate::scratch::PROJECT_SCRATCH_DIR));
     let events = tx.clone();
-    let watcher = spawn_watcher(
+    let mut watcher = spawn_watcher(
         WatchConfig {
-            paths: watch_paths(
-                config_dir,
-                config_path,
-                Path::new(&config.content_dir),
-                Path::new(&config.public_dir),
-            ),
-            explicit_files,
-            ignore,
+            paths: Vec::new(),
+            explicit_files: Vec::new(),
+            ignore: Vec::new(),
             debounce: DEBOUNCE_DURATION,
             retry_unchanged_when: None,
         },
@@ -253,8 +242,28 @@ fn source_watcher(
             let _ = events.try_send(paths);
         },
     )?;
-    // The old watcher may exclude a newly discovered include. Compare with the
-    // bytes used for rendering only after the replacement watch is active.
+    refresh_source_watcher(
+        &mut watcher,
+        source_targets(config, config_dir, config_path, dependencies),
+        dependencies,
+        &tx,
+    )?;
+    Ok(watcher)
+}
+
+/// Point the running watcher at the inputs of the build that just finished.
+///
+/// The watcher is retargeted rather than replaced: dropping it would discard
+/// source edits it observed during the build but had not debounced yet.
+fn refresh_source_watcher(
+    watcher: &mut WatcherHandle,
+    targets: WatchTargets,
+    dependencies: &StateDependencies,
+    tx: &TickSender,
+) -> Result<()> {
+    watcher.retarget(targets)?;
+    // The previous targets may exclude a newly discovered include. Compare with
+    // the bytes used for rendering only after the new subscriptions are active.
     let changed = dependencies.changed_paths();
     if !changed.is_empty() {
         match tx.try_send(changed) {
@@ -264,7 +273,39 @@ fn source_watcher(
             }
         }
     }
-    Ok(watcher)
+    Ok(())
+}
+
+/// Inputs that contribute to a build: source roots, generated includes, and
+/// projection manifests.
+fn source_targets(
+    config: &DocsConfig,
+    config_dir: &Path,
+    config_path: &Path,
+    dependencies: &StateDependencies,
+) -> WatchTargets {
+    let mut explicit_files = projection_manifest_paths(
+        config_dir,
+        config
+            .bundler
+            .as_ref()
+            .map_or(&[][..], |bundler| bundler.projection_manifests.as_slice()),
+    );
+    explicit_files.extend_from_slice(&dependencies.paths);
+    let mut ignore = default_ignore_paths();
+    ignore.push(PathBuf::from(&config.out_dir));
+    ignore.push(PathBuf::from(".webui-press/cache"));
+    ignore.push(config_dir.join(crate::scratch::PROJECT_SCRATCH_DIR));
+    WatchTargets {
+        paths: watch_paths(
+            config_dir,
+            config_path,
+            Path::new(&config.content_dir),
+            Path::new(&config.public_dir),
+        ),
+        explicit_files,
+        ignore,
+    }
 }
 
 /// Default actix handler — delegates to the shared static-file
@@ -436,6 +477,46 @@ mod tests {
         Ok(())
     }
 
+    #[test]
+    fn source_edits_during_a_watch_refresh_still_rebuild() -> Result<()> {
+        let root = tempfile::tempdir()?;
+        let content = root.path().join("content");
+        std::fs::create_dir(&content)?;
+        let page = content.join("page.md");
+        std::fs::write(&page, "# One")?;
+        let config_dir = root.path().join(".webui-press");
+        std::fs::create_dir(&config_dir)?;
+        let mut config: DocsConfig = serde_json::from_str(
+            r#"{"site":{"title":"Test"},"basePath":"/","contentDir":".","nav":[],"sidebar":[]}"#,
+        )?;
+        config.content_dir = content.to_string_lossy().into_owned();
+        config.public_dir = config.content_dir.clone();
+        let dependencies = crate::state::StateLoader::new().into_dependencies();
+        let config_path = config_dir.join("config.json");
+        let (tx, rx) = std::sync::mpsc::sync_channel(8);
+        let mut watcher = source_watcher(
+            &config,
+            &config_dir,
+            &config_path,
+            &dependencies,
+            tx.clone(),
+        )?;
+
+        // A rebuild that read the old page finishes and refreshes its watches
+        // before the debounce window reports this edit.
+        std::fs::write(&page, "# Two")?;
+        refresh_source_watcher(
+            &mut watcher,
+            source_targets(&config, &config_dir, &config_path, &dependencies),
+            &dependencies,
+            &tx,
+        )?;
+        let changed = rx.recv_timeout(Duration::from_secs(5))?;
+        assert_eq!(changed.len(), 1);
+        assert_eq!(changed[0].canonicalize()?, page.canonicalize()?);
+        Ok(())
+    }
+
     #[test]
     fn watch_paths_dedupes_nested_paths() {
         let cfg = Path::new("/proj/docs/.webui-press");

From cf9179d58ec7f8495a090a438b8ae70829e1ca87 Mon Sep 17 00:00:00 2001
From: Mohamed Mansour <hello@mohamedmansour.com>
Date: Thu, 29 Oct 2026 17:10:50 -0700
Subject: [PATCH 2/2] fix: keep nested watch roots when their ancestor fails

Retarget dropped a requested root nested inside another requested root.
When the ancestor could not be watched, the nested root was left
unwatched, contradicting retarget's best-effort contract.

Register requested roots ancestors-first and fall back to nested roots
when none of their requested ancestors can be watched. Release whatever
a failed recursive registration left behind, so a failed root leaves no
untracked subscriptions.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 crates/webui-dev-server/src/watch.rs          |  5 +-
 .../src/watch_subscriptions.rs                | 98 ++++++++++++++-----
 2 files changed, 78 insertions(+), 25 deletions(-)

diff --git a/crates/webui-dev-server/src/watch.rs b/crates/webui-dev-server/src/watch.rs
index 497bf43a6..bba738dee 100644
--- a/crates/webui-dev-server/src/watch.rs
+++ b/crates/webui-dev-server/src/watch.rs
@@ -64,8 +64,9 @@ impl WatcherHandle {
     /// # Errors
     ///
     /// Returns the first error from a path that exists but cannot be watched.
-    /// The remaining paths are still registered, and the failed path is retried
-    /// on the next retarget.
+    /// The remaining paths are still registered, including requested roots
+    /// nested inside the failed path, and the failed path is retried on the
+    /// next retarget.
     pub fn retarget(&mut self, targets: WatchTargets) -> Result<()> {
         let WatchTargets {
             paths,
diff --git a/crates/webui-dev-server/src/watch_subscriptions.rs b/crates/webui-dev-server/src/watch_subscriptions.rs
index 9211362cd..518118e16 100644
--- a/crates/webui-dev-server/src/watch_subscriptions.rs
+++ b/crates/webui-dev-server/src/watch_subscriptions.rs
@@ -28,9 +28,11 @@ impl Subscriptions {
     /// longer needed.
     ///
     /// Unchanged roots stay registered so events already observed under them
-    /// are still delivered. Exact-file parents are always re-registered: some
-    /// backends drop a subscription without an event when its directory is
-    /// deleted, and generated directories are routinely recreated.
+    /// are still delivered. A requested root nested inside another requested
+    /// root is registered only when that ancestor cannot be watched. Exact-file
+    /// parents are always re-registered: some backends drop a subscription
+    /// without an event when its directory is deleted, and generated
+    /// directories are routinely recreated.
     ///
     /// A path that cannot be watched does not stop the others from being
     /// registered; the first failure is returned afterwards.
@@ -44,33 +46,33 @@ impl Subscriptions {
             // A deleted directory may already have released its subscription.
             let _ = watcher.unwatch(&parent);
         }
-        let desired = existing_roots(paths);
+        let requested = existing_roots(paths);
         // Release roots before adding new ones: removing a recursive root also
         // removes subscriptions a new nested root would share with it.
-        let mut index = 0;
-        while index < self.roots.len() {
-            if desired
-                .iter()
-                .any(|root| root.canonical == self.roots[index].canonical)
-            {
-                index += 1;
-                continue;
+        self.roots.retain(|root| {
+            let keep = is_outermost(&requested, &root.canonical);
+            if !keep {
+                let _ = watcher.unwatch(&root.path);
             }
-            let root = self.roots.swap_remove(index);
-            let _ = watcher.unwatch(&root.path);
-        }
+            keep
+        });
         let mut failure = None;
-        for root in desired {
+        // Ancestors come first, so nested roots are reached only when none of
+        // their requested ancestors could be watched.
+        for root in requested {
             if self
                 .roots
                 .iter()
-                .any(|current| current.canonical == root.canonical)
+                .any(|current| root.canonical.starts_with(&current.canonical))
             {
                 continue;
             }
             let watched = watcher.watch(&root.path, RecursiveMode::Recursive);
             if keep_first_failure(&mut failure, watched, &root.path) {
                 self.roots.push(root);
+            } else {
+                // Release what a partial recursive registration left behind.
+                let _ = watcher.unwatch(&root.path);
             }
         }
         watch_explicit_parents(
@@ -100,7 +102,7 @@ fn keep_first_failure(
     false
 }
 
-/// Existing `paths` without entries nested inside another root.
+/// Existing `paths` without duplicates, ancestors before their descendants.
 fn existing_roots(paths: &[PathBuf]) -> Vec<Root> {
     let mut roots: Vec<Root> = Vec::with_capacity(paths.len());
     for path in paths {
@@ -108,21 +110,26 @@ fn existing_roots(paths: &[PathBuf]) -> Vec<Root> {
             continue;
         }
         let canonical = std::fs::canonicalize(path).unwrap_or_else(|_| path.clone());
-        if roots
-            .iter()
-            .any(|root| canonical.starts_with(&root.canonical))
-        {
+        if roots.iter().any(|root| root.canonical == canonical) {
             continue;
         }
-        roots.retain(|root| !root.canonical.starts_with(&canonical));
         roots.push(Root {
             path: path.clone(),
             canonical,
         });
     }
+    roots.sort_by_key(|root| root.canonical.components().count());
     roots
 }
 
+/// Whether `path` is requested and not nested inside another requested root.
+fn is_outermost(requested: &[Root], path: &Path) -> bool {
+    requested.iter().any(|root| root.canonical == path)
+        && !requested
+            .iter()
+            .any(|root| root.canonical != path && path.starts_with(&root.canonical))
+}
+
 fn watch_explicit_parents(
     watcher: &mut dyn Watcher,
     explicit_files: &[PathBuf],
@@ -236,6 +243,8 @@ mod tests {
         assert_eq!(
             watcher.calls,
             vec![
+                // Releases anything a partial recursive registration left.
+                Call::Unwatch(denied.clone()),
                 Call::Watch(content, RecursiveMode::Recursive),
                 Call::Watch(
                     std::fs::canonicalize(&state).unwrap(),
@@ -329,6 +338,49 @@ mod tests {
         );
     }
 
+    /// Subscriptions left active by the recorded calls.
+    fn active(calls: &[Call]) -> Vec<&Path> {
+        let mut active: Vec<&Path> = Vec::new();
+        for call in calls {
+            match call {
+                Call::Watch(path, _) => active.push(path.as_path()),
+                Call::Unwatch(path) => active.retain(|current| *current != path.as_path()),
+            }
+        }
+        active
+    }
+
+    #[test]
+    fn retarget_keeps_nested_roots_when_their_ancestor_cannot_be_watched() {
+        let dir = tempfile::tempdir().unwrap();
+        let docs = dir.path().join("docs");
+        let content = docs.join("content");
+        std::fs::create_dir_all(&content).unwrap();
+        let requested = [content.clone(), docs.clone()];
+        let mut watcher = RecordingWatcher::default();
+        let mut subscriptions = Subscriptions::default();
+        subscriptions
+            .retarget(&mut watcher, std::slice::from_ref(&content), &[])
+            .unwrap();
+
+        watcher.denied = Some(docs.clone());
+        let error = subscriptions
+            .retarget(&mut watcher, &requested, &[])
+            .unwrap_err();
+        assert_eq!(
+            error.to_string(),
+            format!("Cannot watch {}", docs.display())
+        );
+        assert_eq!(active(&watcher.calls), [content.as_path()]);
+
+        // The ancestor is retried and replaces its fallback once it is watchable.
+        watcher.denied = None;
+        subscriptions
+            .retarget(&mut watcher, &requested, &[])
+            .unwrap();
+        assert_eq!(active(&watcher.calls), [docs.as_path()]);
+    }
+
     #[test]
     fn retarget_follows_roots_that_disappear_and_return() {
         let dir = tempfile::tempdir().unwrap();