@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/components/operationsValidation.js

@@ -13,7 +13,12 @@ const { ENV_ENCRYPTED_PREFIX } = require('../utility/envFile.ts');
 // File and project names can only be alphanumeric, dash and underscores. Both patterns are shared
 // with the CLI (utility/componentNames.ts): `harper deploy setup=true` resolves a project name and a
 // credential host client-side, and has to reject exactly what these schemas would.
-const { PROJECT_NAME_PATTERN: PROJECT_FILE_NAME_REGEX, GIT_HOST_PATTERN } = require('../utility/componentNames.ts');
+const {
+	PROJECT_NAME_PATTERN: PROJECT_FILE_NAME_REGEX,
+	GIT_HOST_PATTERN,
+	isReservedComponentName,
+} = require('../utility/componentNames.ts');
+const { assertBranchedDatabases } = require('./Application.ts');
 
 // dotenv's accepted key character set. Restricting keys to this prevents a crafted key (e.g. one
 // containing `=` or a newline) from injecting extra assignments into a .env file.
@@ -24,6 +29,12 @@ const ENV_KEY_REGEX = /^[\w.-]+$/;
 const HOSTNAME_SCHEMA = Joi.string().hostname();
 const IPV6_SCHEMA = Joi.string().ip({ version: 'ipv6' });
 
+// A deployment id names both an hdb_deployment row and a staging directory, so it is held to the shape
+// the recorder mints — `randomUUID()`, which is lowercase. LOWERCASE ONLY, because a case-insensitive
+// filesystem resolves an uppercase id to the real directory while every string compare against it fails:
+// the retention pin would not recognise the artifact the request is about to activate, and would evict it.
+const DEPLOYMENT_ID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
 module.exports = {
 	getDropCustomFunctionValidator,
 	setCustomFunctionValidator,
@@ -73,6 +84,31 @@ function checkProjectExists(checkExists, project, helpers) {
 	}
 }
 
