@harperfast/harper 5.0.25 → 5.1.0-beta.1

package/components/operations.js

@@ -6,18 +6,20 @@ const fs = require('fs-extra');
 const fg = require('fast-glob');
 const normalize = require('normalize-path');
 const validator = require('./operationsValidation.js');
-const log = require('../utility/logging/harper_logger.js');
+const log = require('../utility/logging/harper_logger.ts');
 const hdbTerms = require('../utility/hdbTerms.ts');
-const env = require('../utility/environment/environmentManager.js');
+const env = require('../utility/environment/environmentManager.ts');
 const configUtils = require('../config/configUtils.js');
-const hdbUtils = require('../utility/common_utils.js');
-const { handleHDBError, hdbErrors } = require('../utility/errors/hdbError.js');
+const hdbUtils = require('../utility/common_utils.ts');
+const { handleHDBError, hdbErrors } = require('../utility/errors/hdbError.ts');
 const { HDB_ERROR_MSGS, HTTP_STATUS_CODES } = hdbErrors;
 const manageThreads = require('../server/threads/manageThreads.js');
 const { packageDirectory } = require('../components/packageComponent.ts');
 const { Resources } = require('../resources/Resources.ts');
 const { Application, prepareApplication } = require('./Application.ts');
 const { server } = require('../server/Server.ts');
