imapflow 1.6.6 → 1.7.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.6.6"
+    ".": "1.7.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [1.7.0](https://github.com/postalsys/imapflow/compare/v1.6.6...v1.7.0) (2026-08-11)
+
+
+### Features
+
+* **idle:** make the auto-IDLE delay configurable ([311fe0c](https://github.com/postalsys/imapflow/commit/311fe0ccb0d75d4ddbe797bf5bc755df5bf0485f))
+
+
+### Bug Fixes
+
+* **idle:** align the socket watchdog with the auto-IDLE busy guard ([d5e7191](https://github.com/postalsys/imapflow/commit/d5e71915ac7a1829b7e1340da6195a5e3e9984b2))
+* **idle:** validate autoIdleDelay and keep auto-IDLE off a busy connection ([aeafdf6](https://github.com/postalsys/imapflow/commit/aeafdf62fab3b29cd488d9b8cbdffc8896107d6e))
+
 ## [1.6.6](https://github.com/postalsys/imapflow/compare/v1.6.5...v1.6.6) (2026-08-07)
 
 

package/lib/commands/idle.js

@@ -257,14 +257,16 @@ async function runPollingFallback(connection, maxIdleTime) {
 
                 pollOnce(connection, session)
                     .then(() => {
+                        // Stamped only after a poll actually completed: a failed poll must not
+                        // satisfy the resumed schedule below, or the next session would defer
+                        // its first poll a full interval past an attempt that checked nothing.
+                        connection._lastPollAt = Date.now();
                         // Cancellation is re-checked here: the session may have been broken while
                         // this poll was in flight, and an orphaned poller must not schedule again.
                         if (session.cancelled) {
                             return;
                         }
-                        session.timer = setTimeout(runPoll, interval);
-                        // Background polling must not keep the process alive
-                        unrefTimer(session.timer);
+                        scheduleNextPoll(interval);
                     })
                     .catch(err => {
                         connection.log.warn({ err, cid: connection.id });
@@ -272,9 +274,28 @@ async function runPollingFallback(connection, maxIdleTime) {
                     });
             };
 
+            function scheduleNextPoll(delay) {
+                session.timer = setTimeout(runPoll, delay);
+                // Background polling must not keep the process alive
+                unrefTimer(session.timer);
+            }
+
             connection.log.debug({ src: 'c', msg: `initiated NOOP loop`, cid: connection.id });
-            // Keep the immediate first poll
-            runPoll();
+
+            // Every auto-IDLE restart begins a fresh polling session, so an unconditional first
+            // poll would tie the poll rate to how often the caller runs commands rather than to
+            // `interval`: with a short autoIdleDelay, a command every few seconds turns into a
+            // poll every few seconds. The last poll timestamp lives on the connection, so a new
+            // session resumes the previous one's schedule instead of restarting it.
+            // Clamped at zero because a backward wall-clock step (NTP, VM resume) leaves the
+            // stamp in the future; however large the jump, the next poll must never be more
+            // than one full interval away.
+            let sinceLastPoll = Math.max(0, Date.now() - (connection._lastPollAt || 0));
+            if (sinceLastPoll >= interval) {
+                runPoll();
+            } else {
+                scheduleNextPoll(interval - sinceLastPoll);
+            }
         });
     } finally {
         session.cancelled = true;

package/lib/imap-flow.d.ts

@@ -30,6 +30,17 @@ export interface ImapFlowOptions {
     clientInfo?: IdInfoObject;
     /** If true, then do not start IDLE when connection is established */
     disableAutoIdle?: boolean;
+    /**
+     * How long (in ms) the connection has to be inactive before IDLE is started automatically.
+     * Keep it above the pause your own code usually leaves between two commands, otherwise every
+     * command is followed by an IDLE that the next command has to break, costing two extra
+     * round-trips per command. To turn auto-IDLE off use `disableAutoIdle` rather than a very
+     * large delay: the value is capped below `socketTimeout`, because auto-IDLE has to start
+     * before the inactivity watchdog fires. On servers without IDLE support this controls when
+     * the polling fallback starts, not how often it polls - the poll interval is `maxIdleTime`,
+     * capped at 2 minutes. Default: 15000 ms.
+     */
+    autoIdleDelay?: number;
     /** Additional TLS options (see Node.js TLS documentation) */
     tls?: ConnectionOptions;
     /** Custom logger instance. Set to false to disable logging */

package/lib/imap-flow.js

@@ -64,6 +64,19 @@ const MAX_THROTTLE_DELAY = 5 * 60 * 1000;
 // ImapFlow constructor option `maxLockHoldTime`. Set to 0 or false to disable.
 const HELD_LOCK_WARN_MS = 30 * 60 * 1000;
 
+// How long the connection has to stay inactive before auto-IDLE starts. Long enough that a caller
+// running a sequence of commands is not interrupted by an IDLE it immediately has to break.
+// Configurable via the ImapFlow constructor option `autoIdleDelay`.
+const AUTO_IDLE_DELAY = 15 * 1000;
+
+// Headroom kept between the auto-IDLE delay and the socket inactivity watchdog, so IDLE reaches
+// the wire before the watchdog can fire. See normalizeAutoIdleDelay().
+const AUTO_IDLE_SOCKET_MARGIN = 1000;
+
+// The largest delay setTimeout can honor (2^31 - 1 ms). Anything above fires after 1 ms instead,
+// so the auto-IDLE delay cap has to stay inside this range even when socketTimeout is not.
+const MAX_TIMER_DELAY = 2 ** 31 - 1;
+
 const states = {
     NOT_AUTHENTICATED: 0x01,
     AUTHENTICATED: 0x02,
@@ -71,6 +84,49 @@ const states = {
     LOGOUT: 0x04
 };
 
+/**
+ * Normalizes the configured auto-IDLE delay into a value `setTimeout` can honor. Anything Node
+ * would silently turn into a 1ms timer - NaN, a negative number, a value above the 32-bit range -
+ * falls back to the default instead, because a 1ms delay means an IDLE/DONE round trip around
+ * every single command. The delay is also capped below `socketTimeout`, see AUTO_IDLE_SOCKET_MARGIN.
+ *
+ * @param {*} value - The configured `autoIdleDelay` option.
+ * @param {Number} socketTimeout - The normalized socket inactivity timeout.
+ * @param {Object} log - Logger, used to report a value that could not be used as given.
+ * @param {String} cid - Connection id for the log entry.
+ * @returns {Number} Delay in milliseconds.
+ */
+const normalizeAutoIdleDelay = (value, socketTimeout, log, cid) => {
+    const maxDelay = Math.max(0, Math.min(socketTimeout, MAX_TIMER_DELAY) - AUTO_IDLE_SOCKET_MARGIN);
+    const configured = value !== undefined && value !== null;
+
+    // Numeric strings are accepted, because configuration usually arrives from an environment
+    // variable or a JSON file. Booleans and blank strings are not: Number() would read them as 0,
+    // i.e. "IDLE around every command", the opposite of the "off" they suggest.
+    let delay = typeof value === 'number' || (typeof value === 'string' && value.trim()) ? Number(value) : NaN;
+    let reason = null;
+
+    if (!Number.isFinite(delay) || delay < 0) {
+        reason = 'not a non-negative finite number';
+        delay = AUTO_IDLE_DELAY;
+    }
+
+    if (delay > maxDelay) {
+        // An invalid value keeps its own reason: the cap then applies to the fallback default,
+        // not to anything the caller asked for.
+        reason = reason || `above socketTimeout (${socketTimeout} ms)`;
+        delay = maxDelay;
+    }
+
+    // Only an explicitly configured value is worth warning about. Capping the default because the
+    // caller picked a short socketTimeout is expected behavior, not a misconfiguration.
+    if (configured && reason) {
+        log.warn({ msg: 'Adjusted unusable autoIdleDelay option', requested: value, autoIdleDelay: delay, reason, cid });
+    }
+
+    return Math.floor(delay);
+};
+
 /**
  * @typedef {Object} MailboxObject
  * @global
@@ -188,6 +244,15 @@ class ImapFlow extends EventEmitter {
      * @property {Boolean} [disableAutoIdle=false]
      *     If `true`, do not start IDLE automatically. Useful when only specific operations are needed.
      *
+     * @property {Number} [autoIdleDelay=15000]
+     *     How long (in milliseconds) the connection has to be inactive before IDLE is started automatically.
+     *     Keep it above the pause your own code usually leaves between two commands, otherwise every command is
+     *     followed by an IDLE that the next command has to break, costing two extra round-trips per command.
+     *     To turn auto-IDLE off entirely use `disableAutoIdle` rather than a very large delay: the value is
+     *     capped below `socketTimeout`, because auto-IDLE has to start before the inactivity watchdog fires.
+     *     On servers without IDLE support this controls when the polling fallback starts, not how often it
+     *     polls - the poll interval is `maxIdleTime`, capped at 2 minutes.
+     *
      * @property {Object} [tls]
      *     Additional TLS options. For details, see [Node.js TLS connect](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback).
      *
@@ -438,6 +503,14 @@ class ImapFlow extends EventEmitter {
         this.idRequested = false;
 
         this.maxIdleTime = this.options.maxIdleTime || false;
+        this.autoIdleDelay = normalizeAutoIdleDelay(this.options.autoIdleDelay, this.socketTimeout, this.log, this.id);
+
+        // Wall-clock time of the last fallback poll, owned by lib/commands/idle.js
+        this._lastPollAt = 0;
+
+        // Download streams still fetching chunks. Counted, not a flag, so overlapping downloads
+        // cannot clear each other's suppression of auto-IDLE.
+        this._openDownloads = 0;
         this.missingIdleCommand = (this.options.missingIdleCommand || '').toString().toUpperCase().trim() || 'NOOP';
 
         this.disableBinary = !!this.options.disableBinary;
@@ -1252,10 +1325,22 @@ class ImapFlow extends EventEmitter {
         /**
          * Socket timeout event handler.
          *
-         * When a socket timeout occurs during IDLE, the handler attempts to recover the connection
-         * by sending a NOOP command and then returning to IDLE state.
+         * A quiet socket is only a dead connection when something was supposed to be talking. An
+         * idling session, a download whose consumer stopped draining, and a held mailbox lock
+         * whose owner is busy between commands are all expected to go quiet, so the handler keeps
+         * such a connection alive with a NOOP instead of tearing it down. An in-flight command is
+         * the opposite: its reply is overdue, a recovery NOOP would only queue up behind it and
+         * never reach the wire, so the timeout is reported as an error. The IDLE command itself is
+         * the one exception - it stays in flight for as long as idling lasts, and run() breaks it
+         * through preCheck() before the NOOP is dispatched.
+         *
+         * IDLE is not restarted here: run() re-arms auto-IDLE once the NOOP settles, and
+         * autoidle() knows whether the connection is actually free for IDLE - an open download or
+         * a held lock keeps just the keepalive, and with disableAutoIdle nothing restarts at all.
+         * If the server is dead the NOOP never settles, and the next timeout fires with the NOOP
+         * as the stuck in-flight command, which lands in the error branch below.
          *
-         * @fires ImapFlow#error Emits error event unless the current command is IDLE
+         * @fires ImapFlow#error Emits error event if the connection cannot be recovered
          */
         this._socketTimeout =
             this._socketTimeout ||
@@ -1263,26 +1348,21 @@ class ImapFlow extends EventEmitter {
                 const err = new Error('Socket timeout');
                 err.code = 'ETIMEOUT';
 
-                if (this.idling) {
+                const quietExpected = this.idling || this._openDownloads || this.currentLock;
+                const commandStuck = this.currentRequest && !(this.idling && this.currentRequest.command === 'IDLE');
+
+                if (quietExpected && !commandStuck) {
                     if (!this.usable || !this.socket || this.socket.destroyed) {
                         this.emitError(err);
                         return;
                     }
-                    // Attempt to recover IDLE connections. During true IDLE the NOOP cannot
-                    // reach the server until IDLE has been terminated: run() awaits preCheck(),
-                    // which sends DONE and only resolves once the server has completed the IDLE
-                    // command. Fallback polling has no such handshake - preCheck() there just
-                    // cancels the polling session.
-                    this.run('NOOP')
-                        .then(() => this.idle())
-                        .catch(err => {
-                            this.log.warn({ msg: 'IDLE recovery failed after timeout', err, cid: this.id });
-                            if (!this.isClosed) {
-                                this.close();
-                            }
-                        });
+                    this.run('NOOP').catch(err => {
+                        this.log.warn({ msg: 'Connection recovery failed after timeout', err, cid: this.id });
+                        if (!this.isClosed) {
+                            this.close();
+                        }
+                    });
                 } else {
-                    // Close immediately for non-IDLE operations
                     this.log.debug({ msg: 'Socket timeout', cid: this.id });
                     this.emitError(err);
                 }
@@ -2120,6 +2200,16 @@ class ImapFlow extends EventEmitter {
         return range;
     }
 
+    // The single definition of "the connection is not free". A held or queued mailbox lock, a
+    // command in flight or queued, and an open download stream all mean a caller is
+    // mid-sequence: starting IDLE there injects an IDLE/DONE round trip - or, with
+    // `missingIdleCommand` set to SELECT or STATUS, a mailbox poll - between two of that
+    // caller's own commands. Every one of those states ends by calling autoidle() again, so
+    // declining while busy postpones IDLE, it never cancels it.
+    connectionBusy() {
+        return !!(this.currentLock || this.locks.length || this.currentRequest || this.requestQueue.length || this._openDownloads);
+    }
+
     // Timer process-liveness policy: connection establishment and greeting deadlines keep the
     // process alive, because a caller is waiting on connect() to settle. Background timers
     // (auto-IDLE, IDLE restart, fallback polling, throttle back-off, the held-lock diagnostic) are
@@ -2130,9 +2220,22 @@ class ImapFlow extends EventEmitter {
         if (this.options.disableAutoIdle || this.state !== this.states.SELECTED) {
             return;
         }
+
+        if (this.connectionBusy()) {
+            return;
+        }
+
         this.idleStartTimer = setTimeout(() => {
+            // Re-checked at fire time: paths that take ownership of the connection clear this
+            // timer, but the guard must not depend on every one of them doing so - a single
+            // missed clearTimeout would inject IDLE between a caller's own commands. Declining
+            // postpones rather than cancels: whatever made the connection busy calls autoidle()
+            // again when it finishes.
+            if (this.state !== this.states.SELECTED || this.connectionBusy()) {
+                return;
+            }
             this.idle().catch(err => this.log.warn({ err, cid: this.id }));
-        }, 15 * 1000);
+        }, this.autoIdleDelay);
         unrefTimer(this.idleStartTimer);
     }
 
@@ -3963,6 +4066,23 @@ class ImapFlow extends EventEmitter {
             }
         };
 
+        // A download is a sequence of chunk FETCHes with a backpressure wait in between. Those
+        // gaps look exactly like an inactive connection, so without this auto-IDLE would start
+        // between chunks and the next chunk would have to break it again - two extra round
+        // trips per chunk, for as long as the consumer is slow. Counted before control returns
+        // to the event loop: the head chunk's own FETCH already armed the auto-IDLE timer, and
+        // with a very short autoIdleDelay that timer could otherwise fire before the deferred
+        // chunk loop below has marked the download open.
+        this._openDownloads++;
+        let downloadDone = false;
+        let finishDownload = () => {
+            if (!downloadDone) {
+                downloadDone = true;
+                this._openDownloads--;
+                this.autoidle();
+            }
+        };
+
         // Kick off the download pipeline asynchronously. The first chunk was
         // already fetched above (to get metadata); write it to the decoder
         // stream and then fetch remaining chunks via fetchAllParts().
@@ -3987,6 +4107,7 @@ class ImapFlow extends EventEmitter {
                     /* c8 ignore stop */
                 })
                 .finally(() => {
+                    finishDownload();
                     if (!fetchAborted && stream && !stream.destroyed) {
                         stream.end();
                     }
@@ -3999,6 +4120,7 @@ class ImapFlow extends EventEmitter {
                 writeResult = writeChunk(chunk);
             } catch (err) {
                 stream.emit('error', err);
+                finishDownload();
                 /* c8 ignore next 3 */ // emitting the error above triggers cleanup (fetchAborted=true), so this end() guard is already false here
                 if (!fetchAborted && stream && !stream.destroyed) {
                     stream.end();
@@ -4006,12 +4128,14 @@ class ImapFlow extends EventEmitter {
                 return;
             }
 
-            /* c8 ignore next 7 */ // `stream` is piped to the limiter before this runs, so the head write drains synchronously and always returns true (verified for chunkSize up to 8MB); the drain-wait branch is unreachable
+            /* c8 ignore next 9 */ // `stream` is piped to the limiter before this runs, so the head write drains synchronously and always returns true (verified for chunkSize up to 8MB); the drain-wait branch is unreachable
             if (!writeResult) {
                 // Initial chunk filled the buffer, wait for drain
                 stream.once('drain', () => {
                     if (!fetchAborted) {
                         runFetchAllParts();
+                    } else {
+                        finishDownload();
                     }
                 });
             } else {
@@ -4182,18 +4306,22 @@ class ImapFlow extends EventEmitter {
 
         clearTimeout(this.idleStartTimer);
 
-        if (typeof this.preCheck === 'function') {
-            await this.preCheck();
-        }
-
-        let result = await this.runInternal(command, ...args);
+        try {
+            // The preCheck (breaking an active IDLE) sits inside the try on purpose: the
+            // clearTimeout above is unconditional, so every exit - a failed command or a
+            // preCheck that rejects - must still reach the finally, or auto-IDLE would stay
+            // disarmed on an otherwise healthy connection until some later command succeeded.
+            if (typeof this.preCheck === 'function') {
+                await this.preCheck();
+            }
 
-        if (command !== 'IDLE') {
-            // do not autostart IDLE, if IDLE itself was stopped
-            this.autoidle();
+            return await this.runInternal(command, ...args);
+        } finally {
+            if (command !== 'IDLE') {
+                // do not autostart IDLE, if IDLE itself was stopped
+                this.autoidle();
+            }
         }
-
-        return result;
     }
 
     /**
@@ -4314,6 +4442,10 @@ class ImapFlow extends EventEmitter {
                             idling: this.idling
                         });
                         this.currentLock = false;
+                        // autoidle() will not arm while a lock is held, so the release is what
+                        // restarts it. It re-checks the queue itself, so a lock waiting behind
+                        // this one still keeps IDLE off.
+                        this.autoidle();
                         // Use setImmediate to avoid stack overflow
                         setImmediate(() => {
                             this.processLocks().catch(err => this.log.error({ err, cid: this.id }));
@@ -4335,6 +4467,18 @@ class ImapFlow extends EventEmitter {
                     continue; // Process next lock in queue
                 }
 
+                // Both grant paths finish the same way. autoidle() is re-checked because a stale
+                // auto-IDLE timer may still be armed at this point: on the SELECT path run()
+                // re-arms auto-IDLE when the SELECT settles - a moment before currentLock is set -
+                // and the fast path can inherit a timer from an earlier command. Either way the
+                // timer must not fire inside the lock.
+                const grantLock = () => {
+                    this.currentLock = lock;
+                    armHeldTimer();
+                    this.autoidle();
+                    resolve({ path, release });
+                };
+
                 if (this.mailbox && this.mailbox.path === path && !!this.mailbox.readOnly === !!options.readOnly) {
                     // Fast path: mailbox is already selected with the right access mode
                     this.log.trace({
@@ -4344,9 +4488,7 @@ class ImapFlow extends EventEmitter {
                         idling: this.idling,
                         ...(options.description && { description: options.description })
                     });
-                    this.currentLock = lock;
-                    armHeldTimer();
-                    resolve({ path, release });
+                    grantLock();
                     break; // Stop processing; next lock waits for release()
                 }
 
@@ -4360,9 +4502,7 @@ class ImapFlow extends EventEmitter {
                         idling: this.idling,
                         ...(options.description && { description: options.description })
                     });
-                    this.currentLock = lock;
-                    armHeldTimer();
-                    resolve({ path, release });
+                    grantLock();
                     break; // Wait for this lock to be released
                 } catch (err) {
                     if (err.responseStatus === 'NO') {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.6.6",
+    "version": "1.7.0",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",

package/test/auto-idle-test.js

@@ -0,0 +1,470 @@
+'use strict';
+
+// Auto-IDLE policy: how the `autoIdleDelay` option is normalized, when the timer is allowed to
+// arm at all, and how the socket inactivity watchdog treats connections that are supposed to be
+// quiet.
+//
+// All of it matters more than the option looks. The configured value reaches setTimeout directly,
+// where NaN, a negative number and anything above the 32-bit range all become a 1ms timer, i.e.
+// an IDLE/DONE round trip around every single command. Arming while a caller still owns the
+// connection injects that round trip - or, with `missingIdleCommand` set to SELECT or STATUS, a
+// mailbox poll - between two of that caller's own commands. And the watchdog has to tell a
+// connection that is legitimately quiet (idling, a stalled download, a held lock) from one whose
+// command reply is overdue.
+
+const { makeClient, makeIdleReadyClient, chunkedFetchOne } = require('./fixtures/test-client');
+const { withFakeTimers } = require('./fixtures/fake-timers');
+
+const DEFAULT_DELAY = 15 * 1000;
+const DEFAULT_SOCKET_TIMEOUT = 5 * 60 * 1000;
+const SOCKET_MARGIN = 1000;
+const TIMEOUT_MAX = 2 ** 31 - 1;
+
+// Captures warn entries, so the "silently ignored configuration" cases can be asserted as
+// reported rather than guessed at.
+const makeLoggingClient = (overrides = {}) => {
+    let warnings = [];
+    let client = makeClient({
+        ...overrides,
+        logger: { trace() {}, debug() {}, info() {}, warn: entry => warnings.push(entry), error() {}, fatal() {} }
+    });
+    return { client, warnings };
+};
+
+// ============================================================================
+// option normalization
+// ============================================================================
+
+module.exports['Auto-IDLE: an unset delay uses the default'] = test => {
+    let { client, warnings } = makeLoggingClient();
+    test.equal(client.autoIdleDelay, DEFAULT_DELAY);
+    test.equal(warnings.length, 0, 'the default is not a misconfiguration');
+    test.done();
+};
+
+module.exports['Auto-IDLE: a configured delay is honored and reaches setTimeout'] = async test => {
+    await withFakeTimers(async timers => {
+        let client = makeIdleReadyClient({ autoIdleDelay: 1234 });
+        test.equal(client.autoIdleDelay, 1234);
+
+        client.autoidle();
+
+        let armed = timers.pending();
+        test.equal(armed.length, 1, 'exactly one auto-IDLE timer is armed');
+        test.equal(armed[0].delay, 1234, 'the configured delay is what the timer uses');
+
+        client.close();
+    });
+    test.done();
+};
+
+module.exports['Auto-IDLE: numeric strings are accepted'] = test => {
+    // The normal shape of a value coming from an environment variable or a JSON/YAML config file
+    test.equal(makeClient({ autoIdleDelay: '2000' }).autoIdleDelay, 2000);
+    test.equal(makeClient({ autoIdleDelay: ' 2000 ' }).autoIdleDelay, 2000);
+    test.done();
+};
+
+module.exports['Auto-IDLE: zero is honored, fractions are floored'] = test => {
+    test.equal(makeClient({ autoIdleDelay: 0 }).autoIdleDelay, 0);
+    test.equal(makeClient({ autoIdleDelay: 1500.9 }).autoIdleDelay, 1500);
+    test.done();
+};
+
+module.exports['Auto-IDLE: unusable values fall back to the default and are reported'] = test => {
+    // Every one of these is something setTimeout would turn into a 1ms timer, or something a
+    // caller plausibly means as "off" - which is what disableAutoIdle is for.
+    for (let value of [NaN, -1, -0.5, Infinity, -Infinity, 'soon', '', '   ', true, false, {}, []]) {
+        let { client, warnings } = makeLoggingClient({ autoIdleDelay: value });
+        test.equal(client.autoIdleDelay, DEFAULT_DELAY, `${String(value)} falls back to the default`);
+        test.equal(warnings.length, 1, `${String(value)} is reported rather than silently swallowed`);
+        test.equal(warnings[0].msg, 'Adjusted unusable autoIdleDelay option');
+        test.equal(warnings[0].reason, 'not a non-negative finite number', `${String(value)} is reported with the right reason`);
+    }
+    test.done();
+};
+
+module.exports['Auto-IDLE: the delay is capped below socketTimeout'] = test => {
+    // A delay at or above socketTimeout means the inactivity watchdog fires before IDLE ever
+    // starts. `idling` is still false at that point, so the handler emits ETIMEOUT and tears down
+    // a quiet but perfectly healthy connection instead of letting it enter IDLE.
+    let { client, warnings } = makeLoggingClient({ autoIdleDelay: 10 * 60 * 1000 });
+    test.equal(client.autoIdleDelay, DEFAULT_SOCKET_TIMEOUT - SOCKET_MARGIN);
+    test.equal(warnings.length, 1, 'the caller is told the value was capped');
+
+    // The cap follows a custom socketTimeout, and keeps the delay inside the range setTimeout can
+    // represent: 2 ** 31 and larger would otherwise silently become a 1ms timer.
+    test.equal(makeClient({ autoIdleDelay: 60000, socketTimeout: 30000 }).autoIdleDelay, 29000);
+    test.equal(makeClient({ autoIdleDelay: 2 ** 31 }).autoIdleDelay, DEFAULT_SOCKET_TIMEOUT - SOCKET_MARGIN);
+    test.equal(makeClient({ autoIdleDelay: Number.MAX_SAFE_INTEGER }).autoIdleDelay, DEFAULT_SOCKET_TIMEOUT - SOCKET_MARGIN);
+    test.done();
+};
+
+module.exports['Auto-IDLE: the cap stays inside the timer range for a huge socketTimeout'] = test => {
+    // socket.setTimeout truncates an over-range socketTimeout on its own, so a huge watchdog
+    // deadline still works - but the auto-IDLE delay must not inherit the raw value, or
+    // setTimeout would turn it into a 1ms timer and IDLE would follow every single command.
+    test.equal(makeClient({ socketTimeout: 2 ** 32, autoIdleDelay: 2 ** 31 }).autoIdleDelay, TIMEOUT_MAX - SOCKET_MARGIN);
+    test.equal(makeClient({ socketTimeout: 2200000000, autoIdleDelay: 2150000000 }).autoIdleDelay, TIMEOUT_MAX - SOCKET_MARGIN);
+    test.done();
+};
+
+module.exports['Auto-IDLE: capping the default for a short socketTimeout is silent'] = test => {
+    let { client, warnings } = makeLoggingClient({ socketTimeout: 5000 });
+    test.equal(client.autoIdleDelay, 4000, 'the default is capped too');
+    test.equal(warnings.length, 0, 'but nothing was misconfigured, so nothing is reported');
+    test.done();
+};
+
+module.exports['Auto-IDLE: an invalid value keeps its own reason when the default is then capped'] = test => {
+    // 'soon' falls back to the 15s default, which a 5s socketTimeout then caps to 4s. The
+    // warning must still name what was wrong with the configured value - the cap applied to
+    // the fallback, not to anything the caller asked for.
+    let { client, warnings } = makeLoggingClient({ autoIdleDelay: 'soon', socketTimeout: 5000 });
+    test.equal(client.autoIdleDelay, 4000);
+    test.equal(warnings.length, 1);
+    test.equal(warnings[0].reason, 'not a non-negative finite number');
+    test.done();
+};
+
+// ============================================================================
+// when the timer may arm
+// ============================================================================
+
+module.exports['Auto-IDLE: no timer is armed while a mailbox lock is held'] = async test => {
+    await withFakeTimers(async timers => {
+        let client = makeIdleReadyClient({ autoIdleDelay: 200 });
+
+        let lock = await client.getMailboxLock('INBOX');
+        test.ok(client.currentLock, 'the lock was granted through the fast path');
+
+        client.autoidle();
+        test.equal(timers.count(), 0, 'IDLE must not be injected between a lock holder own commands');
+
+        lock.release();
+        let armed = timers.pending();
+        test.equal(armed.length, 1, 'releasing the lock re-arms auto-IDLE');
+        test.equal(armed[0].delay, 200);
+
+        client.close();
+    });
+    test.done();
+};
+
+module.exports['Auto-IDLE: acquiring a lock through SELECT leaves no timer behind'] = async test => {
+    await withFakeTimers(async timers => {
+        let client = makeIdleReadyClient({ autoIdleDelay: 200 });
+        client.mailbox = false;
+        // The SELECT that opens the mailbox goes through run(), which re-arms auto-IDLE when it
+        // settles - a moment before currentLock is set. That timer would fire inside the lock.
+        client.mailboxOpen = async path => {
+            client.mailbox = { path, readOnly: false };
+            client.autoidle();
+            return client.mailbox;
+        };
+
+        let lock = await client.getMailboxLock('INBOX');
+        test.ok(client.currentLock, 'the lock was granted through the SELECT path');
+        test.equal(timers.count(), 0, 'the timer armed while opening the mailbox was cleared');
+
+        lock.release();
+        test.equal(timers.count(), 1, 'and auto-IDLE resumes once the lock is released');
+
+        client.close();
+    });
+    test.done();
+};
+
+module.exports['Auto-IDLE: releasing a lock with another one queued does not arm'] = async test => {
+    await withFakeTimers(async timers => {
+        let client = makeIdleReadyClient({ autoIdleDelay: 200 });
+
+        let lock = await client.getMailboxLock('INBOX');
+        // Queue a second request; the connection is not free when the first holder lets go
+        let queued = client.getMailboxLock('INBOX');
+        test.equal(client.locks.length, 1, 'the second request is waiting');
+
+        lock.release();
+        test.equal(timers.count(), 0, 'the next holder owns the connection, so IDLE stays off');
+
+        (await queued).release();
+        test.equal(timers.count(), 1, 'the last release re-arms auto-IDLE');
+
+        client.close();
+    });
+    test.done();
+};
+
+module.exports['Auto-IDLE: no timer is armed while a command is in flight or queued'] = async test => {
+    await withFakeTimers(async timers => {
+        let client = makeIdleReadyClient({ autoIdleDelay: 200 });
+
+        // Concurrent commands each clear the timer on entry, so without this guard the first one
+        // to settle would arm a timer that fires while the others are still running.
+        client.currentRequest = { tag: 'A001', command: 'FETCH', sent: true };
+        client.autoidle();
+        test.equal(timers.count(), 0, 'a command in flight owns the connection');
+
+        client.currentRequest = false;
+        client.requestQueue = [{ tag: 'A002', command: 'FETCH' }];
+        client.autoidle();
+        test.equal(timers.count(), 0, 'so does a command still waiting in the queue');
+
+        client.requestQueue = [];
+        client.autoidle();
+        test.equal(timers.count(), 1, 'an idle connection arms the timer');
+
+        client.close();
+    });
+    test.done();
+};
+
+module.exports['Auto-IDLE: the armed timer re-checks the busy guard when it fires'] = async test => {
+    await withFakeTimers(async timers => {
+        let client = makeIdleReadyClient({ autoIdleDelay: 200 });
+        let idleCalls = 0;
+        client.idle = async () => {
+            idleCalls++;
+        };
+
+        client.autoidle();
+        test.equal(timers.count(), 1, 'the timer was armed on a free connection');
+
+        // Ownership taken without clearing the timer - the guard must not depend on every
+        // ownership-taking path remembering its clearTimeout.
+        client.currentRequest = { tag: 'A001', command: 'FETCH', sent: true };
+        await timers.fire();
+        test.equal(idleCalls, 0, 'a connection that is busy at fire time does not start IDLE');
+
+        client.currentRequest = false;
+        client.autoidle();
+        await timers.fire();
+        test.equal(idleCalls, 1, 'a connection that is free at fire time does');
+
+        client.close();
+    });
+    test.done();
+};
+
+module.exports['Auto-IDLE: no timer is armed while a download is streaming'] = async test => {
+    await withFakeTimers(async timers => {
+        let client = makeIdleReadyClient({ autoIdleDelay: 200 });
+        let body = Buffer.from('A'.repeat(20));
+        let armedAfterChunk = [];
+
+        let serveChunk = chunkedFetchOne(body);
+        client.fetchOne = async (range, query) => {
+            // Stands in for run(), which clears the auto-IDLE timer on entry and re-arms it once
+            // the command settles. The pause between two chunks is where IDLE would slip in.
+            clearTimeout(client.idleStartTimer);
+            let part = await serveChunk(range, query);
+            client.autoidle();
+            armedAfterChunk.push(timers.count());
+            return part;
+        };
+
+        let { content } = await client.download('1', false, { chunkSize: 4 });
+        let received = [];
+        for await (let chunk of content) {
+            received.push(chunk);
+        }
+
+        test.equal(Buffer.concat(received).toString(), 'A'.repeat(20), 'the whole body arrived');
+        test.ok(armedAfterChunk.length > 2, 'the body really was fetched in several chunks');
+        test.deepEqual(
+            armedAfterChunk.slice(1).filter(count => count !== 0),
+            [],
+            'no chunk boundary inside the download armed an auto-IDLE timer'
+        );
+        test.equal(timers.count(), 1, 'auto-IDLE resumes once the download stream is finished');
+
+        client.close();
+    });
+    test.done();
+};
+
+module.exports['Auto-IDLE: a download counts as busy before control returns to the event loop'] = async test => {
+    await withFakeTimers(async () => {
+        let client = makeIdleReadyClient({ autoIdleDelay: 200 });
+        let body = Buffer.from('B'.repeat(12));
+        client.fetchOne = chunkedFetchOne(body);
+
+        let { content } = await client.download('1', false, { chunkSize: 4 });
+        // The head chunk's own FETCH re-arms auto-IDLE a moment before the download exists;
+        // with a very short delay that timer fires before the deferred chunk loop starts, so
+        // the busy guard must already see the download when download() hands the stream back.
+        test.equal(client._openDownloads, 1, 'the download is counted before streaming starts');
+
+        let received = [];
+        for await (let chunk of content) {
+            received.push(chunk);
+        }
+        test.equal(Buffer.concat(received).toString(), 'B'.repeat(12), 'the whole body arrived');
+        test.equal(client._openDownloads, 0, 'the download is released once the stream is done');
+
+        client.close();
+    });
+    test.done();
+};
+
+module.exports['Auto-IDLE: a failing command still re-arms the timer'] = async test => {
+    await withFakeTimers(async timers => {
+        let client = makeIdleReadyClient({ autoIdleDelay: 300 });
+        // run() clears the timer before dispatching, so re-arming only on the success path would
+        // leave auto-IDLE off for good after one rejected command.
+        client.runInternal = async () => {
+            throw new Error('command failed');
+        };
+
+        let err;
+        try {
+            await client.run('NOOP');
+        } catch (E) {
+            err = E;
+        }
+
+        test.ok(err, 'the failure still reaches the caller');
+        let armed = timers.pending();
+        test.equal(armed.length, 1, 'auto-IDLE is re-armed after a failed command');
+        test.equal(armed[0].delay, 300);
+
+        client.close();
+    });
+    test.done();
+};
+
+module.exports['Auto-IDLE: a failing IDLE break still re-arms the timer'] = async test => {
+    await withFakeTimers(async timers => {
+        let client = makeIdleReadyClient({ autoIdleDelay: 300 });
+        // run() awaits preCheck() (breaking an active IDLE) before dispatching. A break that
+        // rejects exits run() before the command ever starts, and must still re-arm auto-IDLE
+        // exactly like a failed command does.
+        client.preCheck = async () => {
+            throw new Error('IDLE break failed');
+        };
+
+        let err;
+        try {
+            await client.run('NOOP');
+        } catch (E) {
+            err = E;
+        }
+
+        test.ok(err, 'the failure still reaches the caller');
+        let armed = timers.pending();
+        test.equal(armed.length, 1, 'auto-IDLE is re-armed after the failed IDLE break');
+        test.equal(armed[0].delay, 300);
+
+        client.close();
+    });
+    test.done();
+};
+
+// ============================================================================
+// the socket inactivity watchdog
+// ============================================================================
+
+// A client wired up for _socketTimeout() with recording stubs: recovery commands land in
+// `recovered`, emitted errors in `errors`. run() is stubbed, so nothing here re-arms auto-IDLE -
+// which is deliberate: the handler itself must never start IDLE, that decision belongs to
+// autoidle() once the recovery NOOP settles for real.
+const makeWatchdogClient = () => {
+    let client = makeIdleReadyClient();
+    let errors = [];
+    let recovered = [];
+    client.on('error', err => errors.push(err));
+    client.run = async command => recovered.push(command);
+    client.idle = async () => recovered.push('IDLE');
+    client.writeSocket = client.socket;
+    client.setSocketHandlers();
+    return { client, errors, recovered };
+};
+
+const drainImmediate = () => new Promise(resolve => setImmediate(resolve));
+
+module.exports['Auto-IDLE: a stalled download survives the socket watchdog'] = async test => {
+    // Suppressing auto-IDLE during a download means `idling` is false when the inactivity
+    // watchdog fires, so without the download clause the watchdog would tear down a connection
+    // whose only problem is a consumer that stopped draining.
+    let { client, errors, recovered } = makeWatchdogClient();
+    client._openDownloads = 1;
+
+    client._socketTimeout();
+    await drainImmediate();
+
+    test.deepEqual(errors, [], 'no ETIMEOUT is emitted while a download is open');
+    test.deepEqual(recovered, ['NOOP'], 'kept alive with a NOOP only - IDLE mid-download is what the busy guard exists to prevent');
+
+    client._openDownloads = 0;
+    client._socketTimeout();
+    test.equal(errors.length, 1, 'once the download is done a quiet socket is a timeout again');
+    test.equal(errors[0].code, 'ETIMEOUT');
+
+    client.close();
+    test.ok(client.isClosed, 'the socket stub supports everything close() needs');
+    test.done();
+};
+
+module.exports['Auto-IDLE: a stuck chunk FETCH mid-download is a dead connection'] = async test => {
+    // A quiet socket while a command is awaiting its reply means the reply is overdue. A
+    // recovery NOOP would only queue behind the stuck command and never reach the wire, so
+    // the watchdog must report the timeout instead of recovering into a silent hang.
+    let { client, errors, recovered } = makeWatchdogClient();
+    client._openDownloads = 1;
+    client.currentRequest = { tag: 'A001', command: 'FETCH', sent: true };
+
+    client._socketTimeout();
+    await drainImmediate();
+
+    test.deepEqual(recovered, [], 'no recovery is attempted behind a stuck command');
+    test.equal(errors.length, 1, 'the caller learns the connection is dead');
+    test.equal(errors[0].code, 'ETIMEOUT');
+
+    client.close();
+    test.done();
+};
+
+module.exports['Auto-IDLE: a held mailbox lock keeps a quiet connection alive'] = async test => {
+    // A lock holder pausing between commands for longer than socketTimeout is legitimate (the
+    // held-lock diagnostic warns only after 30 minutes), and with auto-IDLE declining to arm
+    // during a lock there is no IDLE traffic to keep the socket busy - the watchdog has to.
+    let { client, errors, recovered } = makeWatchdogClient();
+    client.currentLock = { lockId: 1 };
+
+    client._socketTimeout();
+    await drainImmediate();
+
+    test.deepEqual(errors, [], 'the lock holder keeps its connection');
+    test.deepEqual(recovered, ['NOOP'], 'kept alive with a NOOP only, no IDLE inside the lock');
+
+    client.currentLock = false;
+    client._socketTimeout();
+    test.equal(errors.length, 1, 'with the lock gone a quiet socket is a timeout again');
+    test.equal(errors[0].code, 'ETIMEOUT');
+
+    client.close();
+    test.done();
+};
+
+module.exports['Auto-IDLE: idling recovers even with the IDLE command in flight'] = async test => {
+    // During true IDLE the in-flight command IS the IDLE command; run() breaks it through
+    // preCheck() before the recovery NOOP goes out, so it does not count as stuck. A recovery
+    // NOOP that then never settles does: the next timeout must fail rather than queue another.
+    let { client, errors, recovered } = makeWatchdogClient();
+    client.idling = true;
+    client.currentRequest = { tag: 'A001', command: 'IDLE', sent: true };
+
+    client._socketTimeout();
+    await drainImmediate();
+    test.deepEqual(errors, [], 'the idling connection is not torn down');
+    test.deepEqual(recovered, ['NOOP'], 'it is recovered with a NOOP');
+
+    client.idling = false;
+    client.currentRequest = { tag: 'A002', command: 'NOOP', sent: true };
+    client._socketTimeout();
+    test.equal(errors.length, 1, 'a recovery NOOP that never settled is a dead connection');
+    test.equal(errors[0].code, 'ETIMEOUT');
+
+    client.close();
+    test.done();
+};

package/test/connection-edge-cases-test.js

@@ -254,7 +254,9 @@ module.exports['Connection Edge: Socket timeout during IDLE'] = test => {
     // Give async operations time to complete
     setTimeout(() => {
         test.ok(noopCalled, 'NOOP should be called to recover from IDLE timeout');
-        test.ok(idleCalled, 'Should return to IDLE after NOOP');
+        // Returning to IDLE is autoidle()'s decision once the NOOP settles (run() re-arms it);
+        // the watchdog handler itself must not bypass the busy guard by calling idle() directly
+        test.equal(idleCalled, false, 'the timeout handler does not restart IDLE by itself');
         test.done();
     }, 100);
 };

package/test/fixtures/test-client.js

@@ -0,0 +1,57 @@
+'use strict';
+
+// Shared ImapFlow construction for unit tests that poke at internals without a live server.
+// One definition instead of a per-file copy, so a change to what the constructor needs lands
+// in one place and cannot drift between suites.
+
+const { ImapFlow } = require('../../lib/imap-flow');
+
+// A socket stub complete enough for setSocketHandlers(), clearSocketHandlers() and close() to
+// run against. removeListener/removeAllListeners matter most: close() removes the handlers it
+// installed, and a stub without them makes close() throw half-way through teardown with the
+// client still holding its socket and streamer references.
+const makeSocketStub = () => ({
+    destroyed: false,
+    destroy: () => {},
+    on: () => {},
+    once: () => {},
+    end: () => {},
+    unpipe: () => {},
+    removeListener: () => {},
+    removeAllListeners: () => {},
+    setKeepAlive: () => {},
+    setTimeout: () => {}
+});
+
+// Bare construction: no socket, no state overrides. Tests that need a transport use
+// makeSocketStub() or makeIdleReadyClient() instead of reaching for their own object literals.
+const makeClient = (overrides = {}) =>
+    new ImapFlow({
+        host: '127.0.0.1',
+        port: 993,
+        logger: false,
+        auth: { user: 'test', pass: 'secret' },
+        ...overrides
+    });
+
+// A client parked in SELECTED with a stubbed socket and a no-op idle(), ready for autoidle(),
+// lock handling and watchdog behavior to be exercised directly
+const makeIdleReadyClient = (overrides = {}) => {
+    let client = makeClient({ maxLockHoldTime: 0, ...overrides });
+    client.socket = makeSocketStub();
+    client.usable = true;
+    client.state = client.states.SELECTED;
+    client.mailbox = { path: 'INBOX', readOnly: false };
+    client.idle = async () => {};
+    return client;
+};
+
+// A fetchOne stand-in that serves `body` back in download()'s chunk-query shape
+// ({source: {start, maxLength}}), so download tests do not each restate that contract
+const chunkedFetchOne = body => async (range, query) => {
+    let start = query.source.start;
+    let maxLength = query.source.maxLength;
+    return { uid: 1, size: body.length, source: body.subarray(start, start + maxLength) };
+};
+
+module.exports = { makeClient, makeIdleReadyClient, makeSocketStub, chunkedFetchOne };

package/test/idle-polling-test.js

@@ -428,3 +428,91 @@ module.exports['Polling: a break in the initiation tick prevents the first poll'
         test.done();
     });
 };
+
+module.exports['Polling: a restarted session resumes the schedule instead of polling again'] = async test => {
+    await withFakeTimers(async timers => {
+        let connection = createConnection();
+
+        let first = idleCommand(connection, 60000);
+        await timers.drain();
+        test.deepEqual(connection.commands, ['NOOP'], 'the first session polls immediately');
+
+        await connection.preCheck();
+        await first;
+
+        // Auto-IDLE restarts the loop after every caller command. An unconditional first poll here
+        // would tie the poll rate to how often the caller runs commands instead of to the poll
+        // interval - with a short autoIdleDelay, a command every few seconds means a poll every
+        // few seconds.
+        let second = idleCommand(connection, 60000);
+        await timers.drain();
+        test.deepEqual(connection.commands, ['NOOP'], 'the restarted session does not poll again');
+        test.equal(timers.count(), 1, 'it waits out the remainder of the interval instead');
+        test.ok(timers.pending()[0].delay <= 60000, 'and never longer than a full interval');
+
+        await connection.preCheck();
+        await second;
+
+        // Once a full interval has elapsed, a fresh session polls at once again
+        connection._lastPollAt = Date.now() - 61000;
+        let third = idleCommand(connection, 60000);
+        await timers.drain();
+        test.deepEqual(connection.commands, ['NOOP', 'NOOP'], 'a session starting after the interval polls right away');
+
+        await connection.preCheck();
+        await third;
+        test.done();
+    });
+};
+
+module.exports['Polling: a failed poll does not defer the next session'] = async test => {
+    await withFakeTimers(async timers => {
+        let failNext = true;
+        let connection = createConnection({
+            exec: async command => {
+                connection.commands.push(command);
+                if (failNext) {
+                    failNext = false;
+                    throw new Error('poll failed');
+                }
+                return { next: () => {} };
+            }
+        });
+
+        // The failing poll cancels its own session. The attempt checked nothing, so it must not
+        // count as a poll: only a completed poll moves the schedule stamp forward.
+        let first = idleCommand(connection, 60000);
+        await timers.drain();
+        await first;
+        test.deepEqual(connection.commands, ['NOOP'], 'the first poll ran and failed');
+
+        let second = idleCommand(connection, 60000);
+        await timers.drain();
+        test.deepEqual(connection.commands, ['NOOP', 'NOOP'], 'the next session retries immediately instead of waiting out an interval');
+
+        await connection.preCheck();
+        await second;
+        test.done();
+    });
+};
+
+module.exports['Polling: a backward clock step never defers the next poll past one interval'] = async test => {
+    await withFakeTimers(async timers => {
+        let connection = createConnection();
+
+        // A last-poll stamp in the future is what an NTP step or a VM clock sync leaves behind.
+        // Without the clamp the remainder math would schedule the next poll a full clock jump
+        // plus one interval away.
+        connection._lastPollAt = Date.now() + 60 * 60 * 1000;
+
+        let idlePromise = idleCommand(connection, 60000);
+        await timers.drain();
+        test.deepEqual(connection.commands, [], 'no immediate poll - the schedule is resumed');
+        test.equal(timers.count(), 1, 'a poll timer is armed');
+        test.ok(timers.pending()[0].delay <= 60000, 'and it is never more than one interval away');
+
+        await connection.preCheck();
+        await idlePromise;
+        test.done();
+    });
+};

package/test/imap-flow-coverage-test.js

@@ -5,6 +5,7 @@
 // reader/handler error branches.
 
 const { ImapFlow } = require('../lib/imap-flow');
+const { makeSocketStub } = require('./fixtures/test-client');
 
 const makeClient = (overrides = {}) => {
     let client = new ImapFlow({
@@ -293,15 +294,6 @@ module.exports['Coverage: authenticate throws when run yields falsy auth result'
 // Socket event handlers (built by setSocketHandlers)
 // ============================================================================
 
-// Minimal socket stub that records listeners so handlers can be invoked directly.
-const makeSocketStub = () => ({
-    destroyed: false,
-    once() {},
-    on() {},
-    removeListener() {},
-    destroy() {}
-});
-
 module.exports['Coverage: setSocketHandlers removes a lingering connect error handler'] = test => {
     let client = makeClient();
     let removed = null;
@@ -389,7 +381,9 @@ module.exports['Coverage: _socketTimeout recovers an IDLE connection with NOOP']
     await drain();
     await drain();
     test.ok(noopRun, 'NOOP issued to recover IDLE');
-    test.ok(idleResumed, 'IDLE resumed after NOOP');
+    // Restarting IDLE is autoidle()'s decision once the NOOP settles (run() re-arms it);
+    // the watchdog handler itself must not bypass the busy guard by calling idle() directly.
+    test.equal(idleResumed, false, 'the handler does not restart IDLE by itself');
     test.done();
 };
 

package/test/imap-flow-fetch-download-test.js

@@ -9,6 +9,7 @@ const libbase64 = require('libbase64');
 const libqp = require('libqp');
 const libmime = require('libmime');
 const { Writable, finished } = require('stream');
+const { chunkedFetchOne } = require('./fixtures/test-client');
 
 const makeClient = (overrides = {}) => {
     let client = new ImapFlow({
@@ -217,11 +218,7 @@ module.exports['Download: returns empty object without mailbox'] = async test =>
 module.exports['Download: full message in multiple chunks'] = async test => {
     let client = makeClient();
     let body = Buffer.from('A'.repeat(10));
-    client.fetchOne = async (range, query) => {
-        let start = query.source.start;
-        let maxLength = query.source.maxLength;
-        return { uid: 1, size: body.length, source: body.slice(start, start + maxLength) };
-    };
+    client.fetchOne = chunkedFetchOne(body);
     let { meta, content } = await client.download('1', false, { chunkSize: 4 });
     test.equal(meta.contentType, 'message/rfc822');
     test.equal(meta.expectedSize, 10);
@@ -233,11 +230,7 @@ module.exports['Download: full message in multiple chunks'] = async test => {
 module.exports['Download: falls back to default chunkSize/maxBytes when zero'] = async test => {
     let client = makeClient();
     let body = Buffer.from('tiny');
-    client.fetchOne = async (range, query) => {
-        let start = query.source.start;
-        let maxLength = query.source.maxLength;
-        return { uid: 1, size: body.length, source: body.slice(start, start + maxLength) };
-    };
+    client.fetchOne = chunkedFetchOne(body);
     // zero values are falsy -> the (|| default) fallbacks kick in
     let { content } = await client.download('1', false, { chunkSize: 0, maxBytes: 0 });
     let data = await collect(content);

package/test/imap-flow-internals-test.js

@@ -6,17 +6,8 @@
 // and the untaggedFetch flag/modseq branches.
 
 const { ImapFlow } = require('../lib/imap-flow');
-
-const makeClient = (overrides = {}) => {
-    let client = new ImapFlow({
-        host: 'imap.example.com',
-        port: 993,
-        auth: { user: 'test', pass: 'test' },
-        logger: false,
-        ...overrides
-    });
-    return client;
-};
+const { withFakeTimers } = require('./fixtures/fake-timers');
+const { makeClient, makeIdleReadyClient } = require('./fixtures/test-client');
 
 // ============================================================================
 // emitError
@@ -275,29 +266,20 @@ module.exports['Internals: autoidle does nothing when not selected'] = test => {
     test.done();
 };
 
-module.exports['Internals: autoidle schedules idle when selected'] = test => {
-    let client = makeClient();
-    client.state = client.states.SELECTED;
+module.exports['Internals: autoidle schedules idle when selected'] = async test => {
+    await withFakeTimers(async timers => {
+        let client = makeIdleReadyClient();
+
+        let idleCalled = false;
+        client.idle = async () => {
+            idleCalled = true;
+        };
 
-    let realSetTimeout = global.setTimeout;
-    let idleCalled = false;
-    client.idle = async () => {
-        idleCalled = true;
-    };
-    // Intercept the 15s idle timer and fire it synchronously
-    global.setTimeout = (fn, ms) => {
-        if (ms === 15 * 1000) {
-            fn();
-            return { unref() {} };
-        }
-        return realSetTimeout(fn, ms);
-    };
-    try {
         client.autoidle();
-    } finally {
-        global.setTimeout = realSetTimeout;
-    }
-    test.ok(idleCalled);
+        await timers.fire();
+
+        test.ok(idleCalled);
+    });
     test.done();
 };
 

package/test/timer-policy-test.js

@@ -9,9 +9,9 @@
 // Asserted through timer identity and cleanup rather than wall-clock sleeps.
 
 const net = require('net');
-const { ImapFlow } = require('../lib/imap-flow');
 const idleCommand = require('../lib/commands/idle.js');
 const { withFakeTimers } = require('./fixtures/fake-timers');
+const { makeClient, makeIdleReadyClient } = require('./fixtures/test-client');
 
 const CAPS = 'IMAP4rev1 ID ENABLE NAMESPACE IDLE';
 
@@ -52,15 +52,6 @@ const createServer = () =>
 
 const listen = server => new Promise(resolve => server.listen(0, '127.0.0.1', () => resolve(server.address().port)));
 
-const makeClient = (overrides = {}) =>
-    new ImapFlow({
-        host: '127.0.0.1',
-        port: 993,
-        logger: false,
-        auth: { user: 'test', pass: 'secret' },
-        ...overrides
-    });
-
 module.exports['Timers: connection and greeting deadlines keep the process alive'] = async test => {
     let server = createServer();
     let port = await listen(server);
@@ -99,15 +90,13 @@ module.exports['Timers: connection and greeting deadlines keep the process alive
 
 module.exports['Timers: the auto-IDLE timer is unrefd and cleared on close'] = async test => {
     await withFakeTimers(async timers => {
-        let client = makeClient();
-        client.state = client.states.SELECTED;
-        client.idle = async () => {};
+        let client = makeIdleReadyClient();
 
         client.autoidle();
 
         let armed = timers.pending();
         test.equal(armed.length, 1, 'exactly one auto-IDLE timer is armed');
-        test.equal(armed[0].delay, 15 * 1000);
+        test.equal(armed[0].delay, client.autoIdleDelay);
         test.ok(armed[0].unrefd, 'the background auto-IDLE timer does not keep the process alive');
 
         client.close();
@@ -119,9 +108,7 @@ module.exports['Timers: the auto-IDLE timer is unrefd and cleared on close'] = a
 
 module.exports['Timers: a restarted auto-IDLE timer replaces the previous one'] = async test => {
     await withFakeTimers(async timers => {
-        let client = makeClient();
-        client.state = client.states.SELECTED;
-        client.idle = async () => {};
+        let client = makeIdleReadyClient();
 
         client.autoidle();
         client.autoidle();