@harperfast/harper 5.0.30 → 5.1.0-beta.2

package/components/EntryHandler.ts

@@ -1,14 +1,19 @@
 import { type Logger } from '../utility/logging/logger.ts';
-import { loggerWithTag } from '../utility/logging/harper_logger.js';
+import { loggerWithTag } from '../utility/logging/harper_logger.ts';
 import type { Stats } from 'node:fs';
 import { EventEmitter, once } from 'node:events';
-import { Component, FileAndURLPathConfig } from './Component.js';
+import { Component, FileAndURLPathConfig } from './Component.ts';
 import chokidar, { FSWatcher, FSWatcherEventMap } from 'chokidar';
 import { join } from 'node:path';
 import { readFile } from 'node:fs/promises';
-import { FilesOption } from './deriveGlobOptions.js';
-import { deriveURLPath } from './deriveURLPath.js';
+import { FilesOption } from './deriveGlobOptions.ts';
+import { deriveURLPath } from './deriveURLPath.ts';
 import { isMatch } from 'micromatch';
+import {
+	DIRECTORY_POLLING_FALLBACK_OPTIONS,
+	isWatcherExhaustionError,
+	warnWatcherFallback,
+} from '../utility/watcherFallback.ts';
 
 export interface BaseEntry {
 	stats?: Stats;
@@ -75,6 +80,19 @@ export class EntryHandler extends EventEmitter<EntryHandlerEventMap> {
 	#logger: Logger;
 	#pendingFileReads: 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.
+	#pausedClose?: Promise<void>;
+	#usingPolling: boolean = false;
+	#closed: boolean = false;
+	#openCount: number = 0;
 	ready: Promise<any[]>;
 
 	constructor(name: string, directory: string, config: FilesOption | FileAndURLPathConfig, logger?: Logger) {
@@ -159,6 +177,25 @@ export class EntryHandler extends EventEmitter<EntryHandlerEventMap> {
 	}
 
 	#handleError(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
+			// surface to consumers in the middle of recovery.
+			if (!this.#usingPolling) {
+				warnWatcherFallback(this.#component.directory);
+				this.#usingPolling = true;
+				// Reopen with polling. #watch() itself guards against reopen-after-close.
+				// The .catch is required because #watch() internally awaits the failed
+				// watcher's close(), which can reject under the same FD/inotify pressure
+				// that triggered this path; without it Node would treat that as an
+				// unhandled rejection (matches the .catch pattern used in
+				// OptionsWatcher / RootConfigWatcher).
+				this.#watch().catch(() => {
+					// Teardown errors on an already-failed watcher are not actionable.
+				});
+			}
+			return;
+		}
 		this.emit('error', error);
 	}
 
@@ -180,21 +217,66 @@ export class EntryHandler extends EventEmitter<EntryHandlerEventMap> {
 	}
 
 	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.
+		if (this.#pausedClose) {
+			await this.#pausedClose;
+			this.#pausedClose = undefined;
+		}
+
 		await this.#watcher?.close();
 		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;
+
+		// 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;
+
+		// 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 allowedBases = this.#component.patternBases.map((base) => join(this.#component.directory, base));
 
+		this.#openCount++;
 		this.#watcher = chokidar
 			.watch(this.#component.commonPatternBase, {
 				cwd: this.#component.directory,
 				persistent: false,
+				followSymlinks: false,
+				...(this.#usingPolling ? DIRECTORY_POLLING_FALLBACK_OPTIONS : {}),
 				ignored: (path) => {
 					const normalizedPath = path.replace(/\\/g, '/');
 					const normalizedBases = allowedBases.map((base) => base.replace(/\\/g, '/'));
+					const normalizedDirectory = this.#component.directory.replace(/\\/g, '/');
+
+					// Determine the path relative to the component directory. Leading '/' is preserved
+					// (or empty when the path *is* the component directory) so the regex anchors below
+					// can use `(?:^|/)` to match the first segment without false positives on names
+					// that merely contain the same substring (e.g. `mynode_modules`, `notgit`).
+					const relativePath = normalizedPath.startsWith(normalizedDirectory)
+						? normalizedPath.slice(normalizedDirectory.length)
+						: normalizedPath;
+
+					// Skip node_modules at any depth. This allows plugins loaded from node_modules
+					// to still watch their own component files while ignoring their dependencies.
+					if (/(?:^|\/)node_modules(?:\/|$)/.test(relativePath)) return true;
+
+					// Skip transient package manager and VCS artifacts. Without these, an in-place
+					// `npm install` during a component deploy writes log files and atomic-rename
+					// temp directories that fire change events and drive an auto-reload restart
+					// storm — see harper#488.
+					if (/(?:^|\/)\.git(?:\/|$)/.test(relativePath)) return true;
+					if (/(?:^|\/)\.tmp-/.test(relativePath)) return true;
+					if (/(?:^|\/)(?:npm-debug|yarn-error|yarn-debug|pnpm-debug)\.log(?:\/|$)/.test(relativePath)) return true;
+
 					return (
-						normalizedPath !== this.#component.directory.replace(/\\/g, '/') &&
-						normalizedBases.every((base) => !normalizedPath.startsWith(base))
+						normalizedPath !== normalizedDirectory && normalizedBases.every((base) => !normalizedPath.startsWith(base))
 					);
 				},
 			})