+const { DeploymentRecorder, awaitDeploymentRow } = require('./deploymentRecorder.ts');
+const { ProgressEmitter } = require('../server/serverHelpers/progressEmitter.ts');
 
 /**
  * Read the settings.js file and return the
@@ -361,7 +363,6 @@ async function deployComponent(req) {
 	}
 
 	// Write to root config if the request contains a package identifier
-	// TODO: how can we keep record of the `payload`? Its often too large to stuff into a config file; especially the root config. Maybe we can write it to a file and reference that way?
 	if (req.package) {
 		// Check if trying to overwrite a core component (requires force)
 		// Lazy-load to avoid circular dependency with componentLoader
@@ -386,63 +387,200 @@ async function deployComponent(req) {
 		await configUtils.addConfig(req.project, applicationConfig);
 	}
 
-	const application = new Application({
-		name: req.project,
-		payload: req.payload,
-		packageIdentifier: req.package,
-		install: {
-			command: req.install_command,
-			timeout: req.install_timeout,
-			allowInstallScripts: req.install_allow_scripts,
-		},
-	});
-
-	await prepareApplication(application);
-
-	// the main thread should never actually load component, just do a deploy
-	if (isMainThread) return;
-
-	// now we attempt to actually load the component in case there is
-	// an error we can immediately detect and report
-	const pseudoResources = new Resources();
-	pseudoResources.isWorker = true;
-
-	if (!process.env.HARPER_SAFE_MODE) {
-		const componentLoader = require('./componentLoader.ts');
-		let lastError;
-		componentLoader.setErrorReporter((error) => (lastError = error));
-		await componentLoader.loadComponent(
-			application.dirPath,
-			pseudoResources,
-			undefined,
-			false,
-			undefined,
-			false,
-			req.project
-		);
+	// Create a hdb_deployment row up front so the deploy is observable and auditable
+	// even if the CLI disconnects. The row also holds the payload in a Blob attribute,
+	// which doubles as the source for peer replication and (later) rollback.
+	//
+	// Only the origin node records — peers receiving a replicated deploy_component skip
+	// recording so we don't accumulate one row per node for the same deploy. The row
+	// reaches peers via the table's standard replication; the peer-side branch below
+	// reads payload_blob back from there.
+	const isReplicatedExecution = typeof req._deploymentId === 'string';
+	// An SSE-bound caller already attached a ProgressEmitter (created in the server
+	// handler so it can also drive the response stream). Reuse it; otherwise spin up a
+	// fresh emitter so the recorder still gets phase events for non-SSE deploys.
+	const emitter = isReplicatedExecution ? null : (req.progress ?? new ProgressEmitter());
+	if (emitter && !req.progress) req.progress = emitter;
+	const recorder = isReplicatedExecution
+		? null
+		: await DeploymentRecorder.create({
+				project: req.project,
+				package_identifier: req.package ?? null,
+				user: req.hdb_user?.username,
+				restart_mode: req.restart === 'rolling' ? 'rolling' : req.restart ? 'immediate' : null,
+				emitter,
+			});
+	if (recorder) req._deploymentId = recorder.deploymentId;
+
+	const emit = (event, data) => emitter?.emit(event, data);
+
+	// The new payload-via-replicated-row path depends on the `system` database actually
+	// being replicated on this node. If the cluster is configured with a narrower
+	// REPLICATION_DATABASES list that excludes `system`, peers won't see the
+	// hdb_deployment row and falling back to sending req.payload through the operation
+	// body is the only viable path.
+	const systemReplicated = isSystemDatabaseReplicated();
+
+	let extractionPayload = req.payload;
+	try {
+		// On the origin, tee the tarball (Buffer or Readable from the multipart parser)
+		// through a hash-and-size tap into the row's payload_blob, then re-source extraction
+		// from the persisted blob. When `system` replicates, the blob becomes the channel
+		// peers read from; when it doesn't, the blob stays local for audit and rollback.
+		if (recorder && req.payload != null) {
+			await recorder.ingestPayload(req.payload);
+			extractionPayload = recorder.row.payload_blob.stream();
+		} else if (isReplicatedExecution && req.payload == null && !req.package) {
+			// Peer received a replicated deploy without a payload — read the tarball from
+			// the replicated hdb_deployment row's payload_blob. Blob.stream() blocks on
+			// in-flight BLOB_CHUNK writes until the chunks land. If the row never arrives
+			// within the timeout, peer records a failure and origin sees it in peer_results.
+			const row = await awaitDeploymentRow(req._deploymentId);
+			extractionPayload = row.payload_blob.stream();
+		}
 
-		if (lastError) throw lastError;
-	}
-	const rollingRestart = req.restart === 'rolling';
-	// if doing a rolling restart set restart to false so that other nodes don't also restart.
-	req.restart = rollingRestart ? false : req.restart;
-	let response = await server.replication.replicateOperation(req);
-	if (req.restart === true) {
-		manageThreads.restartWorkers('http');
-		response.message = `Successfully deployed: ${application.name}, restarting Harper`;
-	} else if (rollingRestart) {
-		const serverUtilities = require('../server/serverHelpers/serverUtilities.ts');
-		const jobResponse = await serverUtilities.executeJob({
-			operation: 'restart_service',
-			service: 'http',
-			replicated: true,
+		const application = new Application({
+			name: req.project,
+			payload: extractionPayload,
+			packageIdentifier: req.package,
+			install: {
+				command: req.install_command,
+				timeout: req.install_timeout,
+				allowInstallScripts: req.install_allow_scripts,
+			},
+			// Forward each complete line of install stdout/stderr to the SSE channel (and
+			// into the recorder's event_log via the same subscriber). Peers have no emitter
+			// — their install output goes to the local logger only; cross-node install
+			// streaming would need extra plumbing and isn't wired here.
+			onInstallLine: emitter ? (manager, stream, line) => emit('install', { manager, stream, line }) : undefined,
 		});
 
-		response.restartJobId = jobResponse.job_id;
-		response.message = `Successfully deployed: ${application.name}, restarting Harper`;
-	} else response.message = `Successfully deployed: ${application.name}`;
+		emit('phase', { phase: 'prepare', status: 'start' });
+		await prepareApplication(application);
+		emit('phase', { phase: 'prepare', status: 'done' });
+
+		// now we attempt to actually load the component in case there is
+		// an error we can immediately detect and report, but app code should not run on the main thread
+		if (!isMainThread && !process.env.HARPER_SAFE_MODE) {
+			const pseudoResources = new Resources();
+			pseudoResources.isWorker = true;
+
+			const componentLoader = require('./componentLoader.ts').default || require('./componentLoader.ts');
+			let lastError;
+			componentLoader.setErrorReporter((error) => (lastError = error));
+			emit('phase', { phase: 'load', status: 'start' });
+			await componentLoader.loadComponent(
+				application.dirPath,
+				pseudoResources,
+				undefined,
+				false,
+				undefined,
+				false,
+				req.project
+			);
+			emit('phase', { phase: 'load', status: 'done' });
 
-	return response;
+			if (lastError) throw lastError;
+		}
+		const rollingRestart = req.restart === 'rolling';
+		// if doing a rolling restart set restart to false so that other nodes don't also restart.
+		req.restart = rollingRestart ? false : req.restart;
+		// ProgressEmitter holds function listeners that can't survive the replication
+		// channel's serialization; strip it unconditionally.
+		delete req.progress;
+		if (systemReplicated && recorder) {
+			// The hdb_deployment row + payload_blob will reach peers via table replication,
+			// so peers can look up the payload by deployment_id. Drop req.payload to keep
+			// the operation body small (the operations channel has frame-size limits the
+			// blob-replication channel doesn't share). _deploymentId is the handoff that
+			// lets peers find the replicated row.
+			delete req.payload;
+		}
+		// As each peer settles, update the origin row so observers polling get_deployment
+		// see per-peer progress in real time rather than only at the aggregate end.
+		// replicateOperation in harper-pro accepts an optional onPeerResult callback that
+		// fires per peer; callers without the callback (older replicator) fall back to
+		// the aggregate response.replicated below.
+		const onPeerResult = recorder
+			? (result) => {
+					recorder.recordPeer(result);
+					emit('peer', result);
+				}
+			: undefined;
+		emit('phase', { phase: 'replicate', status: 'start' });
+		let response = await server.replication.replicateOperation(req, { onPeerResult });
+		emit('phase', { phase: 'replicate', status: 'done' });
+		if (recorder && response?.replicated) {
+			// Fallback path for replicators that don't honor onPeerResult: re-record the
+			// aggregate. recordPeer's upsert-by-node-name semantics make this idempotent
+			// when the per-peer callback already fired for these.
+			recorder.recordPeers(response.replicated);
+		}
+		if (req.restart === true) {
+			emit('phase', { phase: 'restart', status: 'start' });
+			manageThreads.restartWorkers('http');
+			emit('phase', { phase: 'restart', status: 'done' });
+			response.message = `Successfully deployed: ${application.name}, restarting Harper`;
+		} else if (rollingRestart) {
+			const serverUtilities = require('../server/serverHelpers/serverUtilities.ts');
+			emit('phase', { phase: 'restart', status: 'start' });
+			const jobResponse = await serverUtilities.executeJob({
+				operation: 'restart_service',
+				service: 'http',
+				replicated: true,
+			});
+			emit('phase', { phase: 'restart', status: 'done' });
+
+			response.restartJobId = jobResponse.job_id;
+			response.message = `Successfully deployed: ${application.name}, restarting Harper`;
+		} else response.message = `Successfully deployed: ${application.name}`;
+
+		if (recorder) {
+			response.deployment_id = recorder.deploymentId;
+			emit('phase', { phase: 'success', status: 'done' });
+			await recorder.finish('success');
+		}
+		return response;
+	} catch (err) {
+		emit('error', {
+			message: err?.message ?? String(err),
+			code: err?.statusCode ?? err?.code,
+			phase: recorder?.row.phase,
+		});
+		if (recorder) await recorder.finish('failed', err);
+		throw err;
+	}
+}
+
+/**
+ * Returns true when the `system` database is configured to replicate from this node.
+ * Mirrors the gate `shouldReplicateFromNode` applies for `REPLICATION_DATABASES` (in
+ * replication/knownNodes.ts) at the database level. We intentionally do NOT consult
+ * peer nodes' configs — handling partial system-replication across an asymmetric
+ * cluster is out of scope here; the origin's local view is the canonical signal for
+ * whether the payload-via-row path is viable on this node.
+ *
+ * Treats an unset or wildcard ('*') config as "all databases replicate" (Harper's
+ * default), and an array as a strict allowlist where `system` must appear by name
+ * (either as a plain string or as `{name: 'system', ...}`).
+ */
+function isSystemDatabaseReplicated() {
+	const databaseReplications = env.get(hdbTerms.CONFIG_PARAMS.REPLICATION_DATABASES);
+	// Unset → Harper's default: all databases replicate.
+	if (!databaseReplications) return true;
+	// Wildcard.
+	if (databaseReplications === '*') return true;
+	// Single database name (string, not '*'): only THAT database replicates.
+	if (typeof databaseReplications === 'string') return databaseReplications === hdbTerms.SYSTEM_SCHEMA_NAME;
+	// Array allowlist: 'system' must appear by name (string entry or {name: 'system'} object).
+	if (Array.isArray(databaseReplications)) {
+		return databaseReplications.some((entry) =>
+			typeof entry === 'string' ? entry === hdbTerms.SYSTEM_SCHEMA_NAME : entry?.name === hdbTerms.SYSTEM_SCHEMA_NAME
+		);
+	}
+	// Unknown shape — be conservative and assume not replicated rather than risking a
+	// strip that strands peers.
+	return false;
 }
 
 /**
@@ -554,6 +692,8 @@ async function getComponents() {
  * @param req
  * @returns {Promise<*>}
  */
