vendor tsgo

tools/tsgo/internal/fswatch/kqueue.go

@@ -0,0 +1,784 @@
+//go:build darwin || freebsd || openbsd || netbsd || dragonfly
+
+package fswatch
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"sync/atomic"
+
+	"golang.org/x/sys/unix"
+)
+
+// ---------------------------------------------------------------------------
+// kqueue.go: kqueue backend (macOS, FreeBSD, OpenBSD, NetBSD, DragonFlyBSD)
+//
+// Uses the kernel's kqueue/kevent mechanism to watch individual files and
+// directories via EVFILT_VNODE. Unlike inotify, kqueue requires an open file
+// descriptor per watched path, not just per directory. On macOS, O_EVTONLY
+// opens files for event monitoring only; on other BSDs, O_RDONLY is used.
+//
+//	┌──────────────────────────────────────────────────────────────┐
+//	│                       kqueueBackend                          │
+//	│                                                              │
+//	│  ┌───────────┐       kevent(2)        ┌──────────────────┐   │
+//	│  │ pipe[0]   ├───────────────────────►│                  │   │
+//	│  │ (wakeup)  │                        │  start()         │   │
+//	│  └───────────┘                        │  goroutine       │   │
+//	│  ┌───────────┐      EVFILT_VNODE      │  (event loop)    │   │
+//	│  │ kqueue    ├───────────────────────►│                  │   │
+//	│  │ fd        │                        └────────┬─────────┘   │
+//	│  └───────────┘                                 │             │
+//	│                                                ▼             │
+//	│             ┌──────────────────────────────────────────────┐ │
+//	│             │  fdToEntry:  map[fd]   → *dirEntry           │ │
+//	│             │  subsByPath: map[path] → []*kqueueSub        │ │
+//	│             │                                              │ │
+//	│             │  Each dirEntry.state stores the open fd      │ │
+//	│             └──────────────────────────────────────────────┘ │
+//	└──────────────────────────────────────────────────────────────┘
+//
+// Goroutines and threading:
+//   - One long-lived goroutine (start), launched by watcherBase.run(). It
+//     owns the kevent(2) loop and runs for the process lifetime. All event
+//     dispatch (compareDir, handleFileEvent) executes on this goroutine.
+//     compareDir and handleFileEvent acquire b.mu for watch/fd lookups.
+//   - subscribe/closeWatch run on the caller's goroutine under
+//     watcherBase.mu. watchPath acquires b.mu to register fd mappings.
+//
+// Callback delivery:
+//   dirWatch.notify() posts to the shared process-wide debouncer. After a
+//   coalescing window (50 ms min / 500 ms max), the debouncer invokes all
+//   registered WatchCallbacks on its own dedicated goroutine; never on
+//   the caller's goroutine or the event-loop goroutine.
+//
+// WatchDirectory flow:
+//  1. Walk the target directory, building a path→dirEntry map (caller goroutine).
+//  2. For every entry (file or directory), open an fd and register it with
+//     kqueue for EVFILT_VNODE events (NOTE_DELETE, NOTE_WRITE, NOTE_EXTEND,
+//     NOTE_ATTRIB, NOTE_RENAME, NOTE_REVOKE). Store the fd↔dirEntry mapping.
+//
+// Event dispatch (on the start goroutine):
+//   - NOTE_WRITE on a directory → compareDir: re-read the directory from
+//     disk, diff against the in-memory tree, emit update events for new
+//     entries (opening + watching them) and delete events for removed ones
+//     (closing their fds).
+//   - NOTE_DELETE / NOTE_RENAME / NOTE_REVOKE → close the stale fd. For a
+//     pure NOTE_DELETE on a file, tryRewatchLocked checks whether the path
+//     was immediately recreated (atomic-save pattern) and emits update
+//     instead of delete if so. Otherwise emit delete and remove from the
+//     tree. Directories skip tryRewatchLocked to avoid spurious updates
+//     during RemoveAll races.
+//   - NOTE_WRITE / NOTE_ATTRIB / NOTE_EXTEND on a file → emit update.
+//   After processing all returned kevents, call dirWatch.notify() on each
+//   touched dirWatch to trigger the debouncer.
+//
+// Shutdown:
+//   Write a byte to pipe[1] → kevent sees the pipe fd → loop exits →
+//   close all tracked fds, the kqueue fd, and the pipe.
+// ---------------------------------------------------------------------------
+
+// openForEvents opens a path for kqueue event monitoring. On darwin, O_EVTONLY
+// opens the file for event notification without granting read access. On other
+// BSDs, falls back to O_RDONLY.
+func openForEvents(path string) (int, error) {
+	flags := unix.O_RDONLY
+	if runtime.GOOS == "darwin" {
+		flags = 0x8000 // O_EVTONLY, darwin-only
+	}
+	return unix.Open(path, flags, 0)
+}
+
+// dirEntry tracks a watched path for kqueue's fd↔path mapping.
+type dirEntry struct {
+	path      string
+	watchPath string
+	isDir     bool
+	state     any // stores the open fd
+}
+
+// kqueueSubscription.
+type kqueueSubscription struct {
+	dirWatch *dirWatch
+	path     string
+	entries  map[string]*dirEntry
+	fd       int
+}
+
+// kqueueBackend. It embeds treeReaderBackend (via Go
+// composition) just like the inheritance hierarchy.
+type kqueueBackend struct {
+	watcherBase
+
+	mu sync.Mutex // local lock for kqueue-specific maps
+	kq int
+	// pipeFDs[0] is read in the Start goroutine only. pipeFDs[1] is written
+	// by Shutdown (any goroutine) to wake the loop, so it lives in
+	// pipeWriteFD as an atomic with a sentinel of -1 once closed.
+	pipeFDs     [2]int
+	pipeWriteFD atomic.Int32
+	subsByPath  map[string][]*kqueueSubscription // multimap<path, sub>
+	fdToEntry   map[int]*dirEntry
+	endedSignal chan struct{}
+
+	// Persistent buffer reused across event batches. Only accessed
+	// from the start goroutine, so no synchronization needed.
+	watchersTouched map[*dirWatch]struct{}
+}
+
+func init() {
+	kqueueWatcher.factory = func() watcherImpl { return newKqueueBackend() }
+}
+
+func newKqueueBackend() *kqueueBackend {
+	b := &kqueueBackend{
+		kq:              -1,
+		pipeFDs:         [2]int{-1, -1},
+		subsByPath:      map[string][]*kqueueSubscription{},
+		fdToEntry:       map[int]*dirEntry{},
+		endedSignal:     make(chan struct{}),
+		watchersTouched: make(map[*dirWatch]struct{}),
+	}
+	b.pipeWriteFD.Store(-1)
+	b.watcherBase.init(b)
+	return b
+}
+
+func (b *kqueueBackend) start() error {
+	kq, err := unix.Kqueue()
+	if err != nil {
+		return fmt.Errorf("unable to open kqueue: %w", err)
+	}
+	b.kq = kq
+	defer func() {
+		b.closeSubscriptions()
+		b.closeFDs()
+		close(b.endedSignal)
+	}()
+
+	if err := unix.Pipe(b.pipeFDs[:]); err != nil {
+		return fmt.Errorf("unable to open pipe: %w", err)
+	}
+	b.pipeWriteFD.Store(int32(b.pipeFDs[1]))
+
+	// WatchDirectory kqueue to the read side of the pipe so we can break the
+	// loop on shutdown. SetKevent handles the per-arch Ident type
+	// (uint64 on 64-bit, uint32 on 386/arm).
+	var pipeEv unix.Kevent_t
+	unix.SetKevent(&pipeEv, b.pipeFDs[0], unix.EVFILT_READ, unix.EV_ADD|unix.EV_CLEAR)
+	if _, err := unix.Kevent(kq, []unix.Kevent_t{pipeEv}, nil, nil); err != nil {
+		return fmt.Errorf("unable to watch pipe: %w", err)
+	}
+
+	b.notifyStarted()
+
+	events := make([]unix.Kevent_t, 128)
+	for {
+		n, err := unix.Kevent(kq, nil, events, nil)
+		if err != nil {
+			if err == unix.EINTR {
+				continue
+			}
+			return fmt.Errorf("kevent error: %w", err)
+		}
+
+		watchersTouched := b.watchersTouched
+		stop := false
+		for i := range n {
+			fflags := events[i].Fflags
+			flags := events[i].Flags
+			fd := int(events[i].Ident)
+			if fd == b.pipeFDs[0] {
+				stop = true
+				break
+			}
+
+			// EV_ERROR indicates kevent couldn't apply a changelist
+			// entry or that the kernel rejected the registration.
+			// Data carries the errno. Skip dispatching as a normal
+			// event since fflags are not meaningful in this case.
+			if flags&unix.EV_ERROR != 0 {
+				continue
+			}
+
+			b.mu.Lock()
+			entry, ok := b.fdToEntry[fd]
+			b.mu.Unlock()
+			if !ok || entry == nil {
+				continue
+			}
+
+			if fflags&unix.NOTE_WRITE != 0 && entry.isDir {
+				b.compareDir(fd, entry.path, watchersTouched)
+				// NOTE_WRITE on a dir already ran compareDir above.
+				// On DragonFlyBSD, rename-over coalesces NOTE_DELETE
+				// with NOTE_WRITE on the parent directory (rather than
+				// firing NOTE_DELETE on the replaced file's fd).
+				// Skip handleFileEvent so we don't misinterpret the
+				// coalesced NOTE_DELETE as the directory itself being
+				// removed.
+				fflags &^= unix.NOTE_DELETE
+			}
+			if fflags&^unix.NOTE_WRITE != 0 || !entry.isDir {
+				b.handleFileEvent(fflags, entry, watchersTouched)
+			}
+		}
+
+		for w := range watchersTouched {
+			w.notify()
+		}
+		clear(watchersTouched)
+		if stop {
+			break
+		}
+	}
+
+	return nil
+}
+
+func (b *kqueueBackend) closeFDs() {
+	if b.pipeFDs[0] >= 0 {
+		_ = unix.Close(b.pipeFDs[0])
+		b.pipeFDs[0] = -1
+	}
+	if fd := b.pipeWriteFD.Swap(-1); fd >= 0 {
+		_ = unix.Close(int(fd))
+	}
+	b.pipeFDs[1] = -1
+	if b.kq >= 0 {
+		_ = unix.Close(b.kq)
+		b.kq = -1
+	}
+}
+
+func (b *kqueueBackend) closeSubscriptions() {
+	b.mu.Lock()
+	seenFDs := map[int]struct{}{}
+	for _, list := range b.subsByPath {
+		for _, sub := range list {
+			if sub.fd < 0 {
+				continue
+			}
+			if _, ok := seenFDs[sub.fd]; ok {
+				continue
+			}
+			seenFDs[sub.fd] = struct{}{}
+			_ = unix.Close(sub.fd)
+		}
+	}
+	b.subsByPath = map[string][]*kqueueSubscription{}
+	b.fdToEntry = map[int]*dirEntry{}
+	b.mu.Unlock()
+}
+
+func (b *kqueueBackend) shutdown() {
+	fd := b.pipeWriteFD.Load()
+	if fd < 0 {
+		return
+	}
+	_, _ = unix.Write(int(fd), []byte{'X'})
+	<-b.endedSignal
+}
+
+func (b *kqueueBackend) handleFileEvent(fflags uint32, entry *dirEntry, touched map[*dirWatch]struct{}) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	subs := b.findSubscriptionsLocked(entry.path)
+
+	if fflags&(unix.NOTE_DELETE|unix.NOTE_RENAME|unix.NOTE_REVOKE) != 0 {
+		// Close the stale fd; the watched inode is gone.
+		if oldFD, ok := entry.state.(int); ok {
+			unix.Close(oldFD)
+			delete(b.fdToEntry, oldFD)
+			entry.state = nil
+		}
+
+		recreated := false
+		if fflags&unix.NOTE_DELETE != 0 && fflags&(unix.NOTE_RENAME|unix.NOTE_REVOKE) == 0 && !entry.isDir {
+			recreated = b.tryRewatchLocked(entry)
+		}
+
+		for _, sub := range subs {
+			touched[sub.dirWatch] = struct{}{}
+			if recreated {
+				sub.dirWatch.events.update(sub.path)
+			} else {
+				sub.dirWatch.events.remove(sub.path)
+				// If we lost a directory, walk the entries map and
+				// close every fd we had open for descendants. Some
+				// kernels (OpenBSD in particular) deliver only the
+				// parent's NOTE_DELETE/NOTE_RENAME and never fire
+				// NOTE_DELETE on the children; without this cleanup,
+				// modifying a file inside the moved tree later
+				// surfaces an event against the descendant's stale
+				// (pre-rename) path. We also emit a delete for each
+				// descendant we close, so callers don't miss those
+				// removals if the kernel didn't fire per-child events.
+				// (When the kernel does fire them, our follow-up
+				// handleFileEvent finds the fd already gone and is a
+				// no-op, so events.create's coalescing handles dups.)
+				if entry.isDir {
+					b.closeDescendantFDsLocked(sub.dirWatch, sub.entries, sub.path)
+				}
+				removeEntryAndDescendants(sub.entries, sub.path)
+				// Root-of-watch deletion: no more events can fire
+				// for this dirWatch. Tell the caller.
+				if sub.path == sub.dirWatch.dir {
+					sub.dirWatch.events.setError(fmt.Errorf("%w: watched directory removed", ErrWatchTerminated))
+				}
+			}
+		}
+		if !recreated {
+			delete(b.subsByPath, entry.path)
+		}
+		return
+	}
+
+	for _, sub := range subs {
+		touched[sub.dirWatch] = struct{}{}
+		if fflags&(unix.NOTE_WRITE|unix.NOTE_ATTRIB|unix.NOTE_EXTEND) != 0 {
+			sub.dirWatch.events.update(sub.path)
+		}
+	}
+}
+
+// closeDescendantFDsLocked closes every fd attached to an entry whose
+// path lives strictly under root, removing the kevent registration and
+// the corresponding b.subsByPath / b.fdToEntry bookkeeping, and emits a
+// delete event for each. Used when a directory's parent is lost
+// (deleted, renamed away) and the kernel didn't propagate the loss to
+// children. eventList coalesces against any per-child NOTE_DELETE that
+// arrives later.
+func (b *kqueueBackend) closeDescendantFDsLocked(w *dirWatch, entries map[string]*dirEntry, root string) {
+	prefix := root + string(filepath.Separator)
+	for path, e := range entries {
+		if !strings.HasPrefix(path, prefix) {
+			continue
+		}
+		if fd, ok := e.state.(int); ok {
+			unix.Close(fd)
+			delete(b.fdToEntry, fd)
+			e.state = nil
+		}
+		delete(b.subsByPath, path)
+		w.events.remove(path)
+	}
+}
+
+// tryRewatchLocked checks whether a deleted path was immediately recreated
+// with the same type. If so, it opens a new fd, registers a kqueue watch,
+// and returns true. The caller should emit update instead of delete.
+func (b *kqueueBackend) tryRewatchLocked(entry *dirEntry) bool {
+	var st unix.Stat_t
+	if unix.Lstat(entry.watchPath, &st) != nil {
+		return false
+	}
+
+	// Only fast-path when the recreated path has the same type;
+	// a file→dir change needs a full tree rebuild via compareDir.
+	newIsDir := st.Mode&unix.S_IFMT == unix.S_IFDIR
+	if newIsDir != entry.isDir {
+		return false
+	}
+
+	fd, err := openForEvents(entry.watchPath)
+	if err != nil {
+		return false
+	}
+
+	var ev unix.Kevent_t
+	unix.SetKevent(&ev, fd, unix.EVFILT_VNODE, unix.EV_ADD|unix.EV_CLEAR|unix.EV_ENABLE)
+	ev.Fflags = unix.NOTE_DELETE | unix.NOTE_WRITE | unix.NOTE_EXTEND |
+		unix.NOTE_ATTRIB | unix.NOTE_RENAME | unix.NOTE_REVOKE
+	if _, err := unix.Kevent(b.kq, []unix.Kevent_t{ev}, nil, nil); err != nil {
+		unix.Close(fd)
+		return false
+	}
+
+	entry.state = fd
+
+	b.fdToEntry[fd] = entry
+	return true
+}
+
+func (b *kqueueBackend) closeEntryLocked(entry *dirEntry) {
+	if fd, ok := entry.state.(int); ok {
+		unix.Close(fd)
+		delete(b.fdToEntry, fd)
+		entry.state = nil
+	}
+}
+
+func (b *kqueueBackend) removeSubsForEntriesLocked(path string, entriesPtr *map[string]*dirEntry) {
+	list := b.subsByPath[path]
+	kept := list[:0]
+	for _, sub := range list {
+		if &sub.entries == entriesPtr {
+			continue
+		}
+		kept = append(kept, sub)
+	}
+	if len(kept) == 0 {
+		delete(b.subsByPath, path)
+	} else {
+		b.subsByPath[path] = kept
+	}
+}
+
+func (b *kqueueBackend) removeEntryAndDescendantsLocked(entriesPtr *map[string]*dirEntry, path string, includeRoot bool) {
+	entries := *entriesPtr
+	for descendant, e := range entries {
+		if descendant == path {
+			if !includeRoot {
+				continue
+			}
+		} else if !(len(descendant) > len(path) && descendant[len(path)] == filepath.Separator && descendant[:len(path)] == path) {
+			continue
+		}
+		b.closeEntryLocked(e)
+		b.removeSubsForEntriesLocked(descendant, entriesPtr)
+		delete(entries, descendant)
+	}
+}
+
+func (b *kqueueBackend) findSubscriptionsLocked(path string) []*kqueueSubscription {
+	subs := b.subsByPath[path]
+	out := make([]*kqueueSubscription, len(subs))
+	copy(out, subs)
+	return out
+}
+
+// subscribe mirrors `kqueueBackend::subscribe`. Called under watcherBase.mu
+// via watchAdd.
+func (b *kqueueBackend) subscribe(w *dirWatch) error {
+	// Build the entries map without registering any watches or
+	// subscriptions. This avoids a data race: registering a subscription
+	// publishes the entries map to the event loop (via subsByPath),
+	// which could read it via compareDir while we're still populating it.
+	entries := map[string]*dirEntry{}
+	if err := walkDir(w.physicalDir, w.recursive, func(watchPath string, isDir bool) error {
+		path := w.displayPath(watchPath)
+		entries[path] = &dirEntry{path: path, watchPath: watchPath, isDir: isDir}
+		return nil
+	}); err != nil {
+		return err
+	}
+
+	// Open fds, register kevents, and publish subscriptions under b.mu.
+	// Holding the lock for the entire block ensures that the event loop
+	// cannot see a partially-built entries map, and that fds are always
+	// tracked in fdToEntry (no leak on early return).
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	for path, entry := range entries {
+		fd, err := openForEvents(entry.watchPath)
+		if err != nil {
+			if path == w.dir {
+				b.cleanupEntriesLocked(entries)
+				return &dirWatchError{
+					err:      fmt.Errorf("error watching %s: %w", w.dir, err),
+					dirWatch: w,
+				}
+			}
+			delete(entries, path)
+			continue
+		}
+		var ev unix.Kevent_t
+		unix.SetKevent(&ev, fd, unix.EVFILT_VNODE, unix.EV_ADD|unix.EV_CLEAR|unix.EV_ENABLE)
+		ev.Fflags = unix.NOTE_DELETE | unix.NOTE_WRITE | unix.NOTE_EXTEND |
+			unix.NOTE_ATTRIB | unix.NOTE_RENAME | unix.NOTE_REVOKE
+		if _, err := unix.Kevent(b.kq, []unix.Kevent_t{ev}, nil, nil); err != nil {
+			unix.Close(fd)
+			if path == w.dir {
+				b.cleanupEntriesLocked(entries)
+				return &dirWatchError{
+					err:      fmt.Errorf("error watching %s: %w", w.dir, err),
+					dirWatch: w,
+				}
+			}
+			delete(entries, path)
+			continue
+		}
+		entry.state = fd
+		b.fdToEntry[fd] = entry
+	}
+
+	for path, entry := range entries {
+		fd := entry.state.(int)
+		sub := &kqueueSubscription{dirWatch: w, path: path, entries: entries, fd: fd}
+		b.subsByPath[path] = append(b.subsByPath[path], sub)
+	}
+	return nil
+}
+
+// cleanupEntriesLocked closes fds for all entries that have been opened.
+// Called on subscribe failure to avoid fd leaks. Must be called under b.mu.
+func (b *kqueueBackend) cleanupEntriesLocked(entries map[string]*dirEntry) {
+	for _, e := range entries {
+		if fd, ok := e.state.(int); ok {
+			unix.Close(fd)
+			delete(b.fdToEntry, fd)
+			e.state = nil
+		}
+	}
+}
+
+// watchPath corresponds to `kqueueBackend::watchDir`.
+func (b *kqueueBackend) watchPath(w *dirWatch, path string, entries map[string]*dirEntry) bool {
+	entry := entries[path]
+	if entry == nil {
+		return false
+	}
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	sub := &kqueueSubscription{dirWatch: w, path: path, entries: entries}
+	if entry.state == nil {
+		fd, err := openForEvents(entry.watchPath)
+		if err != nil {
+			return false
+		}
+		var ev unix.Kevent_t
+		unix.SetKevent(&ev, fd, unix.EVFILT_VNODE, unix.EV_ADD|unix.EV_CLEAR|unix.EV_ENABLE)
+		ev.Fflags = unix.NOTE_DELETE | unix.NOTE_WRITE | unix.NOTE_EXTEND |
+			unix.NOTE_ATTRIB | unix.NOTE_RENAME | unix.NOTE_REVOKE
+		if _, err := unix.Kevent(b.kq, []unix.Kevent_t{ev}, nil, nil); err != nil {
+			unix.Close(fd)
+			return false
+		}
+		entry.state = fd
+		b.fdToEntry[fd] = entry
+	}
+	sub.fd = entry.state.(int)
+	b.subsByPath[path] = append(b.subsByPath[path], sub)
+	return true
+}
+
+// compareDir mirrors `kqueueBackend::compareDir`. Triggered when a watched
+// directory has NOTE_WRITE: list the dir, diff against the tree, emit
+// create/remove events.
+func (b *kqueueBackend) compareDir(_ int, path string, touched map[*dirWatch]struct{}) bool {
+	b.mu.Lock()
+	subs := b.findSubscriptionsLocked(path)
+	b.mu.Unlock()
+
+	// For non-recursive subscriptions, only compareDir on the root dir.
+	// NOTE_WRITE on a child dir means something changed inside it, but
+	// non-recursive mode shouldn't report those changes. Emit an update
+	// for the child dir itself (its metadata changed) and return.
+	filteredSubs := subs[:0:0]
+	for _, s := range subs {
+		if !s.dirWatch.recursive && path != s.dirWatch.dir {
+			s.dirWatch.events.update(path)
+			touched[s.dirWatch] = struct{}{}
+		} else {
+			filteredSubs = append(filteredSubs, s)
+		}
+	}
+	if len(filteredSubs) == 0 {
+		return true
+	}
+	subs = filteredSubs
+
+	dirStart := path + string(filepath.Separator)
+	type diskSnapshot struct {
+		entries             []os.DirEntry
+		currentDisplayPaths map[string]struct{}
+	}
+	snapshots := map[string]diskSnapshot{}
+
+	// Each subscription has its own entries map (built in subscribe).
+	// Multiple subs at the same path arise from multiple dirWatches
+	// covering overlapping subtrees; their maps are always distinct, so
+	// we iterate subs directly rather than trying to dedup by map identity.
+	for _, sub := range subs {
+		baseEntry := sub.entries[path]
+		if baseEntry == nil {
+			continue
+		}
+		watchPath := baseEntry.watchPath
+		watchDirStart := watchPath + string(filepath.Separator)
+
+		snapshot, ok := snapshots[watchPath]
+		if !ok {
+			diskEntries, err := readEntries(watchPath)
+			if err != nil {
+				continue
+			}
+			snapshot.entries = diskEntries
+			snapshot.currentDisplayPaths = make(map[string]struct{}, len(diskEntries))
+			for _, ent := range diskEntries {
+				snapshot.currentDisplayPaths[dirStart+ent.Name()] = struct{}{}
+			}
+			snapshots[watchPath] = snapshot
+		}
+
+		entries := sub.entries
+		for _, ent := range snapshot.entries {
+			fullPath := dirStart + ent.Name()
+			fullWatchPath := watchDirStart + ent.Name()
+
+			existing := entries[fullPath]
+			if existing != nil {
+				if existing.state != nil {
+					// Check if the fd still refers to the same inode as
+					// the path on disk. On DragonFlyBSD, rename-over
+					// doesn't fire NOTE_DELETE on the replaced file's fd,
+					// leaving a stale entry whose fd points to the old
+					// (now unlinked) inode.
+					if fd, ok := existing.state.(int); ok {
+						var fdSt, pathSt unix.Stat_t
+						if unix.Fstat(fd, &fdSt) == nil && unix.Lstat(fullWatchPath, &pathSt) == nil {
+							if fdSt.Dev != pathSt.Dev || fdSt.Ino != pathSt.Ino {
+								// Inode changed: path was replaced.
+								b.mu.Lock()
+								b.closeEntryLocked(existing)
+								b.removeSubsForEntriesLocked(fullPath, &sub.entries)
+								if existing.isDir {
+									b.removeEntryAndDescendantsLocked(&sub.entries, fullPath, false)
+								}
+								existing.isDir = ent.IsDir()
+								b.mu.Unlock()
+							}
+						}
+					}
+				}
+				if existing.state != nil {
+					continue
+				}
+				// Entry exists but fd is stale: the file was replaced.
+				// Re-watch it and emit an update.
+				if !b.watchPath(sub.dirWatch, fullPath, entries) {
+					continue
+				}
+				sub.dirWatch.events.update(fullPath)
+				touched[sub.dirWatch] = struct{}{}
+				if ent.IsDir() && sub.dirWatch.recursive {
+					_ = walkDir(fullWatchPath, true, func(p string, pIsDir bool) error {
+						if p == fullWatchPath {
+							return nil
+						}
+						displayPath := sub.dirWatch.displayPath(p)
+						e := &dirEntry{path: displayPath, watchPath: p, isDir: pIsDir}
+						entries[displayPath] = e
+						sub.dirWatch.events.create(displayPath)
+						b.watchPath(sub.dirWatch, displayPath, entries)
+						return nil
+					})
+				}
+				continue
+			}
+			e := &dirEntry{path: fullPath, watchPath: fullWatchPath, isDir: ent.IsDir()}
+			entries[fullPath] = e
+			if !b.watchPath(sub.dirWatch, fullPath, entries) {
+				delete(entries, fullPath)
+				continue
+			}
+			sub.dirWatch.events.create(fullPath)
+			touched[sub.dirWatch] = struct{}{}
+
+			// For recursive subscriptions, walk into the new directory
+			// to catch pre-populated subdirectories (e.g. a directory
+			// tree moved into the watched area).
+			if ent.IsDir() && sub.dirWatch.recursive {
+				_ = walkDir(fullWatchPath, true, func(p string, pIsDir bool) error {
+					if p == fullWatchPath {
+						return nil // already handled above
+					}
+					displayPath := sub.dirWatch.displayPath(p)
+					entry := &dirEntry{path: displayPath, watchPath: p, isDir: pIsDir}
+					entries[displayPath] = entry
+					sub.dirWatch.events.create(displayPath)
+					b.watchPath(sub.dirWatch, displayPath, entries)
+					return nil
+				})
+			}
+		}
+
+		// Detect removals: entries directly under dirStart that no longer
+		// exist on disk.
+		var toRemove []string
+		for p := range entries {
+			if !strings.HasPrefix(p, dirStart) {
+				continue
+			}
+			rest := p[len(dirStart):]
+			if strings.Contains(rest, string(filepath.Separator)) {
+				continue
+			}
+			if _, ok := snapshot.currentDisplayPaths[p]; ok {
+				continue
+			}
+			toRemove = append(toRemove, p)
+		}
+		for _, p := range toRemove {
+			sub.dirWatch.events.remove(p)
+			touched[sub.dirWatch] = struct{}{}
+			b.mu.Lock()
+			for descendant, e := range entries {
+				if descendant != p && !(len(descendant) > len(p) && descendant[len(p)] == filepath.Separator && descendant[:len(p)] == p) {
+					continue
+				}
+				if fd, ok := e.state.(int); ok {
+					unix.Close(fd)
+					delete(b.fdToEntry, fd)
+				}
+				delete(b.subsByPath, descendant)
+			}
+			b.mu.Unlock()
+			removeEntryAndDescendants(entries, p)
+		}
+	}
+	return true
+}
+
+// readEntries lists directory entries (excluding "." and "..") at path.
+func readEntries(path string) ([]os.DirEntry, error) {
+	return os.ReadDir(path)
+}
+
+// closeWatch mirrors `kqueueBackend::closeWatch`.
+func (b *kqueueBackend) closeWatch(w *dirWatch) error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	for path, list := range b.subsByPath {
+		kept := list[:0]
+		removedAny := false
+		for _, s := range list {
+			if s.dirWatch == w {
+				removedAny = true
+				continue
+			}
+			kept = append(kept, s)
+		}
+		if !removedAny {
+			continue
+		}
+		if len(kept) == 0 {
+			// Closing the file descriptor automatically unwatches it in kqueue.
+			fd := list[0].fd
+			unix.Close(fd)
+			delete(b.fdToEntry, fd)
+			delete(b.subsByPath, path)
+		} else {
+			b.subsByPath[path] = kept
+		}
+	}
+	return nil
+}
+
+// removeEntryAndDescendants removes path and all paths prefixed with
+// path + separator from the entries map.
+func removeEntryAndDescendants(entries map[string]*dirEntry, path string) {
+	delete(entries, path)
+	for k := range entries {
+		if len(k) > len(path) && k[len(path)] == filepath.Separator && k[:len(path)] == path {
+			delete(entries, k)
+		}
+	}
+}