@@ -205,14 +287,82 @@ export class EntryHandler extends EventEmitter<EntryHandlerEventMap> {
 		return this.ready;
 	}
 
-	close(): this {
-		this.#watcher?.close();
+	// 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);
+	}
+
+	// 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;
+	}
+
+	close(): Promise<this> {
+		this.#closed = true;
+		const pendingReads = [...this.#pendingFileReads];
+		const watcherClose = this.#watcher ? Promise.resolve(this.#watcher.close()).catch(() => {}) : 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;
 
 		this.emit('close');
 		this.removeAllListeners();
 
-		return this;
+		return Promise.allSettled([watcherClose, pausedClose, ...pendingReads]).then(() => this);
+	}
+
+	/**
+	 * Quiesce the watcher without tearing down the EntryHandler. Closes the
+	 * underlying chokidar watcher (releasing inotify handles for the watched
+	 * tree) but preserves all listeners attached to this instance, so plugins
+	 * that registered `scope.handleEntry(handler)` keep their handler wired up
+	 * across the pause.
+	 *
+	 * Idempotent. Awaiting `ready` while paused will not resolve until resume().
+	 */
+	pause(): void {
+		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');
+		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.
+			});
+			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.
+	 *
+	 * 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) {

package/components/OptionsWatcher.ts

@@ -1,12 +1,13 @@
 import { type Logger } from '../utility/logging/logger.ts';
-import { loggerWithTag } from '../utility/logging/harper_logger.js';
+import { loggerWithTag } from '../utility/logging/harper_logger.ts';
 import { EventEmitter, once } from 'events';
 import yaml from 'yaml';
 import chokidar, { type FSWatcher } from 'chokidar';
 import { readFile } from 'node:fs/promises';
 import { isDeepStrictEqual } from 'util';
-import { DEFAULT_CONFIG } from './DEFAULT_CONFIG.js';
+import { DEFAULT_CONFIG } from './DEFAULT_CONFIG.ts';
 import { cloneDeep } from 'lodash';
+import { POLLING_FALLBACK_OPTIONS, isWatcherExhaustionError, warnWatcherFallback } from '../utility/watcherFallback.ts';
 
 export interface Config {
 	[key: string]: ConfigValue;
@@ -82,11 +83,15 @@ export class CannotSetPropertyError extends Error {
  */
 export class OptionsWatcher extends EventEmitter<OptionsWatcherEventMap> {
 	#filePath: string;
-	#watcher: FSWatcher;
+	#watcher!: FSWatcher;
 	#scopedConfig?: ConfigValue;
 	#rootConfig?: Config;
 	#name: string;
 	#logger: Logger;
+	#usingPolling: boolean;
+	#closed: boolean;
+	#openCount: number = 0;
+	#pendingReads: Set<Promise<void>> = new Set();
 	ready: Promise<any[]>;
 
 	constructor(name: string, filePath: string, logger?: Logger) {
@@ -94,9 +99,19 @@ export class OptionsWatcher extends EventEmitter<OptionsWatcherEventMap> {
 		this.#name = name;
 		this.#filePath = filePath;
 		this.#logger = logger || loggerWithTag(name);
+		this.#usingPolling = false;
+		this.#closed = false;
 		this.ready = once(this, 'ready');
+		this.#openWatcher();
+	}
+
+	#openWatcher() {
+		this.#openCount++;
 		this.#watcher = chokidar
-			.watch(filePath, { persistent: false })
+			.watch(this.#filePath, {
+				persistent: false,
+				...(this.#usingPolling ? POLLING_FALLBACK_OPTIONS : {}),
+			})
 			.on('add', this.#handleChange.bind(this))
 			.on('change', this.#handleChange.bind(this))
 			.on('error', this.#handleError.bind(this))
@@ -105,9 +120,10 @@ export class OptionsWatcher extends EventEmitter<OptionsWatcherEventMap> {
 	}
 
 	#handleChange() {
-		readFile(this.#filePath, 'utf-8')
+		const read: Promise<void> = readFile(this.#filePath, 'utf-8')
 			.then((contents) => {
-				this.#rootConfig = yaml.parse(contents);
+				const parsed = yaml.parse(contents);
+				this.#rootConfig = parsed && typeof parsed === 'object' ? parsed : undefined;
 				// If the extension is in the config file
 				if (this.#rootConfig && this.#name in this.#rootConfig) {
 					// If a config object does not exist
@@ -146,10 +162,36 @@ export class OptionsWatcher extends EventEmitter<OptionsWatcherEventMap> {
 					return;
 				}
 				this.emit('error', error);
+			})
+			.finally(() => {
+				this.#pendingReads.delete(read);
 			});
+		this.#pendingReads.add(read);
 	}
 
 	#handleError(error: unknown) {
+		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
+			// surface to consumers in the middle of recovery.
+			if (!this.#usingPolling) {
+				warnWatcherFallback(this.#filePath);
+				this.#usingPolling = true;
+				// Close the failed native watcher and reopen with polling. Guard
+				// against reopen-after-close: the caller may have invoked close()
+				// while this teardown was in flight. The .catch is required because
+				// `finally` would re-raise a teardown rejection as an unhandled one.
+				this.#watcher
+					.close()
+					.catch(() => {
+						// Teardown errors on an already-failed watcher are not actionable.
+					})
+					.finally(() => {
+						if (!this.#closed) this.#openWatcher();
+					});
+			}
+			return;
+		}
 		this.emit('error', new OptionsWatcherConfigFileError(this.#filePath, error));
 	}
 
@@ -283,17 +325,39 @@ export class OptionsWatcher extends EventEmitter<OptionsWatcherEventMap> {
 		this.emit('change', keys, value, this.#scopedConfig);
 	}
 
+	// 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);
+	}
+
+	// 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;
+	}
+
 	/**
-	 * Closes the underlying file watcher, emits the `close` event, and removes any listeners on the OptionsWatcher instance
+	 * Closes the underlying file watcher and drains any pending config-file reads.
+	 * Emits `close` synchronously, removes all listeners, then returns a Promise that
+	 * resolves once the chokidar watcher has fully stopped and all in-flight reads settle.
 	 */
-	close() {
-		this.#watcher.close();
+	close(): Promise<this> {
+		this.#closed = true;
+		const pendingReads = [...this.#pendingReads];
+		const watcherClose = Promise.resolve(this.#watcher.close()).catch(() => {});
 
 		this.emit('close');
-
 		this.removeAllListeners();
 
-		return this;
+		return Promise.allSettled([watcherClose, ...pendingReads]).then(() => this);
 	}
 
 	/**

package/components/Scope.ts

@@ -1,15 +1,17 @@
 import { type Logger } from '../utility/logging/logger.ts';
-import { loggerWithTag } from '../utility/logging/harper_logger.js';
+import { loggerWithTag } from '../utility/logging/harper_logger.ts';
 import { EventEmitter, once } from 'node:events';
-import { databaseEventsEmitter } from '../resources/databases.ts';
+import { databaseEventsEmitter, table } from '../resources/databases.ts';
 import { server, type Server } from '../server/Server.ts';
 import { EntryHandler, type EntryHandlerEventMap, type onEntryEventHandler } from './EntryHandler.ts';
 import { OptionsWatcher, OptionsWatcherEventMap } from './OptionsWatcher.ts';
 import { resources, type Resources } from '../resources/Resources.ts';
+import { Models, models as modelsSingleton } from '../resources/models/Models.ts';
 import type { FileAndURLPathConfig } from './Component.ts';
 import { FilesOption } from './deriveGlobOptions.ts';
 import { requestRestart } from './requestRestart.ts';
 import { ApplicationScope } from './ApplicationScope.ts';
+import { deployLifecycle } from './deployLifecycle.ts';
 
 export class MissingDefaultFilesOptionError extends Error {
 	constructor() {
@@ -19,10 +21,18 @@ export class MissingDefaultFilesOptionError extends Error {
 }
 
 export type ScopeEventsMap = {
-	all: [...args: unknown[]];
-	close: [];
-	error: [error: unknown];
-	ready: [];
+	'all': [...args: unknown[]];
+	'close': [];
+	'error': [error: unknown];
+	'ready': [];
+	// Fired on this scope just before deploy I/O begins for the parent component
+	// (extract + npm install). Plugins observing these can pause their own
+	// file-driven work to avoid acting on intermediate states.
+	'deploy:start': [componentName: string];
+	// Fired after deploy I/O completes (success or failure). The scope's
+	// EntryHandlers have been recreated by this point; subsequent `add`/`change`
+	// events reflect the post-deploy tree.
+	'deploy:end': [componentName: string];
 	[record: string]: [...args: unknown[]];
 };
 
@@ -38,10 +48,18 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 	#directory: string;
 	#appName: string;
 	#pluginName: string;
+	#origin: string;
 	#entryHandler?: EntryHandler;
 	#entryHandlers: EntryHandler[];
 	#logger: Logger;
 	#pendingInitialLoads: Set<Promise<void>>;
+	#deployStartHandler: (name: string) => void;
+	#deployEndHandler: (name: string) => void;
+	// While a deploy of this component is in flight, EntryHandler events do not
+	// drive requestRestart() — the deploy itself produces hundreds of file
+	// changes that would otherwise pile up. A single coalesced restart is
+	// triggered by the post-deploy re-scan instead.
+	#deployInFlight: boolean = false;
 	applicationScope?: ApplicationScope;
 
 	options: OptionsWatcher;
@@ -49,26 +67,53 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 	server?: Server;
 	ready: Promise<any[]>;
 	databaseEvents: typeof databaseEventsEmitter;
+	models: Models;
 
 	constructor(
 		appName: string,
 		pluginName: string,
 		directory: string,
 		configFilePath: string,
-		applicationScope: ApplicationScope
+		applicationScope: ApplicationScope,
+		origin: string = appName
 	) {
 		super();
 
 		this.#appName = appName;
 		this.#pluginName = pluginName;
+		this.#origin = typeof origin === 'string' ? origin : appName;
 		this.#directory = directory;
 		this.#configFilePath = configFilePath;
-		this.#logger = logger || loggerWithTag(this.#appName);
+		this.#logger = loggerWithTag(this.#appName);
 
 		this.databaseEvents = databaseEventsEmitter;
 		this.applicationScope = applicationScope;
 		this.resources = applicationScope?.resources ?? resources;
-		this.server = applicationScope?.server ?? server;
+		this.models = modelsSingleton;
+
+		const baseServer = applicationScope?.server ?? server;
+		const scopeRef = this;
+		// Wrap server so http/request/ws/upgrade calls automatically carry this plugin's name,
+		// urlPath, and host — enabling routing and before/after dependencies on named middleware.
+		this.server = new Proxy(baseServer, {
+			get(target, prop, receiver) {
+				if (prop === 'http' || prop === 'request' || prop === 'ws' || prop === 'upgrade') {
+					const method = Reflect.get(target, prop, receiver);
+					if (typeof method === 'function') {
+						return (listener: any, options?: any) => {
+							const scopeConfig = (scopeRef.options?.getAll() as any) ?? {};
+							return method.call(target, listener, {
+								name: pluginName,
+								urlPath: scopeConfig.urlPath || undefined,
+								host: scopeConfig.host || undefined,
+								...options,
+							});
+						};
+					}
+				}
+				return Reflect.get(target, prop, receiver);
+			},
+		}) as Server;
 
 		this.#entryHandlers = [];
 		this.#pendingInitialLoads = new Set();
@@ -80,6 +125,18 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 			.on('error', this.#handleError.bind(this))
 			.on('change', this.#optionsWatcherChangeListener.bind(this)())
 			.on('ready', this.#handleOptionsWatcherReady.bind(this));
+
+		// Bridge cross-thread deploy lifecycle events for this component. The
+		// handlers live on the scope for the lifetime of the scope and are torn
+		// down in close().
+		this.#deployStartHandler = (name) => {
+			if (name === this.#appName) this.#onDeployStart(name);
+		};
+		this.#deployEndHandler = (name) => {
+			if (name === this.#appName) this.#onDeployEnd(name);
+		};
+		deployLifecycle.on('deploy:start', this.#deployStartHandler);
+		deployLifecycle.on('deploy:end', this.#deployEndHandler);
 	}
 
 	get logger(): Logger {
@@ -102,6 +159,11 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 		return this.#configFilePath;
 	}
 
+	ensureTable<TableResourceType = unknown>(options: any): TableResourceType {
+		options.origin = this.#origin;
+		return table<TableResourceType>(options);
+	}
+
 	#handleOptionsWatcherReady(): void {
 		// This previously created the default entry handler immediately, but now we wait for the user to call `handleEntry`
 		// The issue was that since the component loader was awaiting `scope.ready()` and then calling `pluginModule.handleApplication(scope)`,
@@ -116,20 +178,61 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 		this.emit('error', error);
 	}
 
-	close() {
-		for (const entryHandler of this.#entryHandlers) {
-			entryHandler.close();
-		}
+	async close(): Promise<this> {
+		deployLifecycle.off('deploy:start', this.#deployStartHandler);
+		deployLifecycle.off('deploy:end', this.#deployEndHandler);
 
-		this.options.close();
+		await Promise.allSettled([...this.#entryHandlers.map((h) => h.close()), this.options.close()]);
 
 		this.emit('close');
-
 		this.removeAllListeners();
 
 		return this;
 	}
 
+	#onDeployStart(componentName: string): void {
+		this.#deployInFlight = true;
+		// Pause each EntryHandler so it stops emitting events for the
+		// intermediate filesystem state the deploy is writing, and so it
+		// releases its inotify handles while npm install is unpacking
+		// dependencies. pause() preserves the EntryHandler INSTANCE — listeners
+		// the plugin attached via scope.handleEntry(handler) remain attached.
+		for (const entryHandler of this.#entryHandlers) {
+			entryHandler.pause();
+		}
+
+		this.#safeEmit('deploy:start', componentName);
+	}
+
+	#onDeployEnd(componentName: string): void {
+		this.#deployInFlight = false;
+
+		// Resume each EntryHandler BEFORE notifying plugins. Otherwise a plugin
+		// throwing in its deploy:end handler would abort this function and
+		// leave the watchers permanently paused (surfaced by Gemini review).
+		// The fresh chokidar watcher does an initial scan and emits add events
+		// for the post-deploy tree; the existing per-event listener calls
+		// scope.requestRestart() for each, and the restart debounce in
+		// componentLoader collapses them into a single restart cycle. Plugin
+		// handlers stay attached across the pause.
+		for (const entryHandler of this.#entryHandlers) {
+			void entryHandler.resume();
+		}
+
+		this.#safeEmit('deploy:end', componentName);
+	}
+
+	// Swallow and log listener exceptions so one buggy plugin can't stop us
+	// from running the rest of the deploy-lifecycle bookkeeping. EventEmitter
+	// by default rethrows from synchronous listeners.
+	#safeEmit(event: 'deploy:start' | 'deploy:end', componentName: string): void {
+		try {
+			this.emit(event, componentName);
+		} catch (error) {
+			this.#logger.error?.(`Listener for ${event} threw for ${this.#appName}:`, error);
+		}
+	}
+
 	#createEntryHandler(config: FilesOption | FileAndURLPathConfig): EntryHandler {
 		const entryHandler = new EntryHandler(this.#pluginName, this.#directory, config, this.#logger)
 			.on('error', this.#handleError.bind(this))
@@ -168,10 +271,14 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 			if (key[0] === 'files' || key[0] === 'urlPath') {
 				// TODO: validate options
 
-				// If not entry handler exists then likely the config did not have `files` initially
-				// Now, it does, so create a default entry handler.
+				// If no entry handler exists yet, the plugin's handleApplication has not called
+				// handleEntry() yet — or it hasn't been called at all for this scope. Either way,
+				// when handleEntry() is eventually called it will read the current config via
+				// getFilesOption() and create the handler with the correct, up-to-date values.
+				// Eagerly creating an entry handler here would start chokidar's initial scan
+				// before the plugin's callback is attached, causing the initial `add` events to
+				// be missed (RE-8).
 				if (!scope.#entryHandler) {
-					scope.#entryHandler = scope.#createEntryHandler(config as FileAndURLPathConfig);
 					return;
 				}
 
@@ -303,6 +410,13 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 	}
 
 	requestRestart() {
+		if (this.#deployInFlight) {
+			// Suppressed: a deploy is rewriting this component's files. The
+			// post-deploy re-scan in #onDeployEnd will trigger the coalesced
+			// restart instead.
+			this.#logger.debug?.(`Restart suppressed (deploy in flight) for ${this.#appName}`);
+			return;
+		}
 		this.#logger.debug?.(`Restart requested from ${this.#pluginName} scope for ${this.#appName}`);
 		requestRestart();
 	}