@harperfast/harper 5.3.0-alpha.1 → 5.3.0-beta.1

package/config/RootConfigWatcher.ts

@@ -1,19 +1,30 @@
 import { FSWatcher } from 'chokidar';
-import { readFileSync } from 'node:fs';
 import { getConfigFilePath } from './configUtils.ts';
+import { readConfigFileSync } from './readConfigFileSync.ts';
 import { EventEmitter, once } from 'node:events';
-import { parse } from 'yaml';
+import { parseConfigFile } from './parseConfigFile.ts';
 import {
 	POLLING_FALLBACK_OPTIONS,
-	PartialReadRetry,
 	claimLostNativeWatchError,
 	guardedWatch,
-	isPartialReadError,
 	isWatcherExhaustionError,
 	warnWatcherFallback,
-	warnWatcherListenerError,
 } 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;
 
@@ -34,7 +45,15 @@ export class RootConfigWatcher extends EventEmitter {
 	#usingPolling: boolean;
 	#closed: boolean;
 	#openCount: number = 0;
-	#partialRead: PartialReadRetry;
+	#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(configFilePath: string = getConfigFilePath()) {
@@ -42,7 +61,6 @@ export class RootConfigWatcher extends EventEmitter {
 		this.#configFilePath = configFilePath;
 		const watchTarget = resolveWatchTarget(this.#configFilePath);
 		this.#watchPath = watchTarget.path;
-		this.#partialRead = new PartialReadRetry(this.#configFilePath);
 		this.#usingPolling = watchTarget.mustPoll;
 		this.#closed = false;
 		this.ready = once(this, 'ready');
@@ -50,14 +68,57 @@ export class RootConfigWatcher extends EventEmitter {
 	}
 
 	#openWatcher() {
-		this.#openCount++;
+		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.
@@ -67,17 +128,26 @@ 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;
@@ -88,6 +158,9 @@ export class RootConfigWatcher extends EventEmitter {
 			if (!this.#usingPolling) {
 				warnWatcherFallback(this.#configFilePath);
 				this.#usingPolling = true;
+				// 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()
@@ -98,55 +171,136 @@ export class RootConfigWatcher extends EventEmitter {
 					.then(() => {
 						if (!this.#closed) this.#openWatcher();
 					})
-					.catch((error) => console.error(`Could not reopen the ${this.#configFilePath} watch on polling:`, error));
+					.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));
+		}
 	}
 
-	// See the descriptor-lifetime invariant on atomicWriteFile (DESIGN.md).
 	handleChange() {
+		this.#read(true);
+	}
+
+	// `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);
+	}
+
+	#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;
-		// Only the read and parse are guarded: a listener that throws must not be mistaken for a
-		// half-written file and replayed.
 		try {
-			config = parse(readFileSync(this.#configFilePath, 'utf-8'));
+			config = parseConfigFile(data, this.#configFilePath);
 		} catch (error) {
-			// A missing file needs no re-read; anything else may be the file being replaced.
-			if (isPartialReadError(error)) this.#scheduleReread(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;
 		}
-		// A snapshot that does not parse to an object is the other shape a half-written file
-		// takes: `''`, `'\n'` and a truncated document all yield null, and adopting that would
-		// hand every consumer a config with nothing in it.
+		// 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') {
-			this.#scheduleReread();
+			if (this.#schedule()) return;
+			logger().warn(`The Harper configuration file at ${this.#configFilePath} is empty`);
+			this.#stageBootFallback();
+			return;
+		}
+		this.#readRetry.reset();
+
+		// 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;
 		}
-		this.#partialRead.settled();
 
 		try {
-			if (!this.#config) {
-				this.#config = config;
-				this.emit('ready', this.#config);
-				return;
-			}
 			this.emit('change', (this.#config = config));
 		} catch (error) {
-			warnWatcherListenerError(this.#configFilePath, error);
+			logger().warn('A Harper configuration change listener failed', errorForLog(error));
 		}
 	}
 
-	#scheduleReread(error?: unknown) {
-		if (this.#partialRead.schedule(() => this.handleChange())) return;
-		this.#partialRead.gaveUp(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.#partialRead.cancel();
-		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();

package/config/configReadRetry.ts

@@ -0,0 +1,62 @@
+// Why a lock that outlives the reader's budget is retried from a timer, and why both the bound and
+// the backoff are wall clock rather than an attempt count: see "Root config watchers must read
+// synchronously" in DESIGN.md (harper#2191).
+const RETRY_BUDGET_MS = 3_100;
+const INITIAL_DELAY_MS = 100;
+const MAX_DELAY_MS = 1_600;
+
+let retryBudgetMs = RETRY_BUDGET_MS;
+
+// Test-only, the read-side twin of `atomicWriteFile`'s `retryBudgetMs` option. A case that only
+// needs the ladder *spent* has no way to get there but wall clock, so without this each one sits
+// out the shipped 3.1 s; a dozen of them cost the unit job 40 s. Called with no argument it
+// restores the shipped value, and `configReadRetry.test.js` still spends that value in full, so
+// shortening it elsewhere cannot hide a change to what ships.
+export function _setRetryBudgetForTests(ms: number = RETRY_BUDGET_MS): void {
+	retryBudgetMs = ms;
+}
+
+export class ConfigReadRetry {
+	#timer?: NodeJS.Timeout;
+	#deadline?: number;
+	// Captured with the deadline: the backoff is a fraction of the budget the deadline came from,
+	// so reading the module value again mid-ladder would mis-scale it if a test had changed it.
+	#budgetMs: number = retryBudgetMs;
+
+	// `holdEventLoop` is for a caller whose boot barrier this ladder is the only thing left to
+	// settle: an unref'd timer would let the thread drain and exit mid-boot instead.
+	schedule(retry: () => void, holdEventLoop: boolean = false): boolean {
+		this.cancel();
+		const now = performance.now();
+		if (this.#deadline === undefined) {
+			this.#budgetMs = retryBudgetMs;
+			this.#deadline = now + this.#budgetMs;
+		}
+		const remainingMs = this.#deadline - now;
+		if (remainingMs <= 0) {
+			this.reset();
+			return false;
+		}
+		const elapsedMs = this.#budgetMs - remainingMs;
+		const delayMs = Math.min(Math.max(elapsedMs, INITIAL_DELAY_MS), MAX_DELAY_MS, remainingMs);
+		this.#timer = setTimeout(retry, delayMs);
+		if (!holdEventLoop) this.#timer.unref();
+		return true;
+	}
+
+	get pending(): boolean {
+		return this.#timer !== undefined;
+	}
+
+	reset(): void {
+		this.cancel();
+		this.#deadline = undefined;
+	}
+
+	cancel(): void {
+		if (this.#timer) {
+			clearTimeout(this.#timer);
+			this.#timer = undefined;
+		}
+	}
+}

package/config/configUtils.ts

@@ -92,22 +92,56 @@ export function getConfigPath(param: string) {
 	return path.resolve(rootPath, value);
 }
 
-// Write atomically via temp file + rename so readers don't observe a truncated/empty file.
-// Temp path includes randomness so two worker threads in the same process (same pid) writing
-// in the same millisecond can't collide on the temp name and then race the rename.
-//
+// Write atomically via a randomized temp file + rename so readers do not observe partial content
+// and concurrent workers, which share process.pid, do not collide on a temp path.
 // Windows has no POSIX-style "replace an open file" semantics: rename() fails with
-// EPERM/EACCES while another descriptor is open on the destination. The sleep below blocks the
-// calling thread, so this can only ride out a holder that releases without needing that
-// thread's event loop. A holder on the calling thread would live exactly as long as the budget,
-// which is why config readers must not keep a descriptor on this file open across an event-loop
-// turn (RootConfigWatcher.handleChange, OptionsWatcher#handleChange).
-const RENAME_RETRY_MAX_ATTEMPTS = 12;
+// EPERM/EACCES/EBUSY while another worker or AV holds the destination open. Root config watchers use
+// readConfigFileSync so this blocking retry cannot wait on a read owned by its own worker.
+// The budget is the wall-clock window of the 12-attempt schedule it replaced
+// (10+20+40+80+160+320+500*6), so it stays a deadline rather than an attempt count without
+// widening the stall: this loop blocks the calling worker's event loop, and `set_configuration`
+// reaches it from a live request thread.
+const RENAME_RETRY_BUDGET_MS = 3_630;
+// Secondary guard only: stops a degenerate zero-delay option set from spinning the whole budget.
+const RENAME_RETRY_MAX_ATTEMPTS = 25;
 const RENAME_RETRY_INITIAL_DELAY_MS = 10;
 const RENAME_RETRY_MAX_DELAY_MS = 500;
-// Never notified; exists only so Atomics.wait can time out (a synchronous, CPU-idle sleep).
+// Never notified; Atomics.wait uses this only as a CPU-idle synchronous sleep.
 const renameRetrySleepBuffer = new Int32Array(new SharedArrayBuffer(4));
 
+// Classified by code alone rather than gated to win32 like the read side: `process.platform` does
+// not answer whether this filesystem can replace an open file — WSL drvfs, CIFS/SMB and Docker
+// Desktop bind mounts all report `linux` and return these codes transiently.
+function isRetryableRenameError(code: string): boolean {
+	return code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
+}
+
+type RenameRetryOptions = {
+	retryBudgetMs?: number;
+	maxRetries?: number;
+	initialDelayMs?: number;
+	maxDelayMs?: number;
+};
+
+type AtomicWriteOptions = RenameRetryOptions & {
+	skipIfUnchanged?: boolean;
+};
+
+function validateRenameRetryOptions({ retryBudgetMs, maxRetries, initialDelayMs, maxDelayMs }: RenameRetryOptions) {
+	const invalidOption =
+		!Number.isFinite(retryBudgetMs) ||
+		retryBudgetMs < 0 ||
+		(!Number.isFinite(maxRetries) && maxRetries !== Infinity) ||
+		maxRetries < 0 ||
+		!Number.isFinite(initialDelayMs) ||
+		initialDelayMs < 0 ||
+		!Number.isFinite(maxDelayMs) ||
+		maxDelayMs < 0;
+	if (invalidOption) {
+		throw new RangeError('rename retry options must be non-negative numbers');
+	}
+}
+
 // Linux has no libuv mapping for EDQUOT, so a quota-exhausted write surfaces as
 // `Unknown system error -122` with an unusable `code`; the numeric errno is the portable signal
 // (EDQUOT is 122 on Linux, 69 on macOS).
@@ -142,12 +176,15 @@ export function atomicWriteFile(
 	filePath,
 	content,
 	{
+		retryBudgetMs = RENAME_RETRY_BUDGET_MS,
 		maxRetries = RENAME_RETRY_MAX_ATTEMPTS,
 		initialDelayMs = RENAME_RETRY_INITIAL_DELAY_MS,
 		maxDelayMs = RENAME_RETRY_MAX_DELAY_MS,
 		skipIfUnchanged = false,
-	} = {}
+	}: AtomicWriteOptions = {}
 ) {
+	// Before the temp write, so an option set that can never rename leaves no file behind.
+	validateRenameRetryOptions({ retryBudgetMs, maxRetries, initialDelayMs, maxDelayMs });
 	// Opt-in: skipping means no mtime bump, so no watcher event. Only callers that re-derive the
 	// same file every boot want that.
 	if (skipIfUnchanged && matchesFileContent(filePath, content)) return false;
@@ -160,8 +197,10 @@ export function atomicWriteFile(
 		throw err;
 	}
 	try {
-		renameWithRetry(tempPath, filePath, { maxRetries, initialDelayMs, maxDelayMs });
+		renameWithRetry(tempPath, filePath, { retryBudgetMs, maxRetries, initialDelayMs, maxDelayMs });
 	} catch (err) {
+		// The temp name carries fresh randomness on every call, so a spent budget would otherwise
+		// leave a file nothing else will ever collect.
 		removeTempFile(tempPath);
 		throw err;
 	}
@@ -172,35 +211,48 @@ export function renameWithRetry(
 	fromPath,
 	toPath,
 	{
+		retryBudgetMs = RENAME_RETRY_BUDGET_MS,
 		maxRetries = RENAME_RETRY_MAX_ATTEMPTS,
 		initialDelayMs = RENAME_RETRY_INITIAL_DELAY_MS,
 		maxDelayMs = RENAME_RETRY_MAX_DELAY_MS,
-	} = {}
+	}: RenameRetryOptions = {}
 ) {
+	validateRenameRetryOptions({ retryBudgetMs, maxRetries, initialDelayMs, maxDelayMs });
 	let retries = maxRetries;
 	let delayMs = initialDelayMs;
+	let retryDeadline;
+	let finalAttempt = false;
 	let attempts = 0;
-	const startedAt = Date.now();
+	const startedAt = performance.now();
 	while (true) {
 		try {
 			attempts++;
 			fs.renameSync(fromPath, toPath);
 			return;
 		} catch (err) {
-			if (retries > 0 && (err.code === 'EPERM' || err.code === 'EACCES')) {
+			if (!finalAttempt && retries > 0 && isRetryableRenameError(err.code)) {
 				retries--;
-				// Sleep synchronously (all call sites are sync) to allow the holder to close the
-				// file. Atomics.wait yields the thread to the OS instead of spinning the CPU,
-				// which is what makes a multi-second worst-case budget affordable.
-				if (delayMs > 0) Atomics.wait(renameRetrySleepBuffer, 0, 0, delayMs);
-				delayMs = Math.min(delayMs * 2, maxDelayMs);
-				continue;
+				if (retryDeadline === undefined) {
+					retryDeadline = performance.now() + retryBudgetMs;
+				}
+				const remainingBudgetMs = retryDeadline - performance.now();
+				if (remainingBudgetMs > 0) {
+					// Sleep synchronously (all call sites are sync) to allow the holder to close the
+					// file. Atomics.wait yields the thread to the OS instead of spinning the CPU,
+					// which is what makes a multi-second worst-case budget affordable.
+					const sleepMs = Math.min(delayMs, remainingBudgetMs);
+					finalAttempt = sleepMs === remainingBudgetMs;
+					if (sleepMs > 0) Atomics.wait(renameRetrySleepBuffer, 0, 0, sleepMs);
+					delayMs = Math.min(Math.max(delayMs * 2, RENAME_RETRY_INITIAL_DELAY_MS), maxDelayMs);
+					continue;
+				}
 			}
-			// Attempts and elapsed distinguish a holder that never released from one that lost
-			// a race, and neither survives on the rethrown error.
-			if (err.code === 'EPERM' || err.code === 'EACCES') {
+			// Whether the budget was spent or the code was never retryable is the difference
+			// between a holder that never released and a one-off failure, and neither survives on
+			// the rethrown error.
+			if (isRetryableRenameError(err.code)) {
 				logger.warn(
-					`Could not replace ${toPath}: ${err.code} after ${attempts} attempts over ${Date.now() - startedAt}ms`
+					`Could not replace ${toPath}: ${err.code} after ${attempts} attempts over ${Math.round(performance.now() - startedAt)}ms`
 				);
 			}
 			throw err;

package/config/parseConfigFile.ts

@@ -0,0 +1,34 @@
+import { parse } from 'yaml';
+
+// yaml's prettyErrors frames the offending source lines into `message`, and a config file holds
+// credentials. Neither the cause nor the original stack is carried for the same reason.
+export class ConfigParseError extends Error {
+	constructor(filePath: string, error: unknown) {
+		const { name, code, linePos } = (error ?? {}) as {
+			name?: string;
+			code?: string;
+			linePos?: { line: number; col: number }[];
+		};
+		const at = linePos?.[0] ? ` at line ${linePos[0].line}, column ${linePos[0].col}` : '';
+		super(`Unable to parse the Harper configuration file at ${filePath}: ${code ?? name ?? 'parse failure'}${at}`);
+		this.name = 'ConfigParseError';
+	}
+}
+
+export function parseConfigFile(contents: string, filePath: string): any {
+	try {
+		// yaml routes warnings through `process.emitWarning` rather than a throw, so a framed
+		// warning would reach stderr with the config's own source lines in it, around this scrub.
+		return parse(contents, { logLevel: 'error' });
+	} catch (error) {
+		// Only yaml's own parse errors frame the source into `message`. Anything else is a fault in
+		// the parser, where the message is the whole of the debugging context.
+		if (!isYamlParseError(error)) throw error;
+		throw new ConfigParseError(filePath, error);
+	}
+}
+
+function isYamlParseError(error: unknown): boolean {
+	const { name, linePos } = (error ?? {}) as { name?: string; linePos?: unknown };
+	return linePos !== undefined || name === 'YAMLParseError';
+}

package/config/readConfigFileSync.ts

@@ -0,0 +1,44 @@
+import { readFileSync } from 'node:fs';
+
+// Why root config reads must not be async, and why this budget is shared rather than per call:
+// see "Root config watchers must read synchronously" in DESIGN.md (harper#2191).
+const READ_RETRY_BUDGET_MS = 500;
+const READ_RETRY_INITIAL_DELAY_MS = 10;
+const READ_RETRY_MAX_DELAY_MS = 100;
+const readRetrySleepBuffer = new Int32Array(new SharedArrayBuffer(4));
+const retryDeadlines = new Map<string, number>();
+
+// A caller that already owns a retry ladder passes `waitForLock` false, so one lock costs one
+// blocking window in total rather than one per rung.
+export function readConfigFileSync(filePath: string, waitForLock: boolean = true): string {
+	let delayMs = READ_RETRY_INITIAL_DELAY_MS;
+	while (true) {
+		try {
+			const contents = readFileSync(filePath, 'utf-8');
+			retryDeadlines.delete(filePath);
+			return contents;
+		} catch (error) {
+			const remainingBudgetMs = waitForLock && isSharingViolation(error) ? remainingRetryBudgetMs(filePath) : 0;
+			if (remainingBudgetMs <= 0) throw error;
+			Atomics.wait(readRetrySleepBuffer, 0, 0, Math.min(delayMs, remainingBudgetMs));
+			delayMs = Math.min(delayMs * 2, READ_RETRY_MAX_DELAY_MS);
+		}
+	}
+}
+
+function isSharingViolation(error: unknown): boolean {
+	if (process.platform !== 'win32') return false;
+	const code = (error as { code?: string } | null)?.code;
+	return code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
+}
+
+function remainingRetryBudgetMs(filePath: string): number {
+	const now = performance.now();
+	let deadline = retryDeadlines.get(filePath);
+	// A deadline more than one budget past its expiry belongs to an earlier burst, not this one.
+	if (deadline === undefined || now - deadline > READ_RETRY_BUDGET_MS) {
+		deadline = now + READ_RETRY_BUDGET_MS;
+		retryDeadlines.set(filePath, deadline);
+	}
+	return deadline - now;
+}