+const DEFAULT_COMPONENT_FILE_MAX_SIZE = 5 * 1024 * 1024; // 5 MB
+
 async function getComponentFile(req) {
 	const validation = validator.getComponentFileValidator(req);
 	if (validation) {
@@ -561,12 +701,23 @@ async function getComponentFile(req) {
 	}
 
 	const compRoot = configUtils.getConfigPath(hdbTerms.CONFIG_PARAMS.COMPONENTSROOT);
+	const filePath = path.join(compRoot, req.project, req.file);
 	const options = req.encoding ? { encoding: req.encoding } : { encoding: 'utf8' };
+	const configuredMax = configUtils.getConfigValue(hdbTerms.CONFIG_PARAMS.OPERATIONSAPI_COMPONENTFILE_MAXSIZE);
+	const maxSize =
+		Number.isFinite(+configuredMax) && +configuredMax > 0 ? +configuredMax : DEFAULT_COMPONENT_FILE_MAX_SIZE;
 
 	try {
-		const stats = await fs.stat(path.join(compRoot, req.project, req.file));
+		const stats = await fs.stat(filePath);
+		if (stats.size > maxSize) {
+			throw handleHDBError(
+				new Error(HDB_ERROR_MSGS.COMPONENT_FILE_TOO_LARGE(stats.size, maxSize)),
+				HDB_ERROR_MSGS.COMPONENT_FILE_TOO_LARGE(stats.size, maxSize),
+				HTTP_STATUS_CODES.CONTENT_TOO_LARGE
+			);
+		}
 		return {
-			message: await fs.readFile(path.join(compRoot, req.project, req.file), options),
+			message: await fs.readFile(filePath, options),
 			size: stats.size,
 			birthtime: stats.birthtime,
 			mtime: stats.mtime,

package/components/operationsValidation.js

@@ -3,11 +3,11 @@
 const Joi = require('joi');
 const fs = require('fs-extra');
 const path = require('path');
-const validator = require('../validation/validationWrapper.js');
+const validator = require('../validation/validationWrapper.ts');
 const hdbTerms = require('../utility/hdbTerms.ts');
-const hdbLogger = require('../utility/logging/harper_logger.js');
+const hdbLogger = require('../utility/logging/harper_logger.ts');
 const configUtils = require('../config/configUtils.js');
-const { hdbErrors } = require('../utility/errors/hdbError.js');
+const { hdbErrors } = require('../utility/errors/hdbError.ts');
 const { HDB_ERROR_MSGS } = hdbErrors;
 
 // File name can only be alphanumeric, dash and underscores

package/components/packageComponent.ts

@@ -1,39 +1,107 @@
 import { join } from 'path';
+import { stat, readdir } from 'node:fs/promises';
+import { Readable } from 'node:stream';
 import tar from 'tar-fs';
 import { createGzip } from 'node:zlib';
 
+interface PackageOptions {
+	skip_node_modules?: boolean;
+	skip_symlinks?: boolean;
+}
+
+const DEFAULT_OPTIONS: PackageOptions = { skip_node_modules: false, skip_symlinks: false };
+
 /**
- * Package a directory into a tarball, base64 encoded
- * @param directory
+ * Package a directory into a tar+gzip stream. The returned Readable can be
+ * piped directly into an HTTP request body, avoiding the Node.js 2GB Buffer
+ * cap that the buffered variant runs into for large components.
+ *
+ * @param onBytes - Optional callback invoked with the byte length of each raw
+ *   tar chunk *before* gzip compression. Useful for tracking upload progress
+ *   against an uncompressed-size total (e.g. from `getPackagedDirectorySize`).
  */
-export function packageDirectory(
+export function streamPackagedDirectory(
 	directory: string,
-	options: { skip_node_modules?: boolean; skip_symlinks?: boolean } = { skip_node_modules: false, skip_symlinks: false }
-): Promise<Buffer> {
+	options: PackageOptions = DEFAULT_OPTIONS,
+	onBytes?: (n: number) => void
+): Readable {
+	const packStream = tar.pack(directory, {
+		dereference: !options.skip_symlinks,
+		ignore: options.skip_node_modules
+			? (name: string) => {
+					return name.includes('node_modules') || name.includes(join('cache', 'webpack'));
+				}
+			: undefined,
+		map: (header) => {
+			if (header.type === 'directory') {
+				header.mode = 0o755;
+			}
+			return header;
+		},
+	});
+	const gzip = createGzip();
+	// Propagate pack errors onto the gzip stream so a single consumer can listen
+	packStream.on('error', (err) => gzip.destroy(err));
+	if (onBytes) {
+		// Attaching a 'data' listener after pipe() is safe — the stream is already
+		// in flowing mode and Node's EventEmitter supports multiple listeners.
+		packStream.on('data', (chunk: Buffer) => onBytes(chunk.length));
+	}
+	return packStream.pipe(gzip);
+}
+
+/**
+ * Walk `directory` and return the total uncompressed size of all files that
+ * `streamPackagedDirectory` would include with the same options. Used by the
+ * CLI to give the upload progress bar a realistic total. The uncompressed size
+ * won't equal the gzipped wire size, but it gives the bar a steady trajectory:
+ * the bar moves as bytes are sent and snaps to 100% when the upload finishes.
+ */
+export async function getPackagedDirectorySize(
+	directory: string,
+	options: PackageOptions = DEFAULT_OPTIONS
+): Promise<number> {
+	let total = 0;
+	const walk = async (dir: string): Promise<void> => {
+		let entries;
+		try {
+			entries = await readdir(dir, { withFileTypes: true });
+		} catch {
+			return; // unreadable directory — skip
+		}
+		for (const entry of entries) {
+			const fullPath = join(dir, entry.name);
+			if (options.skip_node_modules && (entry.name === 'node_modules' || fullPath.includes(join('cache', 'webpack')))) {
+				continue;
+			}
+			if (entry.isDirectory()) {
+				await walk(fullPath);
+			} else {
+				if (options.skip_symlinks && entry.isSymbolicLink()) continue;
+				try {
+					const s = await stat(fullPath); // follows symlinks, matching tar dereference
+					total += s.size;
+				} catch {
+					// inaccessible file — skip
+				}
+			}
+		}
+	};
+	await walk(directory);
+	return total;
+}
+
+/**
+ * Package a directory into a tar+gzip buffer. Retained for callers that need
+ * an in-memory payload (small deploys, tests). For large directories prefer
+ * `streamPackagedDirectory` to avoid the Buffer size ceiling.
+ */
+export function packageDirectory(directory: string, options: PackageOptions = DEFAULT_OPTIONS): Promise<Buffer> {
 	return new Promise((resolve, reject) => {
-		// for deployComponent to a remote server, we need to tar the local directory
-		const chunks = [];
-		// pack the directory
-		tar
-			.pack(directory, {
-				dereference: !options.skip_symlinks,
-				ignore: options.skip_node_modules
-					? (name: string) => {
-							return name.includes('node_modules') || name.includes(join('cache', 'webpack'));
-						}
-					: undefined,
-				map: (header) => {
-					if (header.type === 'directory') {
-						header.mode = 0o755;
-					}
-					return header;
-				},
-			})
-			.pipe(createGzip())
-			.on('data', (chunk: Buffer) => chunks.push(chunk))
-			.on('end', () => {
-				resolve(Buffer.concat(chunks));
-			})
-			.on('error', reject);
+		const chunks: Buffer[] = [];
+		const stream = streamPackagedDirectory(directory, options);
+		stream.on('data', (chunk: Buffer) => chunks.push(chunk));
+		stream.on('end', () => resolve(Buffer.concat(chunks)));
+		stream.on('error', reject);
 	});
 }

package/components/requestRestart.ts

@@ -1,11 +1,19 @@
 import { Status } from '../server/status/index.ts';
 
-let restartArrayBuffer: ArrayBuffer;
+interface NotifyingArrayBuffer extends ArrayBuffer {
+	notify(): void;
+	cancel(): void;
+}
+
+let restartArrayBuffer: NotifyingArrayBuffer;
 let restartNeededArray: Uint8Array;
+let onRestartRequestedCallback: (() => void) | null = null;
 
 function ensureInitialized() {
 	if (!restartArrayBuffer) {
-		restartArrayBuffer = Status.primaryStore.getUserSharedBuffer('restart-needed', new ArrayBuffer(1));
+		restartArrayBuffer = Status.primaryStore.getUserSharedBuffer('restart-needed', new ArrayBuffer(1), {
+			callback: () => onRestartRequestedCallback?.(),
+		}) as NotifyingArrayBuffer;
 		restartNeededArray = new Uint8Array(restartArrayBuffer);
 	}
 }
@@ -13,6 +21,7 @@ function ensureInitialized() {
 export function requestRestart() {
 	ensureInitialized();
 	restartNeededArray[0] = 1;
+	restartArrayBuffer.notify();
 }
 
 export function restartNeeded() {
@@ -24,3 +33,9 @@ export function resetRestartNeeded() {
 	ensureInitialized();
 	restartNeededArray[0] = 0;
 }
+
+export function subscribeToRestartRequests(callback: () => void) {
+	ensureInitialized();
+	if (onRestartRequestedCallback) throw new Error('A restart-request subscriber is already registered');
+	onRestartRequestedCallback = callback;
+}

package/components/status/crossThread.ts

@@ -72,7 +72,11 @@ export class CrossThreadStatusCollector {
 	}
 
 	/**
-	 * Schedule cleanup of stale requests if needed
+	 * Safety-net cleanup of stale requests. Each collect() call also has its own 5s
+	 * timeout that deletes its requestId on completion or timeout, so this should
+	 * normally never find anything to reap — it exists to defend against a missed
+	 * cleanup path (e.g., a thrown exception between awaitingResponses.set and the
+	 * timeout being armed).
 	 */
 	private scheduleCleanup(): void {
 		// Clear any existing timer
@@ -80,12 +84,17 @@ export class CrossThreadStatusCollector {
 			clearTimeout(this.cleanupTimer);
 		}
 
-		// Schedule cleanup in 30 seconds if there are pending requests
-		if (this.awaitingResponses.size > 0) {
+		// Schedule cleanup in 30 seconds if there are pending requests or checkers
+		if (this.awaitingResponses.size > 0 || this.responseCheckers.size > 0) {
 			this.cleanupTimer = setTimeout(() => {
-				if (this.awaitingResponses.size > 0) {
-					logger.debug?.(`Cleaning up ${this.awaitingResponses.size} stale pending requests`);
+				const staleResponses = this.awaitingResponses.size;
+				const staleCheckers = this.responseCheckers.size;
+				if (staleResponses > 0 || staleCheckers > 0) {
+					logger.debug?.(
+						`Cleaning up ${staleResponses} stale pending requests, ${staleCheckers} stale response checkers`
+					);
 					this.awaitingResponses.clear();
+					this.responseCheckers.clear();
 				}
 				this.cleanupTimer = null;
 			}, 30000);

package/components/status/errors.ts

@@ -5,7 +5,7 @@
  * providing better diagnostics and error handling capabilities.
  */
 
-import { HTTP_STATUS_CODES } from '../../utility/errors/commonErrors.js';
+import { HTTP_STATUS_CODES } from '../../utility/errors/commonErrors.ts';
 
 /**
  * Base error class for component status system

package/config/RootConfigWatcher.ts

@@ -3,25 +3,78 @@ import { readFile } from 'node:fs/promises';
 import { getConfigFilePath } from './configUtils.js';
 import { EventEmitter, once } from 'node:events';
 import { parse } from 'yaml';
+import { POLLING_FALLBACK_OPTIONS, isWatcherExhaustionError, warnWatcherFallback } from '../utility/watcherFallback.ts';
 
 export class RootConfigWatcher extends EventEmitter {
 	#configFilePath: string;
-	#watcher: FSWatcher;
+	#watcher!: FSWatcher;
 	#config: any;
+	#usingPolling: boolean;
+	#closed: boolean;
+	#openCount: number = 0;
 	ready: Promise<any[]>;
 
 	constructor() {
 		super();
 		this.#configFilePath = getConfigFilePath();
+		this.#usingPolling = false;
+		this.#closed = false;
 		this.ready = once(this, 'ready');
+		this.#openWatcher();
+	}
+
+	#openWatcher() {
+		this.#openCount++;
 		this.#watcher = chokidar
-			.watch(this.#configFilePath, { persistent: false })
+			.watch(this.#configFilePath, {
+				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));
 	}
 
+	// 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.
+	get _openCountForTests(): number {
+		return this.#openCount;
+	}
+
 	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.#configFilePath);
+				this.#usingPolling = true;
+				// 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', error);
 	}
 
@@ -46,6 +99,7 @@ export class RootConfigWatcher extends EventEmitter {
 	}
 
 	close() {
+		this.#closed = true;
 		this.#watcher.close();
 		this.#config = undefined;
 		this.emit('close');