@harperfast/harper 5.2.0-beta.4 → 5.2.1

package/components/EntryHandler.ts

@@ -1,7 +1,8 @@
 import { type Logger } from '../utility/logging/logger.ts';
 import { loggerWithTag } from '../utility/logging/harper_logger.ts';
+import { createHash } from 'node:crypto';
 import type { Stats } from 'node:fs';
-import { EventEmitter, once } from 'node:events';
+import { EventEmitter } from 'node:events';
 import { Component, FileAndURLPathConfig } from './Component.ts';
 import chokidar, { FSWatcher, FSWatcherEventMap } from 'chokidar';
 import { join } from 'node:path';
@@ -74,25 +75,39 @@ export type EntryHandlerEventMap = {
 	unlinkDir: [entry: UnlinkDirectoryEvent];
 };
 
+type EntrySnapshot =
+	{ entryType: 'file'; urlPath: string; digest: Buffer } | { entryType: 'directory'; urlPath: string };
+
+type RedeployScan = {
+	generation: number;
+	previousEntries: Map<string, EntrySnapshot>;
+	currentEntries: Map<string, EntrySnapshot>;
+	removalsEmitted: Set<string>;
+	readFailures: Map<string, unknown>;
+};
+
 export class EntryHandler extends EventEmitter<EntryHandlerEventMap> {
 	#component: Component;
 	#watcher?: FSWatcher;
 	#logger: Logger;
 	#pendingFileReads: Set<Promise<void>>;
+	#pendingFileReadsByGeneration: Map<number, Set<Promise<void>>>;
 	#isInitialScanComplete: boolean;
-	// When true, #watch() short-circuits without creating a chokidar watcher.
-	// pause() sets it, resume() clears it. Lets a deploy quiesce the watcher
-	// without losing the EntryHandler instance (and therefore listener
-	// attachments registered by plugins via scope.handleEntry(handler)).
-	#paused: boolean = false;
-	// Tracks the in-flight close() promise from pause() so resume() can await
-	// the old watcher's inotify handles releasing before installing a fresh
-	// chokidar instance — otherwise a rapid pause→resume can overlap teardown
-	// and setup, which under inotify pressure can produce spurious EMFILE.
+	#readyPending = false;
+	#readyGeneration = 0;
+	#watchGeneration = 0;
+	#eventSequence = 0;
+	#latestPathSequence = new Map<string, number>();
+	#entries = new Map<string, EntrySnapshot>();
+	#redeployScan?: RedeployScan;
+	#paused = false;
 	#pausedClose?: Promise<void>;
-	#usingPolling: boolean = false;
-	#closed: boolean = false;
-	#openCount: number = 0;
+	// Serializes replacements so concurrent update/recovery calls cannot orphan an intervening watcher.
+	#watchInstall?: Promise<void>;
+	#usingPolling = false;
+	#closed = false;
+	#openCount = 0;
+	#liveWatchers = new Set<FSWatcher>();
 	ready: Promise<any[]>;
 
 	constructor(name: string, directory: string, config: FilesOption | FileAndURLPathConfig, logger?: Logger) {
@@ -101,9 +116,40 @@ export class EntryHandler extends EventEmitter<EntryHandlerEventMap> {
 		this.#component = new Component(name, directory, castConfig(config));
 		this.#logger = logger || loggerWithTag(name);
 		this.#pendingFileReads = new Set();
+		this.#pendingFileReadsByGeneration = new Map();
 		this.#isInitialScanComplete = false;
-		this.ready = once(this, 'ready');
-		this.#watch();
+		this.ready = this.#createReadyLatch();
+		this.#watch().catch(() => {});
+	}
+
+	#createReadyLatch(): Promise<any[]> {
+		if (this.#readyPending) return this.ready;
+		this.#readyPending = true;
+		const ready = new Promise<any[]>((resolve, reject) => {
+			const cleanup = () => {
+				this.#readyPending = false;
+				this.off('ready', handleReady);
+				this.off('error', handleError);
+				this.off('close', handleClose);
+			};
+			const handleReady = () => {
+				cleanup();
+				resolve([]);
+			};
+			const handleError = (error: unknown) => {
+				cleanup();
+				reject(error);
+			};
+			const handleClose = () => {
+				cleanup();
+				reject(new Error(`Entry handler for ${this.name} closed before becoming ready`));
+			};
+			this.once('ready', handleReady);
+			this.once('error', handleError);
+			this.once('close', handleClose);
+		});
+		void ready.catch(() => {});
+		return ready;
 	}
 
 	get name(): string {
@@ -114,7 +160,8 @@ export class EntryHandler extends EventEmitter<EntryHandlerEventMap> {
 		return this.#component.directory;
 	}
 
-	#handleAll(...[event, path, stats]: FSWatcherEventMap['all']): void {
+	#handleAll(generation: number, ...[event, path, stats]: FSWatcherEventMap['all']): void {
+		if (generation !== this.#watchGeneration) return;
 		if (path === '') path = '/';
 
 		if (!isMatch(path, this.#component.globOptions.source, { ignore: this.#component.globOptions.ignore })) return;
@@ -124,26 +171,7 @@ export class EntryHandler extends EventEmitter<EntryHandlerEventMap> {
 		switch (event) {
 			case 'add':
 			case 'change': {
-				const urlPath = deriveURLPath(this.#component, path, 'file');
-				const fileReadPromise = readFile(absolutePath)
-					.then((contents) => {
-						const entry: AddFileEvent | ChangeFileEvent = {
-							eventType: event,
-							entryType: 'file' as const,
-							contents,
-							stats,
-							absolutePath,
-							urlPath,
-						};
-						this.emit('all', entry);
-						this.emit(event, entry as any);
-					})
-					.finally(() => {
-						this.#pendingFileReads.delete(fileReadPromise);
-						this.#checkIfAllComplete();
-					});
-
-				this.#pendingFileReads.add(fileReadPromise);
+				this.#queueFileRead(generation, event, path, absolutePath, stats, readFile(absolutePath));
 				break;
 			}
 			case 'unlink': {
@@ -155,28 +183,214 @@ export class EntryHandler extends EventEmitter<EntryHandlerEventMap> {
 					absolutePath,
 					urlPath,
 				};
-				this.emit('all', entry);
-				this.emit(event, entry);
+				this.#handleRemovedEntry(generation, entry);
 				break;
 			}
 			case 'addDir':
 			case 'unlinkDir': {
 				const urlPath = deriveURLPath(this.#component, path, 'directory');
-				const entry: DirectoryEntryEvent = {
-					eventType: event,
-					entryType: 'directory' as const,
-					stats,
-					absolutePath,
-					urlPath,
-				};
-				this.emit('all', entry);
-				this.emit(event, entry as any);
+				if (event === 'addDir') {
+					const entry: AddDirectoryEvent = {
+						eventType: event,
+						entryType: 'directory',
+						stats,
+						absolutePath,
+						urlPath,
+					};
+					this.#handleAddedEntry(generation, entry, this.#snapshot(entry));
+				} else {
+					const entry: UnlinkDirectoryEvent = {
+						eventType: event,
+						entryType: 'directory',
+						stats,
+						absolutePath,
+						urlPath,
+					};
+					this.#handleRemovedEntry(generation, entry);
+				}
 				break;
 			}
 		}
 	}
 
-	#handleError(error: unknown): void {
+	#queueFileRead(
+		generation: number,
+		event: 'add' | 'change',
+		path: string,
+		absolutePath: string,
+		stats: Stats | undefined,
+		contentsPromise: Promise<Buffer>
+	): Promise<void> {
+		const sequence = ++this.#eventSequence;
+		this.#latestPathSequence.set(absolutePath, sequence);
+
+		const fileReadPromise = contentsPromise
+			.then(
+				(contents) => {
+					if (generation !== this.#watchGeneration || this.#latestPathSequence.get(absolutePath) !== sequence) return;
+					if (this.#redeployScan?.generation === generation) this.#redeployScan.readFailures.delete(absolutePath);
+					const entry: AddFileEvent | ChangeFileEvent = {
+						eventType: event,
+						entryType: 'file',
+						contents,
+						stats,
+						absolutePath,
+						urlPath: deriveURLPath(this.#component, path, 'file'),
+					};
+					try {
+						this.#handleAddedEntry(generation, entry, this.#snapshot(entry));
+					} catch (error) {
+						this.#reportConsumerError(error);
+					}
+				},
+				(error) => {
+					if (
+						generation !== this.#watchGeneration ||
+						this.#latestPathSequence.get(absolutePath) !== sequence ||
+						(error as NodeJS.ErrnoException | null | undefined)?.code === 'ENOENT'
+					)
+						return;
+					if (this.#redeployScan?.generation === generation) {
+						this.#redeployScan.readFailures.set(absolutePath, error);
+					} else {
+						this.#handleWatcherError(error);
+					}
+				}
+			)
+			.finally(() => {
+				if (this.#latestPathSequence.get(absolutePath) === sequence) this.#latestPathSequence.delete(absolutePath);
+				this.#pendingFileReads.delete(fileReadPromise);
+				const generationReads = this.#pendingFileReadsByGeneration.get(generation);
+				generationReads?.delete(fileReadPromise);
+				if (generationReads?.size === 0) this.#pendingFileReadsByGeneration.delete(generation);
+				this.#checkIfAllComplete(generation);
+			});
+
+		this.#pendingFileReads.add(fileReadPromise);
+		let generationReads = this.#pendingFileReadsByGeneration.get(generation);
+		if (!generationReads) this.#pendingFileReadsByGeneration.set(generation, (generationReads = new Set()));
+		generationReads.add(fileReadPromise);
+		return fileReadPromise;
+	}
+
+	#snapshot(entry: AddFileEvent | ChangeFileEvent | AddDirectoryEvent): EntrySnapshot {
+		if (entry.entryType === 'file')
+			return {
+				entryType: entry.entryType,
+				urlPath: entry.urlPath,
+				digest: createHash('sha256').update(entry.contents).digest(),
+			};
+		return { entryType: entry.entryType, urlPath: entry.urlPath };
+	}
+
+	#handleAddedEntry(
+		generation: number,
+		entry: AddFileEvent | ChangeFileEvent | AddDirectoryEvent,
+		snapshot: EntrySnapshot
+	): void {
+		if (generation !== this.#watchGeneration) return;
+		const scan = this.#redeployScan?.generation === generation ? this.#redeployScan : undefined;
+		if (!scan) {
+			const wasKnown = this.#entries.has(entry.absolutePath);
+			this.#entries.set(entry.absolutePath, snapshot);
+			// A newer change read can supersede an initial add read for the same path. The consumer still
+			// needs its first event to be an add so it can load the entry before handling later changes.
+			if (entry.entryType === 'file' && entry.eventType === 'change' && !wasKnown)
+				this.#emitEntrySafely({ ...entry, eventType: 'add' });
+			else this.#emitEntrySafely(entry);
+			return;
+		}
+
+		const wasRemovedDuringScan = scan.removalsEmitted.delete(entry.absolutePath);
+		const currentEntry = scan.currentEntries.get(entry.absolutePath);
+		const previousEntry = wasRemovedDuringScan
+			? undefined
+			: (currentEntry ?? scan.previousEntries.get(entry.absolutePath));
+		scan.currentEntries.set(entry.absolutePath, snapshot);
+
+		if (!previousEntry) {
+			this.#emitAddition(entry);
+			return;
+		}
+		if (previousEntry.entryType !== snapshot.entryType || previousEntry.urlPath !== snapshot.urlPath) {
+			try {
+				this.#emitRemoval(previousEntry, entry.absolutePath);
+			} catch (error) {
+				this.#reportConsumerError(error);
+			}
+			this.#emitAddition(entry);
+			return;
+		}
+		if (
+			snapshot.entryType === 'file' &&
+			previousEntry.entryType === 'file' &&
+			!previousEntry.digest.equals(snapshot.digest)
+		) {
+			this.#emitEntrySafely({ ...entry, eventType: 'change' } as ChangeFileEvent);
+		}
+	}
+
+	#emitAddition(entry: AddFileEvent | ChangeFileEvent | AddDirectoryEvent): void {
+		if (entry.entryType === 'file') this.#emitEntrySafely({ ...entry, eventType: 'add' });
+		else this.#emitEntrySafely({ ...entry, eventType: 'addDir' });
+	}
+
+	#handleRemovedEntry(generation: number, entry: UnlinkFileEvent | UnlinkDirectoryEvent): void {
+		if (generation !== this.#watchGeneration) return;
+		this.#latestPathSequence.delete(entry.absolutePath);
+		const scan = this.#redeployScan?.generation === generation ? this.#redeployScan : undefined;
+		if (!scan) {
+			this.#entries.delete(entry.absolutePath);
+			this.#emitEntrySafely(entry);
+			return;
+		}
+
+		const knownEntry = scan.currentEntries.get(entry.absolutePath) ?? scan.previousEntries.get(entry.absolutePath);
+		scan.currentEntries.delete(entry.absolutePath);
+		if (!knownEntry || scan.removalsEmitted.has(entry.absolutePath)) return;
+		try {
+			this.#emitRemoval(knownEntry, entry.absolutePath);
+		} catch (error) {
+			this.#reportConsumerError(error);
+		}
+		scan.removalsEmitted.add(entry.absolutePath);
+	}
+
+	#emitRemoval(snapshot: EntrySnapshot, absolutePath: string): void {
+		if (snapshot.entryType === 'file')
+			this.#emitEntry({ eventType: 'unlink', entryType: 'file', absolutePath, urlPath: snapshot.urlPath });
+		else this.#emitEntry({ eventType: 'unlinkDir', entryType: 'directory', absolutePath, urlPath: snapshot.urlPath });
+	}
+
+	#emitEntry(entry: FileEntryEvent | DirectoryEntryEvent): void {
+		this.emit('all', entry);
+		switch (entry.eventType) {
+			case 'add':
+				this.emit('add', entry);
+				break;
+			case 'change':
+				this.emit('change', entry);
+				break;
+			case 'unlink':
+				this.emit('unlink', entry);
+				break;
+			case 'addDir':
+				this.emit('addDir', entry);
+				break;
+			case 'unlinkDir':
+				this.emit('unlinkDir', entry);
+		}
+	}
+
+	#emitEntrySafely(entry: FileEntryEvent | DirectoryEntryEvent): void {
+		try {
+			this.#emitEntry(entry);
+		} catch (error) {
+			this.#reportConsumerError(error);
+		}
+	}
+
+	#handleWatcherError(error: unknown): void {
 		if (isWatcherExhaustionError(error)) {
 			// Swallow every exhaustion error — chokidar can emit several before the
 			// failed native watcher closes, and we don't want a flurry of ENOSPC to
@@ -196,55 +410,136 @@ export class EntryHandler extends EventEmitter<EntryHandlerEventMap> {
 			}
 			return;
 		}
-		this.emit('error', error);
+		this.#reportConsumerError(error);
+	}
+
+	#reportConsumerError(error: unknown): void {
+		if (this.listenerCount('error') > 0) this.emit('error', error);
+		else this.#logger.error?.('Error in entry listener:', error);
 	}
 
-	#handleReady(): void {
+	#handleReady(generation: number): void {
+		if (generation !== this.#watchGeneration) return;
 		this.#isInitialScanComplete = true;
-		if (this.#pendingFileReads.size > 0) {
-			this.#logger.debug?.(
-				`Initial scan complete, still waiting for ${this.#pendingFileReads.size} pending file reads`
-			);
+		const pendingReads = this.#pendingFileReadsByGeneration.get(generation)?.size ?? 0;
+		if (pendingReads > 0) {
+			this.#logger.debug?.(`Initial scan complete, still waiting for ${pendingReads} pending file reads`);
 		}
-		this.#checkIfAllComplete();
+		this.#checkIfAllComplete(generation);
 	}
 
-	#checkIfAllComplete(): void {
-		// Only emit 'ready' once the initial scan is complete AND all file reads are done
-		if (this.#isInitialScanComplete && this.#pendingFileReads.size === 0) {
+	#checkIfAllComplete(generation: number): void {
+		if (
+			generation === this.#watchGeneration &&
+			this.#readyGeneration !== generation &&
+			this.#isInitialScanComplete &&
+			!this.#pendingFileReadsByGeneration.has(generation)
+		) {
+			this.#readyGeneration = generation;
+			const { listenerErrors, readErrors } = this.#finishRedeployScan(generation);
 			this.emit('ready');
+			// The readiness latch rejects if `error` is emitted first. Surface consumer failures only
+			// after resolving the generation's ready latch so one bad removal listener cannot strand startup.
+			for (const error of listenerErrors) this.#reportConsumerError(error);
+			for (const error of readErrors) this.#handleWatcherError(error);
+		}
+	}
+
+	#finishRedeployScan(generation: number): { listenerErrors: unknown[]; readErrors: unknown[] } {
+		const scan = this.#redeployScan;
+		if (!scan || scan.generation !== generation) return { listenerErrors: [], readErrors: [] };
+		const listenerErrors: unknown[] = [];
+		for (const absolutePath of scan.readFailures.keys()) {
+			const previousEntry = scan.previousEntries.get(absolutePath);
+			if (previousEntry && !scan.currentEntries.has(absolutePath)) scan.currentEntries.set(absolutePath, previousEntry);
+		}
+		const missingEntries = [...scan.previousEntries].filter(
+			([absolutePath]) => !scan.currentEntries.has(absolutePath) && !scan.removalsEmitted.has(absolutePath)
+		);
+		// Match watcher deletion semantics: descendants disappear before the directory that contained them.
+		missingEntries.sort(([a], [b]) => b.length - a.length);
+		// Commit the generation before invoking consumer code. A synchronously throwing removal listener must
+		// not leave the old snapshot installed or keep the readiness latch permanently unresolved.
+		this.#entries = scan.currentEntries;
+		this.#redeployScan = undefined;
+		for (const [absolutePath, snapshot] of missingEntries) {
+			try {
+				this.#emitRemoval(snapshot, absolutePath);
+			} catch (error) {
+				listenerErrors.push(error);
+			}
 		}
+		return { listenerErrors, readErrors: [...scan.readFailures.values()] };
+	}
+
+	#observedEntries(): Map<string, EntrySnapshot> {
+		const scan = this.#redeployScan;
+		if (!scan) return this.#entries;
+		// A generation can be replaced before `ready`, after some events have already reached consumers.
+		// Carry exactly that observed state forward: retain previously known paths that this partial scan
+		// has not reached, apply additions/changes it emitted, and remove paths whose unlink was emitted.
+		const observedEntries = new Map(scan.previousEntries);
+		for (const absolutePath of scan.removalsEmitted) observedEntries.delete(absolutePath);
+		for (const [absolutePath, snapshot] of scan.currentEntries) observedEntries.set(absolutePath, snapshot);
+		return observedEntries;
 	}
 
 	async #watch() {
-		// If pause() retained an in-flight close, wait for it to release inotify
-		// handles before we install a new watcher. Otherwise a fast pause→resume
-		// can overlap teardown and setup under inotify pressure.
+		const install = this.#watchInstall ? this.#watchInstall.then(() => this.#installWatcher()) : this.#installWatcher();
+		const settled: Promise<void> = install.then(
+			() => {
+				if (this.#watchInstall === settled) this.#watchInstall = undefined;
+			},
+			() => {
+				if (this.#watchInstall === settled) this.#watchInstall = undefined;
+			}
+		);
+		this.#watchInstall = settled;
+		await install;
+
+		return this.ready;
+	}
+
+	async #installWatcher(): Promise<void> {
 		if (this.#pausedClose) {
 			await this.#pausedClose;
 			this.#pausedClose = undefined;
 		}
 
-		await this.#watcher?.close();
-		this.#watcher = undefined;
+		const outgoing = this.#watcher;
+		if (outgoing) {
+			// Stays installed across the await so a close() landing in the gap still includes this
+			// teardown in its own settle set; only clear it if close() didn't already replace it.
+			try {
+				await outgoing.close();
+			} catch (error) {
+				this.#logger.warn?.(`Failed to close the previous watcher for ${this.name}; replacing it anyway:`, error);
+			} finally {
+				this.#liveWatchers.delete(outgoing);
+			}
+			if (this.#watcher === outgoing) this.#watcher = undefined;
+		}
 
-		// If close() landed while a previous close()/recreate was awaiting, don't
-		// install a fresh watcher — it would outlive the EntryHandler.
-		if (this.#closed) return this.ready;
+		if (this.#closed) return;
 
-		// pause() may have landed in the gap before our async close resolved.
-		// If so, do not install a replacement watcher — resume() will.
-		if (this.#paused) return this.ready;
+		if (this.#paused) return;
+		const generation = ++this.#watchGeneration;
 
-		// When a fresh watcher is installed (after pause+resume, or update), the
-		// initial scan emits add events anew, so reset the readiness latch so
-		// `ready` resolves after the new scan completes.
 		this.#isInitialScanComplete = false;
+		const previousEntries = this.#observedEntries();
+		this.#entries = previousEntries;
+		this.#redeployScan = {
+			generation,
+			previousEntries,
+			currentEntries: new Map(),
+			removalsEmitted: new Set(),
+			readFailures: new Map(),
+		};
 
 		const allowedBases = this.#component.patternBases.map((base) => join(this.#component.directory, base));
 
 		this.#openCount++;
-		this.#watcher = chokidar
+		const watcher = (this.#watcher = chokidar
 			.watch(this.#component.commonPatternBase, {
 				cwd: this.#component.directory,
 				persistent: false,
@@ -280,39 +575,48 @@ export class EntryHandler extends EventEmitter<EntryHandlerEventMap> {
 					);
 				},
 			})
-			.on('all', this.#handleAll.bind(this))
-			.on('error', this.#handleError.bind(this))
-			.on('ready', this.#handleReady.bind(this));
-
-		return this.ready;
+			.on('all', (...args) => this.#handleAll(generation, ...args))
+			.on('error', (error) => {
+				if (generation === this.#watchGeneration) this.#handleWatcherError(error);
+			})
+			.on('ready', () => this.#handleReady(generation)));
+		this.#liveWatchers.add(watcher);
 	}
 
-	// Test-only: simulate the underlying chokidar watcher emitting an error.
-	// Exposed so the polling-fallback path can be exercised without triggering a
-	// real ENOSPC/EMFILE on the host.
 	_simulateWatcherErrorForTests(error: unknown): void {
-		this.#handleError(error);
+		this.#handleWatcherError(error);
+	}
+
+	_simulateFileReadForTests(event: 'add' | 'change', path: string, contents: Promise<Buffer>): Promise<void> {
+		const absolutePath = join(this.directory, path);
+		return this.#queueFileRead(this.#watchGeneration, event, path, absolutePath, undefined, contents);
 	}
 
-	// Test-only: whether the watcher has fallen back to polling.
 	get _usingPollingForTests(): boolean {
 		return this.#usingPolling;
 	}
 
-	// Test-only: number of times the underlying watcher has been (re)opened.
-	// Used to assert that a close()-during-fallback race didn't install a
-	// replacement watcher.
 	get _openCountForTests(): number {
 		return this.#openCount;
 	}
 
+	get _liveWatcherCountForTests(): number {
+		return this.#liveWatchers.size;
+	}
+
 	close(): Promise<this> {
+		this.#watchGeneration++;
 		this.#closed = true;
 		const pendingReads = [...this.#pendingFileReads];
-		const watcherClose = this.#watcher ? Promise.resolve(this.#watcher.close()).catch(() => {}) : Promise.resolve();
+		const outgoing = this.#watcher;
+		const watcherClose = outgoing
+			? Promise.resolve(outgoing.close())
+					.catch(() => {})
+					.then(() => {
+						this.#liveWatchers.delete(outgoing);
+					})
+			: Promise.resolve();
 		this.#watcher = undefined;
-		// If paused, there may be an in-flight close from pause() that hasn't settled yet.
-		// Include it so close() doesn't resolve while inotify handles are still releasing.
 		const pausedClose = this.#pausedClose ?? Promise.resolve();
 		this.#pausedClose = undefined;
 
@@ -332,41 +636,42 @@ export class EntryHandler extends EventEmitter<EntryHandlerEventMap> {
 	 * Idempotent. Awaiting `ready` while paused will not resolve until resume().
 	 */
 	pause(): void {
+		if (this.#paused || this.#closed) return;
+		this.#watchGeneration++;
 		this.#paused = true;
-		// Reset `ready` to a fresh pending promise so the documented "awaiting
-		// ready while paused will not resolve until resume()" contract holds even
-		// when the watcher had already become ready before pause(). The next
-		// 'ready' emit will come from the chokidar instance installed by resume().
-		this.ready = once(this, 'ready');
+		this.ready = this.#createReadyLatch();
 		if (this.#watcher) {
-			// Retain the close promise so resume()→#watch() can await full
-			// teardown before opening a new watcher.
-			this.#pausedClose = Promise.resolve(this.#watcher.close()).catch(() => {
-				// Teardown errors aren't actionable; swallow so resume can proceed.
-			});
+			const outgoing = this.#watcher;
+			this.#pausedClose = Promise.resolve(outgoing.close())
+				.catch(() => {})
+				.then(() => {
+					this.#liveWatchers.delete(outgoing);
+				});
 			this.#watcher = undefined;
 		}
 	}
 
 	/**
 	 * Reinstate the watcher previously stopped by pause(). The fresh chokidar
-	 * instance does an initial scan and emits add events for every file
-	 * currently matching the configured globs — by design, since the typical
-	 * caller (Scope, on deploy:end) wants plugins to see the post-deploy tree
-	 * as if loading cold.
+	 * instance scans the post-pause tree, compares it with the retained snapshot,
+	 * and emits only the logical add, change, unlink, addDir, and unlinkDir events.
 	 *
 	 * No-op if not currently paused.
 	 */
 	resume(): Promise<any[]> {
 		if (!this.#paused) return this.ready;
 		this.#paused = false;
-		// `this.ready` was already reset to a pending promise in pause(); just
-		// trigger the watcher recreation and let its 'ready' emit resolve it.
 		return this.#watch();
 	}
 
 	update(config: FilesOption | FileAndURLPathConfig) {
+		if (this.#closed) return this.ready;
+		this.#watchGeneration++;
 		this.#component = new Component(this.name, this.directory, castConfig(config));
+		// Re-arm the readiness latch for parity with pause(). Without this, awaiting update() on an
+		// already-ready handler resolves against the outgoing generation's 'ready' — before the
+		// replacement generation has scanned, digested, and emitted its logical events.
+		this.ready = this.#createReadyLatch();
 
 		return this.#watch();
 	}