@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/dist/components/OptionsWatcher.js

@@ -1,19 +1,19 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OptionsWatcher = exports.CannotSetPropertyError = exports.KeyDoesNotExistError = exports.InvalidValueTypeError = exports.InvariantUninitializedOptionsWatcherError = exports.UninitializedOptionsWatcherError = exports.OptionsWatcherConfigFileError = void 0;
 const harper_logger_ts_1 = require("../utility/logging/harper_logger.js");
 const events_1 = require("events");
-const yaml_1 = __importDefault(require("yaml"));
-const chokidar_1 = __importDefault(require("chokidar"));
 const promises_1 = require("node:fs/promises");
 const util_1 = require("util");
 const DEFAULT_CONFIG_ts_1 = require("./DEFAULT_CONFIG.js");
 const lodash_1 = require("lodash");
 const watcherFallback_ts_1 = require("../utility/watcherFallback.js");
+const watchPath_ts_1 = require("../utility/watchPath.js");
 const harperConfigEnvVars_ts_1 = require("../config/harperConfigEnvVars.js");
+const readConfigFileSync_ts_1 = require("../config/readConfigFileSync.js");
+const parseConfigFile_ts_1 = require("../config/parseConfigFile.js");
+const configReadRetry_ts_1 = require("../config/configReadRetry.js");
+const watcherArming_ts_1 = require("../config/watcherArming.js");
 // This is uniquely for errors coming from the chokidar watcher of the config file.
 class OptionsWatcherConfigFileError extends Error {
     constructor(configFilePath, error) {
@@ -68,35 +68,49 @@ exports.CannotSetPropertyError = CannotSetPropertyError;
  */
 class OptionsWatcher extends events_1.EventEmitter {
     #filePath;
+    #watchPath;
     #watcher;
     #scopedConfig;
     #rootConfig;
     #isRootConfig;
+    #synchronousRead;
+    #readRetry = new configReadRetry_ts_1.ConfigReadRetry();
+    #armGate = new watcherArming_ts_1.ArmGate();
     #name;
     #logger;
     #usingPolling;
     #closed;
     #openCount = 0;
+    #readCount = 0;
+    #readSequence = 0;
+    #appliedSequence = 0;
+    #scopeConfigured = false;
+    #armAbsence;
+    #readyEmitted = false;
+    #envComposeError;
     #pendingReads = new Set();
     ready;
     constructor(name, filePath, logger, isRootConfig) {
         super();
         this.#name = name;
         this.#filePath = filePath;
+        const watchTarget = (0, watchPath_ts_1.resolveWatchTarget)(filePath);
+        this.#watchPath = watchTarget.path;
         // Root-config watchers must see runtime env config (HARPER_SET_CONFIG et al.)
         // even when it hasn't been flushed to disk yet — see #handleChange (#1618).
         // Application scopes watch their own config.yaml and are never overlaid.
-        this.#isRootConfig = isRootConfig ?? (0, harperConfigEnvVars_ts_1.isRootConfigFilename)(filePath);
+        const rootConfigFile = (0, harperConfigEnvVars_ts_1.isRootConfigFilename)(filePath);
+        this.#isRootConfig = isRootConfig ?? rootConfigFile;
+        this.#synchronousRead = this.#isRootConfig;
         this.#logger = logger || (0, harper_logger_ts_1.loggerWithTag)(name);
-        this.#usingPolling = false;
+        this.#usingPolling = watchTarget.mustPoll;
         this.#closed = false;
         this.ready = (0, events_1.once)(this, 'ready');
         this.#openWatcher();
     }
     #openWatcher() {
-        this.#openCount++;
-        this.#watcher = chokidar_1.default
-            .watch(this.#filePath, {
+        const generation = ++this.#openCount;
+        this.#watcher = (0, watcherFallback_ts_1.guardedWatch)(this.#watchPath, {
             persistent: false,
             ...(this.#usingPolling ? watcherFallback_ts_1.POLLING_FALLBACK_OPTIONS : {}),
         })
@@ -104,79 +118,292 @@ class OptionsWatcher extends events_1.EventEmitter {
             .on('change', this.#handleChange.bind(this))
             .on('error', this.#handleError.bind(this))
             .on('unlink', this.#handleUnlink.bind(this))
-            .on('ready', this.#handleChange.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));
+    }
+    // Every root-declared plugin gets its own root-config watcher and each reads synchronously, so
+    // each has the unarmed window DESIGN.md's "`ready` means the watcher is armed" describes. The
+    // write that lands in it is reported by no event, so only this re-read can deliver it.
+    #handleArmed(generation) {
+        if (this.#closed || generation !== this.#openCount)
+            return;
+        this.#armGate.arm(() => this.#read(true, true));
     }
     #handleChange() {
-        const read = (0, promises_1.readFile)(this.#filePath, 'utf-8')
-            .then((contents) => {
-            let parsed = yaml_1.default.parse(contents);
-            // The on-disk root config is not guaranteed to include runtime env config at
-            // boot: the file flush races component loading, so a scope's boot-time reads
-            // (e.g. an `enabled` gate in handleApplication) could observe pre-env values
-            // the componentLoader itself never saw. Ask the config layer to overlay env
-            // config onto EVERY root-config read so scope.options matches the resolved
-            // view (#1618). Non-root scopes and the no-env-vars case are untouched
-            // (overlayRootEnvConfig is a no-op there).
-            if (this.#isRootConfig)
-                parsed = (0, harperConfigEnvVars_ts_1.overlayRootEnvConfig)(parsed);
-            this.#rootConfig = parsed && typeof parsed === 'object' ? parsed : undefined;
-            // If the extension is in the config file
-            if (this.#rootConfig && this.#name in this.#rootConfig) {
-                // If a config object does not exist
-                if (!this.#scopedConfig) {
-                    // set it
-                    this.#scopedConfig = this.#rootConfig[this.#name];
-                    // and emit a ready event
-                    this.emit('ready', this.#scopedConfig);
+        this.#read(true);
+    }
+    // While `ready` is outstanding the ladder is the only thing that can settle it, so its timer has
+    // to keep the thread alive; afterwards it must not, or a config file nobody is reading would
+    // hold a worker open.
+    #schedule() {
+        return this.#readRetry.schedule(() => this.#read(false), !this.#readyEmitted);
+    }
+    #read(waitForLock, arming = false) {
+        // A queued chokidar callback can still land after close(), and by then removeAllListeners()
+        // has run — emitting into an EventEmitter with no 'error' listener would throw out of it.
+        if (this.#closed)
+            return;
+        this.#readCount++;
+        if (this.#synchronousRead) {
+            try {
+                let contents;
+                try {
+                    contents = (0, readConfigFileSync_ts_1.readConfigFileSync)(this.#filePath, waitForLock);
                 }
-                else {
-                    // Otherwise, merge the new config with the old config
-                    this.#merge(this.#rootConfig[this.#name], this.#scopedConfig);
+                catch (error) {
+                    this.#handleReadError(error, arming);
+                    return;
                 }
+                this.#applyContents(contents);
             }
-            else {
-                // Otherwise, if the extension is not in the config file
-                // This means the plugin was removed from the config file
-                if (this.#scopedConfig) {
-                    // and a config exists, remove it
-                    this.#scopedConfig = undefined;
-                    this.emit('remove');
-                }
-                // Otherwise do nothing - the user may add the config back in later
+            catch (error) {
+                // A listener of what `#applyContents` emitted may have closed the watcher, after
+                // which `emit('error')` has no listener left and would throw out of here.
+                if (!this.#closed)
+                    this.#surfaceFailure(error);
             }
+            return;
+        }
+        // The `#closed` check above cannot cover the completion: close() may land while this read is
+        // in flight, and by then its retry state is cancelled and its listeners are gone. Nothing
+        // orders these against each other either — chokidar does not await one read before starting
+        // the next — so an older one completing last would put the file's previous contents back
+        // with no event left to correct it.
+        const sequence = ++this.#readSequence;
+        // `<=`, not `<`: a deletion supersedes the reads already in flight without being a read of
+        // its own, and says so by claiming the sequence they were issued under.
+        const outranked = () => this.#closed || sequence <= this.#appliedSequence;
+        const read = (0, promises_1.readFile)(this.#filePath, 'utf-8')
+            .then((contents) => {
+            if (outranked())
+                return;
+            this.#appliedSequence = sequence;
+            this.#applyContents(contents);
+        }, (error) => {
+            if (outranked())
+                return;
+            this.#appliedSequence = sequence;
+            this.#handleReadError(error, arming);
         })
             .catch((error) => {
-            // If the config file does not exist
-            if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
-                // A readFile ENOENT here is the install window (file not written yet) or a
-                // transient read race — NOT a real deletion, which chokidar routes to
-                // `#handleUnlink`. Env config is file-independent, so when it provides this
-                // scope the missing file must not discard it (#1618). When it does not, fall
-                // through to the original ENOENT handling with #rootConfig untouched, so a
-                // first boot still emits `ready` (not `remove`, which nothing consumes at
-                // boot → `ready` would hang forever).
-                if (this.#applyEnvOnlyConfig())
-                    return;
-                // And a config already exists, reset it to the default
-                if (this.#rootConfig) {
-                    this.#resetConfig();
-                    this.emit('remove');
-                }
-                else {
-                    // Otherwise, if no config exists, then just set to default and emit ready
-                    this.#resetConfig();
-                    this.emit('ready');
-                }
-                return;
-            }
-            this.emit('error', error);
+            if (!this.#closed)
+                this.#surfaceFailure(error);
         })
             .finally(() => {
             this.#pendingReads.delete(read);
         });
         this.#pendingReads.add(read);
     }
+    #applyContents(contents) {
+        // An empty read is a writer's truncate window, not an emptied config, and falling through
+        // would emit `remove` — see DESIGN.md, "An empty read is a writer mid-write, not an empty
+        // config". Both read paths can land in that window; only the synchronous one is likely to.
+        if (!contents) {
+            if (this.#schedule())
+                return;
+            // Past the ladder the file is empty rather than mid-write, and an empty file carries no
+            // scope: keep what is already applied instead of reading it as a removal, and settle the
+            // boot barrier on the defaults rather than leaving `Scope.ready` pending forever.
+            this.#logger.warn?.(`Configuration file ${this.#filePath} is empty.`);
+            this.#settleUnconfigured();
+            return;
+        }
+        let parsed;
+        try {
+            parsed = (0, parseConfigFile_ts_1.parseConfigFile)(contents, this.#filePath);
+        }
+        catch (error) {
+            // A prefix of the document is as much a mid-write read as an empty one, and the event
+            // carrying the rest is the one chokidar throttles away — same ladder, same reason. Past it
+            // the file really is malformed, which `#read` routes to `#surfaceFailure`.
+            if (!this.#closed && this.#schedule())
+                return;
+            throw error;
+        }
+        // Judged on the file's own parse, before the overlay below: a truncated document, a lone
+        // `\n` and a file of nothing but comments all parse to `null` rather than throwing, and
+        // `overlayRootEnvConfig` turns any of them into a non-null object whenever a config env var
+        // is set — the norm in containers — so overlaying first would launder a half-written file
+        // into a valid-looking env-only config and wipe the file's own options. Past the ladder it
+        // is an empty file, which `#applyContents` already keeps rather than reads as a removal.
+        if (!parsed || typeof parsed !== 'object') {
+            if (this.#schedule())
+                return;
+            this.#logger.warn?.(`Configuration file ${this.#filePath} is empty.`);
+            this.#settleUnconfigured();
+            return;
+        }
+        this.#readRetry.reset();
+        // The on-disk root config is not guaranteed to include runtime env config at
+        // boot: the file flush races component loading, so a scope's boot-time reads
+        // (e.g. an `enabled` gate in handleApplication) could observe pre-env values
+        // the componentLoader itself never saw. Ask the config layer to overlay env
+        // config onto EVERY root-config read so scope.options matches the resolved
+        // view (#1618). Non-root scopes and the no-env-vars case are untouched
+        // (overlayRootEnvConfig is a no-op there).
+        if (this.#isRootConfig) {
+            try {
+                parsed = (0, harperConfigEnvVars_ts_1.overlayRootEnvConfig)(parsed);
+            }
+            catch (error) {
+                this.#envComposeError = error;
+                if (this.#readyEmitted)
+                    this.#reportEnvComposeFailure();
+                else
+                    this.#settleUnconfigured();
+                return;
+            }
+        }
+        this.#rootConfig = parsed && typeof parsed === 'object' ? parsed : undefined;
+        // If the extension is in the config file
+        if (this.#rootConfig && this.#name in this.#rootConfig) {
+            this.#applyScopedConfig(this.#rootConfig[this.#name]);
+        }
+        else {
+            // Otherwise, if the extension is not in the config file
+            // This means the plugin was removed from the config file
+            // Presence, not truthiness: `myPlugin:` with nothing under it is a configured scope, and
+            // deleting that block has to reach `Scope` as a removal like any other.
+            if (this.#scopeConfigured) {
+                this.#scopeConfigured = false;
+                this.#scopedConfig = undefined;
+                this.#emitRemove();
+            }
+            // The scope may be added back later, but this read is still a terminal outcome: with
+            // nothing ever applied, neither branch above emits, and `Scope.ready` would stay pending
+            // for a config that read perfectly well. The read succeeded, so only the scope falls back
+            // to its default — `#settleUnconfigured`'s full reset would discard the root config this
+            // very read produced.
+            if (!this.#readyEmitted) {
+                this.#scopedConfig = (0, lodash_1.cloneDeep)(DEFAULT_CONFIG_ts_1.DEFAULT_CONFIG[this.#name]);
+                this.#emitReady(this.#scopedConfig);
+            }
+        }
+    }
+    #handleReadError(error, arming = false) {
+        // If the config file does not exist
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            // A readFile ENOENT here is the install window (file not written yet) or a
+            // transient read race — NOT a real deletion, which chokidar routes to
+            // `#handleUnlink`. Env config is file-independent, so when it provides this
+            // scope the missing file must not discard it (#1618). When it does not, fall
+            // through to the original ENOENT handling with #rootConfig untouched, so a
+            // first boot still emits `ready` (not `remove`, which nothing consumes at
+            // boot → `ready` would hang forever).
+            // A ladder armed by an earlier empty read is spent here, and every other terminal path
+            // clears its deadline; leaving it armed costs the next mid-write read its whole budget.
+            this.#readRetry.reset();
+            if (this.#applyEnvOnlyConfig())
+                return;
+            // And a config already exists, reset it to the default
+            if (this.#rootConfig) {
+                // The arm gate's job is the *write* that landed while the watch was unarmed, and
+                // answering its ENOENT with a removal reports the deletion ahead of the `unlink`
+                // that would confirm it — on a platform with an arming grace, ahead of chokidar
+                // having finished its own teardown, so a config recreated on the strength of that
+                // early `remove` lands where its `add` is not observed at all. It cannot simply be
+                // dropped either: the unarmed window is exactly where an `unlink` can go missing.
+                // So it goes back to the loop once, and chokidar's own `unlink` cancels it.
+                if (arming) {
+                    // Every resolution of the deferral recomposes and reports the env state it finds,
+                    // so a failure held across it is one that may no longer be true — and the next
+                    // path to report would attach it to an unrelated event.
+                    this.#envComposeError = undefined;
+                    this.#deferAbsenceCheck();
+                    return;
+                }
+                this.#resetConfig();
+                this.#emitRemove();
+            }
+            else {
+                // Otherwise, if no config exists, then just set to default and emit ready
+                this.#resetConfig();
+                this.#emitReady();
+            }
+            this.#reportEnvComposeFailure();
+            return;
+        }
+        // A failure that outlives the read emits no new watcher event when it clears, so without
+        // this the scope would hold a stale config until the next write. Both read paths: an
+        // application config on SMB or under an editor's replacement returns a transient
+        // EBUSY/EIO just the same, and only the read for it blocks — the ladder never does.
+        if (!this.#closed && this.#schedule())
+            return;
+        this.#surfaceFailure(error);
+    }
+    // A failure before anything has been applied is the boot window, where `error` alone strands the
+    // component: `Scope` logs it and componentLoader waits on `Scope.ready` with no timeout. Fall
+    // back to the defaults exactly as the ENOENT branch above does — and emit `ready` first, since
+    // `error` settles the `once(..., 'ready')` promises both of them await.
+    #surfaceFailure(error) {
+        this.#settleUnconfigured();
+        this.#emitError(error);
+    }
+    // Settling the barrier removes the `error` listener `once(this, 'ready')` attached, and an emit
+    // with none left throws the error back at the caller — here, chokidar's dispatch or a retry
+    // timer, where nothing can absorb it. A consumer that throws is no different.
+    #emitError(error) {
+        if (this.listenerCount('error') === 0) {
+            this.#logger.error?.(`The configuration for '${this.#name}' at ${this.#filePath} could not be read`, error);
+            return;
+        }
+        try {
+            this.emit('error', error);
+        }
+        catch (listenerError) {
+            this.#logger.error?.('A configuration error listener failed', listenerError);
+        }
+    }
+    #emitRemove() {
+        try {
+            this.emit('remove');
+        }
+        catch (error) {
+            this.#logger.error?.('A configuration removal listener failed', error);
+        }
+    }
+    // `#readyEmitted`, not the config's truthiness: a scope absent from a config that read fine
+    // leaves `#rootConfig` set with no `ready` behind it, and a later failure would return here
+    // with `Scope.ready` still pending.
+    #settleUnconfigured() {
+        if (this.#readyEmitted)
+            return;
+        // A file the watcher cannot use does not unset env config, exactly as on the ENOENT path
+        // (#1618) — but the barrier still has to settle, including when composing that env config is
+        // itself what failed.
+        if (this.#applyEnvOnlyConfig()) {
+            if (!this.#readyEmitted)
+                this.#emitReady(this.#scopedConfig);
+        }
+        else {
+            this.#resetConfig();
+            this.#emitReady(this.#scopedConfig);
+        }
+        // Also on the env-only branch: the caller may be `#handleChange`'s merge-shape failure,
+        // whose error composing `undefined` never reproduces.
+        this.#reportEnvComposeFailure();
+    }
+    #emitReady(...args) {
+        this.#readyEmitted = true;
+        try {
+            this.emit('ready', ...args);
+        }
+        catch (error) {
+            // The failure paths emit `ready` from a ladder timer and from chokidar's error dispatch,
+            // where a throwing listener is an uncaught exception that takes the worker down.
+            this.#logger.error?.('A configuration listener failed', error);
+        }
+    }
     #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))
+            return;
         if ((0, watcherFallback_ts_1.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
@@ -184,25 +411,51 @@ class OptionsWatcher extends events_1.EventEmitter {
             if (!this.#usingPolling) {
                 (0, watcherFallback_ts_1.warnWatcherFallback)(this.#filePath);
                 this.#usingPolling = true;
-                // Close the failed native watcher and reopen with polling. Guard
-                // against reopen-after-close: the caller may have invoked close()
-                // while this teardown was in flight. The .catch is required because
-                // `finally` would re-raise a teardown rejection as an unhandled one.
-                this.#watcher
-                    .close()
+                // 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) => this.#logger.error?.(`Could not reopen the ${this.#filePath} watch on polling:`, 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 no read will ever run: settle the barrier rather than
+                // leave `Scope.ready` pending forever.
+                this.#settleUnconfigured();
             }
             return;
         }
-        this.emit('error', new OptionsWatcherConfigFileError(this.#filePath, error));
+        // Terminal for this scope: `componentLoader` awaits `Scope.ready` with no timeout, and an
+        // `error` emitted while it is pending rejects that barrier instead of settling it — the
+        // asymmetry with `RootConfigWatcher.handleError` the boot-barrier contract cannot afford.
+        const watcherError = new OptionsWatcherConfigFileError(this.#filePath, error);
+        this.#settleUnconfigured();
+        this.#emitError(watcherError);
     }
     #handleUnlink(path) {
+        // The deletion settles what a pending read was retrying, and a rung landing after this
+        // would find ENOENT and emit a second `remove` at consumers that treat it as teardown.
+        // Same for the arming re-read's deferred absence check: this is the event it was waiting on.
+        // Cancelling the ladder covers the rung not yet armed; a rung already in flight on the
+        // asynchronous path is outranked instead, or its ENOENT would report the same deletion again
+        // — after the settle below, as a `remove` that asks `Scope` to restart a scope that just
+        // booted on the defaults.
+        this.#readRetry.reset();
+        this.#appliedSequence = this.#readSequence;
+        if (this.#armAbsence)
+            clearImmediate(this.#armAbsence);
+        this.#armAbsence = undefined;
         // A real deletion still leaves env-var config in force: an env-defined scope must
         // survive it exactly as on the ENOENT read path — same fallback, same error routing
         // (#1618, #1726 review).
@@ -212,16 +465,24 @@ class OptionsWatcher extends events_1.EventEmitter {
         }
         this.#logger.warn?.(`Configuration file ${path} was deleted. Reverting to default configuration. Recreate it to restore the options watcher.`);
         this.#resetConfig();
-        this.emit('remove');
+        // Before the first `ready` there is nothing to remove and nothing to hear it: `Scope.ready`
+        // is still pending, so a `remove` here asks for a restart of a scope that never booted while
+        // the `#readRetry.reset()` above cancelled the only thing left to settle the barrier. Same
+        // ruling as the ENOENT read path, which already boots on the defaults rather than reporting
+        // a removal `ready` would then wait behind forever.
+        if (this.#readyEmitted)
+            this.#emitRemove();
+        else
+            this.#emitReady(this.#scopedConfig);
+        this.#reportEnvComposeFailure();
     }
     /**
      * Shared fallback for the ENOENT read path and `#handleUnlink`: when config env vars
-     * define this scope, apply the env-only overlay (first application → `ready`; already
-     * configured → `merge`, never reset). Returns true when the event was handled —
-     * including the malformed-env case, which routes to `error` like the file-read path
-     * rather than an unhandled rejection. Returns false (root config untouched) when this
-     * is not a root config or the env config does not provide the scope, so callers keep
-     * their own reset semantics.
+     * define this scope, apply the env-only overlay (first source application → `ready`;
+     * already configured → `merge`, never reset). Returns false — root config untouched, so
+     * callers keep their own reset semantics — when this is not a root config, when the env
+     * config does not provide the scope, and when composing it threw, which is held for
+     * `#reportEnvComposeFailure` rather than emitted here.
      */
     #applyEnvOnlyConfig() {
         if (!this.#isRootConfig)
@@ -231,25 +492,71 @@ class OptionsWatcher extends events_1.EventEmitter {
             composed = (0, harperConfigEnvVars_ts_1.overlayRootEnvConfig)(undefined);
         }
         catch (composeError) {
-            this.emit('error', composeError);
-            return true;
+            // Env config that cannot be composed is not env config: `false` puts every caller on the
+            // path it already takes when there is none, so the barrier still settles on the defaults
+            // and a deletion still emits `remove`. The failure is held for `#reportEnvComposeFailure`,
+            // which callers run *after* settling — an `error` emitted first settles
+            // `once(this, 'ready')` by rejection instead.
+            this.#envComposeError = composeError;
+            return false;
         }
         if (!composed || !(this.#name in composed))
             return false;
         this.#rootConfig = composed;
-        if (!this.#scopedConfig) {
-            this.#scopedConfig = composed[this.#name];
-            this.emit('ready', this.#scopedConfig);
+        this.#applyScopedConfig(composed[this.#name]);
+        return true;
+    }
+    #reportEnvComposeFailure() {
+        if (this.#envComposeError === undefined)
+            return;
+        const error = this.#envComposeError;
+        this.#envComposeError = undefined;
+        this.#emitError(error);
+    }
+    // A scope with no source config takes `ready`, one with a prior source value takes the granular `change`
+    // events `#merge` derives. `ready` is emitted more than once: a scope can go back to having no
+    // config of its own — see `Scope.#handleOptionsWatcherReady` for what a repeat means there.
+    #applyScopedConfig(next) {
+        if (!this.#scopeConfigured) {
+            this.#scopeConfigured = true;
+            this.#scopedConfig = next;
+            this.#emitReady(this.#scopedConfig);
+            return;
         }
-        else {
-            this.#merge(composed[this.#name], this.#scopedConfig);
+        if (this.#scopedConfig) {
+            return this.#merge(next, this.#scopedConfig);
         }
-        return true;
+        // A falsy scope value is still a configured scope — `myPlugin:` with nothing under it is
+        // the idiomatic "enable with defaults" — and `#merge` cannot diff from one, because
+        // `#setValue` needs a value to walk. Re-reading it is not a transition (every ladder rung
+        // and rename-burst re-read would otherwise look like one), but *filling it in* is a change
+        // like any other, not the unconfigured → configured `ready` that `Scope` answers with a
+        // restart.
+        if ((0, util_1.isDeepStrictEqual)(next, this.#scopedConfig))
+            return;
+        this.#scopedConfig = next;
+        this.#emitChange([], next);
     }
+    // Cloned, never aliased: `#merge` writes into `#scopedConfig` in place, so a scope that starts
+    // on the defaults and is then configured would otherwise write the app's values into the
+    // module-level `DEFAULT_CONFIG` every later reset hands out. And not configured: the six scopes
+    // `DEFAULT_CONFIG` names would otherwise have the next read of an unchanged file look like the
+    // block being deleted.
     #resetConfig() {
-        this.#rootConfig = DEFAULT_CONFIG_ts_1.DEFAULT_CONFIG;
+        this.#scopeConfigured = false;
+        this.#rootConfig = (0, lodash_1.cloneDeep)(DEFAULT_CONFIG_ts_1.DEFAULT_CONFIG);
         this.#scopedConfig = this.#rootConfig[this.#name];
     }
+    #deferAbsenceCheck() {
+        if (this.#armAbsence)
+            return;
+        this.#armAbsence = setImmediate(() => {
+            this.#armAbsence = undefined;
+            if (!this.#closed)
+                this.#read(true);
+        });
+        this.#armAbsence.unref?.();
+    }
     /**
      * This merge algorithm is best thought off as a diff and overwrite.
      * The new config object will completely overwrite the old config object,
@@ -331,7 +638,7 @@ class OptionsWatcher extends events_1.EventEmitter {
         }
         if (keys.length === 0) {
             this.#scopedConfig = value;
-            this.emit('change', keys, value, this.#scopedConfig);
+            this.#emitChange(keys, value);
             return;
         }
         let obj = this.#scopedConfig;
@@ -345,7 +652,19 @@ class OptionsWatcher extends events_1.EventEmitter {
             throw new CannotSetPropertyError(keys);
         }
         obj[keys[keys.length - 1]] = value;
-        this.emit('change', keys, value, this.#scopedConfig);
+        this.#emitChange(keys, value);
+    }
+    // `#merge` runs inside chokidar's own dispatch on the unlink and env-fallback paths, where a
+    // plugin's `change` handler throwing would leave the worker with an uncaught exception on a
+    // config event the watcher had just decided to survive. It still reaches consumers as `error`
+    // — a listener fault is not a read fault, which is why it must not reach `#handleReadError`.
+    #emitChange(keys, value) {
+        try {
+            this.emit('change', keys, value, this.#scopedConfig);
+        }
+        catch (error) {
+            this.#emitError(error);
+        }
     }
     // Test-only: simulate the underlying chokidar watcher emitting an error.
     // Exposed so the polling-fallback path can be exercised without triggering a
@@ -353,23 +672,45 @@ class OptionsWatcher extends events_1.EventEmitter {
     _simulateWatcherErrorForTests(error) {
         this.#handleError(error);
     }
-    // Test-only: whether the watcher has fallen back to polling.
+    // Test-only: a real unlink cannot be ordered against a read already in flight — see DESIGN.md,
+    // "Root config watchers must read synchronously".
+    _simulateUnlinkForTests(path) {
+        this.#handleUnlink(path);
+    }
     get _usingPollingForTests() {
         return this.#usingPolling;
     }
-    // Test-only: number of times the underlying watcher has been (re)opened.
-    // Used to assert that a close()-during-fallback race didn't install a
-    // replacement watcher.
+    // Used to assert that a close()-during-fallback race didn't install a replacement watcher.
     get _openCountForTests() {
         return this.#openCount;
     }
+    // Distinguishes a ladder rung from a watcher event.
+    get _readCountForTests() {
+        return this.#readCount;
+    }
+    get _armedForTests() {
+        return this.#armGate.armed;
+    }
+    // Test-only: read now, rather than at whatever granularity a chokidar event would arrive.
+    _refreshForTests(arming = false) {
+        this.#read(true, arming);
+        return Promise.allSettled([...this.#pendingReads]);
+    }
     /**
      * Closes the underlying file watcher and drains any pending config-file reads.
      * Emits `close` synchronously, removes all listeners, then returns a Promise that
      * resolves once the chokidar watcher has fully stopped and all in-flight reads settle.
      */
     close() {
+        // Terminal like every other outcome, and `Scope.ready` has no timeout. Before `#closed` and
+        // through `#emitReady`, so a listener that throws cannot skip the teardown below it.
+        this.#settleUnconfigured();
         this.#closed = true;
+        this.#readRetry.cancel();
+        this.#armGate.cancel();
+        if (this.#armAbsence)
+            clearImmediate(this.#armAbsence);
+        this.#armAbsence = undefined;
         const pendingReads = [...this.#pendingReads];
         const watcherClose = Promise.resolve(this.#watcher.close()).catch(() => { });
         this.emit('close');