+// Drop/package/file operations deliberately don't call this: an application deployed under the
+// name before it was reserved has to stay removable.
+function checkReservedProjectName(project, helpers) {
+	if (isReservedComponentName(project)) return helpers.message(HDB_ERROR_MSGS.RESERVED_PROJECT_NAME(project));
+	return project;
+}
+
+/**
+ * The file writers create the project directory as a side effect of writing into it, so they refuse
+ * only the creation — an application that already holds the name stays editable until it is
+ * migrated off it.
+ */
+function checkReservedProjectCreation(project, helpers) {
+	if (!isReservedComponentName(project)) return project;
+	let projectDir;
+	try {
+		const componentsRoot = configUtils.getConfigPath(hdbTerms.CONFIG_PARAMS.COMPONENTSROOT);
+		if (componentsRoot) projectDir = path.join(componentsRoot, project);
+	} catch (err) {
+		hdbLogger.error(err);
+	}
+	if (projectDir && fs.existsSync(projectDir)) return project;
+	return helpers.message(HDB_ERROR_MSGS.RESERVED_PROJECT_NAME(project));
+}
+
 function checkFilePath(path, helpers) {
 	if (path.includes('..')) return helpers.message('Invalid file path');
 	return path;
@@ -154,6 +190,7 @@ function setComponentFileValidator(req) {
 	const setCompSchema = Joi.object({
 		project: Joi.string()
 			.pattern(PROJECT_FILE_NAME_REGEX)
+			.custom(checkReservedProjectCreation)
 			.required()
 			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
 		file: Joi.string().custom(checkFilePath).required(),
@@ -214,6 +251,7 @@ function setEnvValueValidator(req) {
 	const schema = Joi.object({
 		project: Joi.string()
 			.pattern(PROJECT_FILE_NAME_REGEX)
+			.custom(checkReservedProjectCreation)
 			.required()
 			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
 		file: Joi.string().custom(checkFilePath).optional(),
@@ -330,6 +368,7 @@ function addComponentValidator(req) {
 	const addFuncSchema = Joi.object({
 		project: Joi.string()
 			.pattern(PROJECT_FILE_NAME_REGEX)
+			.custom(checkReservedProjectName)
 			.custom(checkProjectExists.bind(null, false))
 			.required()
 			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
@@ -455,10 +494,36 @@ function deployComponentValidator(req) {
 	const deployProjSchema = Joi.object({
 		project: Joi.string()
 			.pattern(PROJECT_FILE_NAME_REGEX)
+			.custom(checkReservedProjectName)
 			.required()
 			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
 		package: Joi.string().optional(),
-		restart: Joi.alternatives().try(Joi.boolean(), Joi.string().valid('rolling')).optional(),
+		// `activate: false` builds and certifies the component, then stops, leaving an artifact a later
+		// request activates by `deployment_id`. STRICT: `validateBySchema` throws away Joi's converted
+		// value, so a coercing boolean would let `activate: "false"` validate here and then read as truthy
+		// in the handler — deploying the very release the caller asked not to make live.
+		activate: Joi.boolean().strict().optional(),
+		// Activate a build staged earlier by `activate: false`. It becomes a path segment
+		// (`.deploy-staging/<id>/<component>`), so the charset is pinned as tightly as the value it names.
+		deployment_id: Joi.string().pattern(DEPLOYMENT_ID_REGEX).optional().messages({
+			'string.pattern.base': `'deployment_id' must be a UUID`,
+		}),
+		// Set by deployComponent from the origin's deployment row and carried to peers by replication.
+		// Validated because it is a path segment on EVERY deploy and unknown keys are admitted, so an
+		// operator-supplied one would otherwise reach the filesystem unchecked.
+		_deploymentId: Joi.string().pattern(DEPLOYMENT_ID_REGEX).optional().messages({
+			'string.pattern.base': `'_deploymentId' must be a UUID`,
+		}),
+		restart: Joi.alternatives()
+			.try(Joi.boolean(), Joi.string().valid('rolling'))
+			.optional()
+			// Nothing goes live, so there is nothing to restart into.
+			.when('activate', {
+				is: false,
+				then: Joi.forbidden().messages({
+					'any.unknown': `'restart' cannot be combined with 'activate: false': staging does not change the running component`,
+				}),
+			}),
 		install_command: Joi.string().optional(),
 		install_timeout: Joi.number().optional(),
 		install_allow_scripts: Joi.boolean().optional(),
@@ -496,6 +561,21 @@ function deployComponentValidator(req) {
 			})
 			.optional()
 			.messages({ 'string.bracketedHost': '{#label} must not be bracketed; use the bare IPv6 literal' }),
+		// Databases this application forks a private copy of (harper#642/#643). Deployment routing
+		// like urlPath/host above, not component config: reusing assertBranchedDatabases here (rather
+		// than re-deriving its rules in Joi) gives a synchronous 400 at deploy time instead of a load
+		// failure discovered much later and disconnected from the request that caused it.
+		isolated: Joi.boolean().optional(),
+		branchedDatabases: Joi.custom((value, helpers) => {
+			try {
+				assertBranchedDatabases(req.project, value);
+			} catch (error) {
+				return helpers.error('any.invalid', { reason: error.message });
+			}
+			return value;
+		}, 'branchedDatabases')
+			.optional()
+			.messages({ 'any.invalid': '{{#reason}}' }),
 		// Deploy credentials. The array is kind-heterogeneous: an entry's kind is implied by its
 		// identifying key rather than a separate discriminator field, so a new kind is added as
 		// another item alternative here without reshaping the field. Today: npm registry auth
@@ -527,7 +607,22 @@ function deployComponentValidator(req) {
 		}),
 	})
 		.with('urlPath', 'package')
-		.with('host', 'package');
+		.with('host', 'package')
+		// An activation has no build inputs and takes no routing or packaging opinions: the artifact's own
+		// descriptor is the authority for what it publishes, and silently ignoring these would hide that.
+		.without('deployment_id', [
+			'package',
+			'payload',
+			'activate',
+			'install_command',
+			'install_timeout',
+			'install_allow_scripts',
+			'credentials',
+			'urlPath',
+			'host',
+			'branchedDatabases',
+			'isolated',
+		]);
 
 	return validator.validateBySchema(req, deployProjSchema);
 }

package/components/packageComponent.ts

@@ -1,4 +1,4 @@
-import { join, relative, sep } from 'node:path';
+import { basename, join, relative, sep } from 'node:path';
 import { stat, readdir } from 'node:fs/promises';
 import { Readable, pipeline } from 'node:stream';
 import tar from 'tar-fs';
@@ -13,6 +13,27 @@ const DEFAULT_OPTIONS: PackageOptions = { skip_node_modules: false, skip_symlink
 
 const WEBPACK_CACHE_SEGMENT = join('cache', 'webpack');
 
+/**
+ * `node_modules/harper` is Harper's, whatever is on disk there.
+ *
+ * Every non-root component load runs `symlinkHarperModule`, which does `rmSync(harperModule, {
+ * recursive: true, force: true })` and then links the running install (`components/componentLoader.ts`).
+ * It does that whether or not the path already existed, so component content there survives no load and
+ * packaging it cannot be preserving component source — while packaging it walks the whole install, since
+ * the packer dereferences symlinks and recurses into linked directories.
+ *
+ * `harperdb` is deliberately NOT here, and the asymmetry is the reason: the loader only *repairs*
+ * `node_modules/harperdb` when that path already exists. A legacy component shipping a real
+ * npm-installed `harperdb` that has never been loaded on this host therefore owns it — and excluding it
+ * would strip it from the tarball, after which `installApplication` skips installing (it returns early
+ * when `node_modules` exists), the loader's present-gate never fires, and `import from 'harperdb'`
+ * fails on the target — and that holds whether the path is skipped by name or by resolved identity,
+ * because an archive that simply OMITS it cannot restore it. So a `harperdb` link to the install is
+ * still followed. Closing that means packing a placeholder at the path so the loader's present-gate can
+ * fire on the target, not skipping it; tracked in harper#2577.
+ */
+const INSTALL_OWNED_PATH = join('node_modules', 'harper');
+
 /**
  * Whether `fullPath` (an absolute path under `directory`) should be excluded from the package when
  * `skip_node_modules` is set. The path is first made relative to `directory`, so packaging a component
@@ -21,6 +42,9 @@ const WEBPACK_CACHE_SEGMENT = join('cache', 'webpack');
  * excluded the whole tree. Shared by the stream packer and the directory walk so they cannot diverge.
  */
 function isExcluded(directory: string, fullPath: string, options: PackageOptions): boolean {
+	// Unconditional, including under `skip_symlinks`: packed literally, the link ships an absolute path to
+	// the packaging host's install root, which arrives dangling.
+	if (basename(fullPath) === 'harper' && relative(directory, fullPath) === INSTALL_OWNED_PATH) return true;
 	if (!options.skip_node_modules) return false;
 	const rel = relative(directory, fullPath);
 	return rel.split(sep).includes('node_modules') || rel.includes(WEBPACK_CACHE_SEGMENT);

package/components/requestRestart.ts

@@ -24,6 +24,17 @@ export function requestRestart() {
 	restartArrayBuffer.notify();
 }
 
+export function requestRestartAfterDeploy(
+	isNewComponent: boolean,
+	packageMetadataChanged: boolean,
+	wasIsolated: boolean,
+	isIsolated: boolean
+): boolean {
+	if (!isNewComponent && !packageMetadataChanged && wasIsolated === isIsolated) return false;
+	requestRestart();
+	return true;
+}
+
 export function restartNeeded() {
 	ensureInitialized();
 	return restartNeededArray[0] === 1;

package/components/status/ComponentStatusRegistry.ts

@@ -5,6 +5,7 @@
  * centralized management of component health status.
  */
 
+import { deployValidationStatusSink } from '../../server/serverHelpers/deployValidationState.ts';
 import { ComponentStatus } from './ComponentStatus.ts';
 import {
 	type ComponentStatusLevel,
@@ -24,6 +25,37 @@ export type ComponentStatusMap = Map<string, ComponentStatus>;
  * Component Status Registry Class
  * Provides a centralized registry for managing component health status
  */
+/**
+ * A status copy handed to a validation must share nothing mutable with the live entry. `Error` is reachable
+ * through the public `statusForComponent(...).get()` path, so candidate code could otherwise edit
+ * `message`, `cause` or a custom field on the serving component's own error object. Own enumerable
+ * properties are carried across; `cause` is flattened to a message, because an error graph of unknown depth
+ * is not worth cloning to hand a throwaway load its own read.
+ */
+function detachError(error: Error | string | undefined): Error | string | undefined {
+	if (!(error instanceof Error)) return error;
+	const detached = new Error(error.message);
+	detached.name = error.name;
+	detached.stack = error.stack;
+	for (const [key, value] of Object.entries(error)) {
+		if (key === 'cause') continue;
+		// Detached too where it can be: copying an object property by reference would leave the candidate a
+		// mutable handle into the live error after all. Anything unclonable (a function, a class instance) is
+		// replaced by its string form rather than shared.
+		let detachedValue: unknown;
+		try {
+			detachedValue = structuredClone(value);
+		} catch {
+			detachedValue = typeof value === 'object' && value !== null ? String(value) : value;
+		}
+		(detached as unknown as Record<string, unknown>)[key] = detachedValue;
+	}
+	if (error.cause !== undefined) {
+		detached.cause = error.cause instanceof Error ? `${error.cause.name}: ${error.cause.message}` : error.cause;
+	}
+	return detached;
+}
+
 export class ComponentStatusRegistry {
 	private statusMap: ComponentStatusMap = new Map();
 
@@ -61,6 +93,16 @@ export class ComponentStatusRegistry {
 			);
 		}
 
+		// A deploy's pre-flight validation loads the CANDIDATE's code under the real component's name, so its
+		// writes would land on the live component. They go to the validation's own throwaway map instead —
+		// which is why this cannot simply be reverted afterwards: the live component keeps serving through
+		// that window, and `statusForComponent()` is a public API its own code may call at any time, so
+		// reverting would silently discard a genuine report from it.
+		const sink = deployValidationStatusSink();
+		if (sink) {
+			sink.set(componentName, new ComponentStatus(status, message, error));
+			return;
+		}
 		this.statusMap.set(componentName, new ComponentStatus(status, message, error));
 	}
 
@@ -68,6 +110,23 @@ export class ComponentStatusRegistry {
 	 * Get the current status of a component
 	 */
 	public getStatus(componentName: string): ComponentStatus | undefined {
+		// Inside a validation the candidate reads its OWN writes, and never the live object: the returned
+		// `ComponentStatus` is mutable, so handing back the live one would let candidate code edit the
+		// serving component's status in place and bypass the diversion entirely. A component the candidate
+		// has not written yet is copied into the sink on first read for the same reason.
+		const sink = deployValidationStatusSink();
+		if (sink) {
+			const diverted = sink.get(componentName);
+			if (diverted) return diverted;
+			const live = this.statusMap.get(componentName);
+			if (!live) return undefined;
+			const copy = new ComponentStatus(live.status, live.message, detachError(live.error));
+			// A new Date, not the live one: `Date` is mutable, so sharing it would let candidate code reach
+			// back into the serving component's status through the copy.
+			copy.lastChecked = new Date(live.lastChecked);
+			sink.set(componentName, copy);
+			return copy;
+		}
 		return this.statusMap.get(componentName);
 	}
 

package/config/RootConfigWatcher.ts

@@ -1,38 +1,124 @@
-import chokidar, { FSWatcher } from 'chokidar';
-import { readFile } from 'node:fs/promises';
+import { FSWatcher } from 'chokidar';
 import { getConfigFilePath } from './configUtils.ts';
+import { readConfigFileSync } from './readConfigFileSync.ts';
 import { EventEmitter, once } from 'node:events';
-import { parse } from 'yaml';
-import { POLLING_FALLBACK_OPTIONS, isWatcherExhaustionError, warnWatcherFallback } from '../utility/watcherFallback.ts';
+import { parseConfigFile } from './parseConfigFile.ts';
+import {
+	POLLING_FALLBACK_OPTIONS,
+	claimLostNativeWatchError,
+	guardedWatch,
+	isWatcherExhaustionError,
+	warnWatcherFallback,
+} from '../utility/watcherFallback.ts';
+import { resolveWatchTarget } from '../utility/watchPath.ts';
+import { errorForLog, loggerWithTag } from '../utility/logging/harper_logger.ts';
+import { ConfigReadRetry } from './configReadRetry.ts';
+import { ArmGate } from './watcherArming.ts';
+
+function isMissingFile(error: unknown): boolean {
+	return !!error && typeof error === 'object' && (error as NodeJS.ErrnoException).code === 'ENOENT';
+}
+
+// `harper_logger` imports this module at its own bottom to break their cycle, so a tagged logger
+// built at module scope would run `loggerWithTag()` before `mainLogger` is initialized.
+let taggedLogger: ReturnType<typeof loggerWithTag> | undefined;
+function logger() {
+	return (taggedLogger ??= loggerWithTag('config-watcher'));
+}
+
+let sharedWatcher: RootConfigWatcher | undefined;
+
+/**
+ * The isolate-wide watcher for the root config file. Consumers (logging, models) subscribe to this
+ * one instance instead of each opening their own native watcher — per-worker duplicates double the
+ * inotify/FD footprint and the synchronous read+parse work on every config write.
+ */
+export function getSharedRootConfigWatcher(): RootConfigWatcher {
+	return (sharedWatcher ??= new RootConfigWatcher());
+}
 
 export class RootConfigWatcher extends EventEmitter {
 	#configFilePath: string;
+	#watchPath: string;
 	#watcher!: FSWatcher;
 	#config: any;
 	#usingPolling: boolean;
 	#closed: boolean;
 	#openCount: number = 0;
+	#readCount: number = 0;
+	#readRetry: ConfigReadRetry = new ConfigReadRetry();
+	#armGate: ArmGate = new ArmGate();
+	// The gate above is chokidar's scan finishing; this is the barrier's gate. A terminal outcome
+	// opens it without claiming the watch is armed, so the arming re-read still runs afterwards.
+	#barrierOpen: boolean = false;
+	#configLoaded: boolean = false;
+	#readyStaged: boolean = false;
+	#readyEmitted: boolean = false;
 	ready: Promise<any[]>;
 
-	constructor() {
+	constructor(configFilePath: string = getConfigFilePath()) {
 		super();
-		this.#configFilePath = getConfigFilePath();
-		this.#usingPolling = false;
+		this.#configFilePath = configFilePath;
+		const watchTarget = resolveWatchTarget(this.#configFilePath);
+		this.#watchPath = watchTarget.path;
+		this.#usingPolling = watchTarget.mustPoll;
 		this.#closed = false;
 		this.ready = once(this, 'ready');
 		this.#openWatcher();
 	}
 
 	#openWatcher() {
-		this.#openCount++;
-		this.#watcher = chokidar
-			.watch(this.#configFilePath, {
-				persistent: false,
-				...(this.#usingPolling ? POLLING_FALLBACK_OPTIONS : {}),
-			})
+		const generation = ++this.#openCount;
+		this.#watcher = guardedWatch(this.#watchPath, {
+			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));
+			.on('error', this.handleError.bind(this))
+			// Generation-bound: `#armGate.reset()` runs before the failed watcher is closed, so a
+			// `ready` still queued on it would arm the gate on the replacement's behalf and the
+			// replacement's own `ready` would then be a no-op — leaving its scan window unre-read.
+			.on('ready', () => this.#handleArmed(generation));
+	}
+
+	#handleArmed(generation: number) {
+		if (this.#closed || generation !== this.#openCount) return;
+		this.#armGate.arm(() => this.#markArmed());
+	}
+
+	#markArmed() {
+		this.#barrierOpen = true;
+		// A write that landed while the watch was unarmed was never reported, and a scan that found
+		// no file at all reported nothing either, so arming always re-reads rather than publishing
+		// what an earlier read staged — or, with no file, staying pending forever.
+		this.#read(true);
+		// A read that armed the ladder settles `ready` itself, with the newer config.
+		if (!this.#readRetry.pending) this.#emitReady();
+	}
+
+	#emitReady() {
+		if (this.#readyEmitted || !this.#barrierOpen || !this.#readyStaged || this.#closed) return;
+		this.#readyEmitted = true;
+		try {
+			this.emit('ready', this.#config);
+		} catch (error) {
+			logger().warn('A Harper configuration listener failed', errorForLog(error));
+		}
+	}
+
+	// `harper_logger.start()` awaits `ready` with no timeout, so every terminal outcome has to
+	// settle the barrier. A failed read discards an earlier staged value, but a watcher error keeps
+	// it because no later read superseded it. No config is represented by `undefined`, not `{}`:
+	// an empty object is a configuration that turns logging off.
+	#stageBootFallback(discardStaged = true) {
+		if (this.#readyEmitted) return;
+		if (discardStaged) {
+			this.#config = undefined;
+			this.#configLoaded = false;
+		}
+		this.#readyStaged = true;
+		this.#emitReady();
 	}
 
 	// Test-only: simulate the underlying chokidar watcher emitting an error.
@@ -42,17 +128,29 @@ export class RootConfigWatcher extends EventEmitter {
 		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;
 	}
 
+	// Distinguishes a ladder rung from a watcher event.
+	get _readCountForTests(): number {
+		return this.#readCount;
+	}
+
+	get _armedForTests(): boolean {
+		return this.#armGate.armed;
+	}
+
 	handleError(error: unknown) {
+		// A queued chokidar error can land after close(), which has dropped every listener.
+		if (this.#closed) return;
+		// See EntryHandler.#handleWatcherError: a lost native watch handle is benign
+		// and must not be surfaced to consumers as a config-watch failure.
+		if (claimLostNativeWatchError(error)) return;
 		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
@@ -60,47 +158,149 @@ export class RootConfigWatcher extends EventEmitter {
 			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()
+				// The generation that just failed no longer speaks for the watch; the replacement
+				// arms on its own scan, and re-reads then as the first one did.
+				this.#armGate.reset();
+				// Start close() from a microtask, not directly here, so a synchronous throw
+				// can't escape this 'error' listener as an uncaught exception.
+				Promise.resolve()
+					.then(() => this.#watcher.close())
 					.catch(() => {
 						// Teardown errors on an already-failed watcher are not actionable.
 					})
-					.finally(() => {
+					.then(() => {
 						if (!this.#closed) this.#openWatcher();
-					});
+					})
+					.catch((error) =>
+						logger().warn(`Could not reopen the ${this.#configFilePath} watch on polling`, errorForLog(error))
+					);
+			} else {
+				// Already polling — the replacement failed too, or the watch was polling from
+				// construction (`mustPoll`) and never had a fallback to take. Either way the branch
+				// above reopens only once, so this is the watch's terminal outcome and the barrier
+				// has to settle or `harper_logger.start()` awaits it forever.
+				this.#barrierOpen = true;
+				this.#stageBootFallback(false);
 			}
 			return;
 		}
-		this.emit('error', error);
+		// chokidar may never reach its own `ready` after a scan error, and nothing else would
+		// settle the barrier: the error is this read's terminal outcome. The scan is not over
+		// though, so the arm gate stays closed and a later `ready` still takes the arming re-read.
+		this.#barrierOpen = true;
+		this.#stageBootFallback(false);
+		// Settling the barrier removed the `error` listener `once(this, 'ready')` attached, and an
+		// emit with none left throws the error back into chokidar's dispatch — as does a consumer
+		// that throws from its own handler.
+		if (this.listenerCount('error') === 0) {
+			logger().warn(`The Harper configuration watcher at ${this.#configFilePath} failed`, errorForLog(error));
+			return;
+		}
+		try {
+			this.emit('error', error);
+		} catch (listenerError) {
+			logger().warn('A Harper configuration error listener failed', errorForLog(listenerError));
+		}
 	}
 
 	handleChange() {
-		readFile(this.#configFilePath, 'utf-8')
-			.then((data) => {
-				if (!data) return;
+		this.#read(true);
+	}
 
-				const config = parse(data);
+	// `harper_logger.start()` awaits `ready` with no timeout and the ladder may be the only thing
+	// left to settle it, so until then its timer keeps the thread alive rather than letting it
+	// drain and exit mid-boot.
+	#schedule(): boolean {
+		return this.#readRetry.schedule(() => this.#read(false), !this.#readyEmitted);
+	}
 
-				if (!this.#config) {
-					this.#config = config;
-					this.emit('ready', this.#config);
-					return;
-				}
+	#read(waitForLock: boolean) {
+		// A queued chokidar callback can still land after close(), which has already discarded the
+		// config and dropped every listener.
+		if (this.#closed) return;
+		this.#readCount++;
+		let data: string;
+		try {
+			data = readConfigFileSync(this.#configFilePath, waitForLock);
+		} catch (error) {
+			// A missing file is not a lock — `readConfigFileSync` does not retry it either, and
+			// `OptionsWatcher` settles it immediately as the install window. Taking the ladder here
+			// would disagree with that and cost `harper_logger.start()` the whole budget on every
+			// boot that has no config file (an env-var-only deployment, an empty mounted rootPath).
+			if (!isMissingFile(error) && this.#schedule()) return;
+			// A ladder armed by an earlier empty read is spent by the time a rung lands on ENOENT,
+			// and every other terminal path clears its deadline.
+			this.#readRetry.reset();
+			logger().warn(
+				`Unable to read the Harper configuration file at ${this.#configFilePath}` +
+					(this.#configLoaded ? ', continuing with the previously loaded configuration' : '; none has been loaded yet'),
+				errorForLog(error)
+			);
+			this.#stageBootFallback();
+			return;
+		}
+		// See DESIGN.md, "An empty read is a writer mid-write, not an empty config".
+		if (!data) {
+			if (this.#schedule()) return;
+			logger().warn(`The Harper configuration file at ${this.#configFilePath} is empty`);
+			this.#stageBootFallback();
+			return;
+		}
+		let config;
+		try {
+			config = parseConfigFile(data, this.#configFilePath);
+		} catch (error) {
+			// A read taken mid-write is untrustworthy, not only an empty one: the writer's first
+			// `write(2)` can land a prefix of the document, and the event carrying the rest is the one
+			// chokidar throttles away. So an unparseable read rides out the same ladder as an empty
+			// one, and only a read that parses releases it.
+			if (this.#schedule()) return;
+			logger().warn((error as Error).message);
+			this.#stageBootFallback();
+			return;
+		}
+		// The third shape a mid-write read takes, and the only one that parses: a truncated
+		// document, a lone `\n`, a file that is nothing but comments all yield `null` rather than
+		// throwing, and adopting one hands every consumer a config with nothing in it. Same ladder
+		// as the two above, and past it the file is empty rather than mid-write.
+		if (!config || typeof config !== 'object') {
+			if (this.#schedule()) return;
+			logger().warn(`The Harper configuration file at ${this.#configFilePath} is empty`);
+			this.#stageBootFallback();
+			return;
+		}
+		this.#readRetry.reset();
 
-				this.emit('change', (this.#config = config));
-			})
-			.catch((_error) => {
-				// if yaml parse error ignore?
-			});
+		// Before `ready` goes out there is no prior state to have changed *since*.
+		this.#configLoaded = true;
+		this.#readyStaged = true;
+		if (!this.#readyEmitted) {
+			this.#config = config;
+			this.#emitReady();
+			return;
+		}
+
+		try {
+			this.emit('change', (this.#config = config));
+		} catch (error) {
+			logger().warn('A Harper configuration change listener failed', errorForLog(error));
+		}
 	}
 
 	close() {
+		// Closing is a terminal outcome too: leaving `ready` pending would hang anything still
+		// awaiting the barrier. Through `#emitReady`, so a listener that throws cannot skip the
+		// teardown below it and leave the watcher and its arm timer running.
+		this.#barrierOpen = true;
+		this.#readyStaged = true;
+		this.#emitReady();
 		this.#closed = true;
-		this.#watcher.close();
+		this.#readRetry.cancel();
+		this.#armGate.cancel();
+		// chokidar's close() is a promise; an unhandled teardown rejection would reach Node as one,
+		// on the path whose whole job is to stop caring about this watcher. Same shape as the
+		// exhaustion-recovery close above, and as `OptionsWatcher.close`.
+		Promise.resolve(this.#watcher.close()).catch(() => {});
 		this.#config = undefined;
 		this.emit('close');
 		this.removeAllListeners();