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

package/dist/config/RootConfigWatcher.js

@@ -2,12 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RootConfigWatcher = void 0;
 exports.getSharedRootConfigWatcher = getSharedRootConfigWatcher;
-const node_fs_1 = require("node:fs");
 const configUtils_ts_1 = require("./configUtils.js");
+const readConfigFileSync_ts_1 = require("./readConfigFileSync.js");
 const node_events_1 = require("node:events");
-const yaml_1 = require("yaml");
+const parseConfigFile_ts_1 = require("./parseConfigFile.js");
 const watcherFallback_ts_1 = require("../utility/watcherFallback.js");
 const watchPath_ts_1 = require("../utility/watchPath.js");
+const harper_logger_ts_1 = require("../utility/logging/harper_logger.js");
+const configReadRetry_ts_1 = require("./configReadRetry.js");
+const watcherArming_ts_1 = require("./watcherArming.js");
+function isMissingFile(error) {
+    return !!error && typeof error === 'object' && error.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;
+function logger() {
+    return (taggedLogger ??= (0, harper_logger_ts_1.loggerWithTag)('config-watcher'));
+}
 let sharedWatcher;
 /**
  * The isolate-wide watcher for the root config file. Consumers (logging, models) subscribe to this
@@ -25,28 +37,79 @@ class RootConfigWatcher extends node_events_1.EventEmitter {
     #usingPolling;
     #closed;
     #openCount = 0;
-    #partialRead;
+    #readCount = 0;
+    #readRetry = new configReadRetry_ts_1.ConfigReadRetry();
+    #armGate = new watcherArming_ts_1.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 = false;
+    #configLoaded = false;
+    #readyStaged = false;
+    #readyEmitted = false;
     ready;
     constructor(configFilePath = (0, configUtils_ts_1.getConfigFilePath)()) {
         super();
         this.#configFilePath = configFilePath;
         const watchTarget = (0, watchPath_ts_1.resolveWatchTarget)(this.#configFilePath);
         this.#watchPath = watchTarget.path;
-        this.#partialRead = new watcherFallback_ts_1.PartialReadRetry(this.#configFilePath);
         this.#usingPolling = watchTarget.mustPoll;
         this.#closed = false;
         this.ready = (0, node_events_1.once)(this, 'ready');
         this.#openWatcher();
     }
     #openWatcher() {
-        this.#openCount++;
+        const generation = ++this.#openCount;
         this.#watcher = (0, watcherFallback_ts_1.guardedWatch)(this.#watchPath, {
             persistent: false,
             ...(this.#usingPolling ? watcherFallback_ts_1.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) {
+        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', (0, harper_logger_ts_1.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.
     // Exposed so the polling-fallback path can be exercised without triggering a
@@ -54,15 +117,23 @@ class RootConfigWatcher extends node_events_1.EventEmitter {
     _simulateWatcherErrorForTests(error) {
         this.handleError(error);
     }
-    // Test-only: whether the watcher has fallen back to polling.
     get _usingPollingForTests() {
         return this.#usingPolling;
     }
-    // Test-only: number of times the underlying watcher has been (re)opened.
     get _openCountForTests() {
         return this.#openCount;
     }
+    // Distinguishes a ladder rung from a watcher event.
+    get _readCountForTests() {
+        return this.#readCount;
+    }
+    get _armedForTests() {
+        return this.#armGate.armed;
+    }
     handleError(error) {
+        // 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 ((0, watcherFallback_ts_1.claimLostNativeWatchError)(error))
@@ -74,6 +145,9 @@ class RootConfigWatcher extends node_events_1.EventEmitter {
             if (!this.#usingPolling) {
                 (0, watcherFallback_ts_1.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()
@@ -85,55 +159,135 @@ class RootConfigWatcher extends node_events_1.EventEmitter {
                     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`, (0, harper_logger_ts_1.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;
+        }
+        // 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`, (0, harper_logger_ts_1.errorForLog)(error));
             return;
         }
-        this.emit('error', error);
+        try {
+            this.emit('error', error);
+        }
+        catch (listenerError) {
+            logger().warn('A Harper configuration error listener failed', (0, harper_logger_ts_1.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() {
+        return this.#readRetry.schedule(() => this.#read(false), !this.#readyEmitted);
+    }
+    #read(waitForLock) {
+        // 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;
+        try {
+            data = (0, readConfigFileSync_ts_1.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'), (0, harper_logger_ts_1.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 = (0, yaml_1.parse)((0, node_fs_1.readFileSync)(this.#configFilePath, 'utf-8'));
+            config = (0, parseConfigFile_ts_1.parseConfigFile)(data, this.#configFilePath);
         }
         catch (error) {
-            // A missing file needs no re-read; anything else may be the file being replaced.
-            if ((0, watcherFallback_ts_1.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.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) {
-            (0, watcherFallback_ts_1.warnWatcherListenerError)(this.#configFilePath, error);
+            logger().warn('A Harper configuration change listener failed', (0, harper_logger_ts_1.errorForLog)(error));
         }
     }
-    #scheduleReread(error) {
-        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/dist/config/RootConfigWatcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"RootConfigWatcher.js","sourceRoot":"","sources":["../../config/RootConfigWatcher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"RootConfigWatcher.js","sourceRoot":"","sources":["../../config/RootConfigWatcher.ts"],"names":[],"mappings":"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"}

package/dist/config/configReadRetry.d.ts

@@ -0,0 +1,8 @@
+export declare function _setRetryBudgetForTests(ms?: number): void;
+export declare class ConfigReadRetry {
+    #private;
+    schedule(retry: () => void, holdEventLoop?: boolean): boolean;
+    get pending(): boolean;
+    reset(): void;
+    cancel(): void;
+}

package/dist/config/configReadRetry.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigReadRetry = void 0;
+exports._setRetryBudgetForTests = _setRetryBudgetForTests;
+// 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.
+function _setRetryBudgetForTests(ms = RETRY_BUDGET_MS) {
+    retryBudgetMs = ms;
+}
+class ConfigReadRetry {
+    #timer;
+    #deadline;
+    // 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 = 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, holdEventLoop = false) {
+        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() {
+        return this.#timer !== undefined;
+    }
+    reset() {
+        this.cancel();
+        this.#deadline = undefined;
+    }
+    cancel() {
+        if (this.#timer) {
+            clearTimeout(this.#timer);
+            this.#timer = undefined;
+        }
+    }
+}
+exports.ConfigReadRetry = ConfigReadRetry;
+//# sourceMappingURL=configReadRetry.js.map

package/dist/config/configReadRetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configReadRetry.js","sourceRoot":"","sources":["../../config/configReadRetry.ts"],"names":[],"mappings":";;;AAcA,0DAEC;AAhBD,mGAAmG;AACnG,+FAA+F;AAC/F,6CAA6C;AAC7C,MAAM,eAAe,GAAG,KAAK,CAAC;AAC9B,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAC7B,MAAM,YAAY,GAAG,KAAK,CAAC;AAE3B,IAAI,aAAa,GAAG,eAAe,CAAC;AAEpC,gGAAgG;AAChG,iGAAiG;AACjG,4FAA4F;AAC5F,gGAAgG;AAChG,8DAA8D;AAC9D,SAAgB,uBAAuB,CAAC,KAAa,eAAe;IACnE,aAAa,GAAG,EAAE,CAAC;AACpB,CAAC;AAED,MAAa,eAAe;IAC3B,MAAM,CAAkB;IACxB,SAAS,CAAU;IACnB,8FAA8F;IAC9F,4FAA4F;IAC5F,SAAS,GAAW,aAAa,CAAC;IAElC,2FAA2F;IAC3F,iFAAiF;IACjF,QAAQ,CAAC,KAAiB,EAAE,gBAAyB,KAAK;QACzD,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAC9B,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,SAAS,GAAG,aAAa,CAAC;YAC/B,IAAI,CAAC,SAAS,GAAG,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC;QACvC,CAAC;QACD,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC;QACzC,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,OAAO,KAAK,CAAC;QACd,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC;QAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,gBAAgB,CAAC,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC;QAC3F,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACzC,IAAI,CAAC,aAAa;YAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACxC,OAAO,IAAI,CAAC;IACb,CAAC;IAED,IAAI,OAAO;QACV,OAAO,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC;IAClC,CAAC;IAED,KAAK;QACJ,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5B,CAAC;IAED,MAAM;QACL,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC1B,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QACzB,CAAC;IACF,CAAC;CACD;AA3CD,0CA2CC"}

package/dist/config/configUtils.d.ts

@@ -5,19 +5,19 @@ export declare function resolvePath(relativePath: string): string;
  * @param param
  */
 export declare function getConfigPath(param: string): any;
-export declare function isStorageExhausted(error: any): boolean;
-export declare function persistConfigDuringBoot(artifactPath: string, write: () => void): boolean;
-export declare function atomicWriteFile(filePath: any, content: any, { maxRetries, initialDelayMs, maxDelayMs, skipIfUnchanged, }?: {
+type RenameRetryOptions = {
+    retryBudgetMs?: number;
     maxRetries?: number;
     initialDelayMs?: number;
     maxDelayMs?: number;
+};
+type AtomicWriteOptions = RenameRetryOptions & {
     skipIfUnchanged?: boolean;
-}): boolean;
-export declare function renameWithRetry(fromPath: any, toPath: any, { maxRetries, initialDelayMs, maxDelayMs, }?: {
-    maxRetries?: number;
-    initialDelayMs?: number;
-    maxDelayMs?: number;
-}): void;
+};
+export declare function isStorageExhausted(error: any): boolean;
+export declare function persistConfigDuringBoot(artifactPath: string, write: () => void): boolean;
+export declare function atomicWriteFile(filePath: any, content: any, { retryBudgetMs, maxRetries, initialDelayMs, maxDelayMs, skipIfUnchanged, }?: AtomicWriteOptions): boolean;
+export declare function renameWithRetry(fromPath: any, toPath: any, { retryBudgetMs, maxRetries, initialDelayMs, maxDelayMs, }?: RenameRetryOptions): void;
 /**
  * Builds the Harper config file using user inputs and default values from defaultConfig.yaml
  * @param args - any args that the user provided.
@@ -137,3 +137,4 @@ export declare function addConfig(topLevelElement: any, values: any): Promise<vo
 export declare function deleteConfigFromFile(param: string): void;
 export declare function getConfigObj(): any;
 export declare function getFlatConfigObj(): any;
+export {};

package/dist/config/configUtils.js

@@ -146,21 +146,41 @@ function getConfigPath(param) {
         return value;
     return path_1.default.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) {
+    return code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
+}
+function validateRenameRetryOptions({ retryBudgetMs, maxRetries, initialDelayMs, maxDelayMs }) {
+    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).
@@ -186,7 +206,9 @@ function persistConfigDuringBoot(artifactPath, write) {
     }
 }
 // Returns true when the file was written, false when an unchanged write was skipped.
-function atomicWriteFile(filePath, content, { maxRetries = RENAME_RETRY_MAX_ATTEMPTS, initialDelayMs = RENAME_RETRY_INITIAL_DELAY_MS, maxDelayMs = RENAME_RETRY_MAX_DELAY_MS, skipIfUnchanged = false, } = {}) {
+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, } = {}) {
+    // 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))
@@ -201,19 +223,24 @@ function atomicWriteFile(filePath, content, { maxRetries = RENAME_RETRY_MAX_ATTE
         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;
     }
     return true;
 }
-function renameWithRetry(fromPath, toPath, { maxRetries = RENAME_RETRY_MAX_ATTEMPTS, initialDelayMs = RENAME_RETRY_INITIAL_DELAY_MS, maxDelayMs = RENAME_RETRY_MAX_DELAY_MS, } = {}) {
+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, } = {}) {
+    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++;
@@ -221,20 +248,29 @@ function renameWithRetry(fromPath, toPath, { maxRetries = RENAME_RETRY_MAX_ATTEM
             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') {
-                harper_logger_ts_1.default.warn(`Could not replace ${toPath}: ${err.code} after ${attempts} attempts over ${Date.now() - startedAt}ms`);
+            // 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)) {
+                harper_logger_ts_1.default.warn(`Could not replace ${toPath}: ${err.code} after ${attempts} attempts over ${Math.round(performance.now() - startedAt)}ms`);
             }
             throw err;
         }