imapflow 1.3.1 → 1.3.3

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.3.1"
+    ".": "1.3.3"
 }

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.3.3](https://github.com/postalsys/imapflow/compare/v1.3.2...v1.3.3) (2026-04-29)
+
+
+### Bug Fixes
+
+* handle NIL delimiter in NAMESPACE response (RFC 2342) ([#351](https://github.com/postalsys/imapflow/issues/351)) ([10bda2a](https://github.com/postalsys/imapflow/commit/10bda2a1d398dc7bc6ea0ede50b1ae48e4b28cf7))
+
+## [1.3.2](https://github.com/postalsys/imapflow/compare/v1.3.1...v1.3.2) (2026-04-17)
+
+
+### Bug Fixes
+
+* Bumped deps ([7b45f61](https://github.com/postalsys/imapflow/commit/7b45f6173b8e942d477612ade86296bac2bcaa79))
+* harden mailbox-lock and error-propagation paths ([7b87d96](https://github.com/postalsys/imapflow/commit/7b87d96f280fa79b3e34b223ba3aa708f2e9bac1))
+
 ## [1.3.1](https://github.com/postalsys/imapflow/compare/v1.3.0...v1.3.1) (2026-04-08)
 
 

package/lib/commands/namespace.js

@@ -4,7 +4,7 @@
  * Requests NAMESPACE info from the server.
  *
  * @param {Object} connection - IMAP connection instance
- * @returns {Promise<{prefix: string, delimiter: string}|{error: boolean, status: string, text: string}>} The primary personal namespace, or an error object on failure
+ * @returns {Promise<{prefix: string, delimiter: string|null}|{error: boolean, status: string, text: string}>} The primary personal namespace, or an error object on failure
  */
 module.exports = async connection => {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
@@ -114,7 +114,7 @@ async function getListPrefix(connection) {
  * Parses namespace information from an IMAP NAMESPACE response attribute.
  *
  * @param {Array} attribute - Namespace attribute array from the server response
- * @returns {Array<{prefix: string, delimiter: string}>|boolean} Array of namespace entries, or false if empty
+ * @returns {Array<{prefix: string, delimiter: string|null}>|boolean} Array of namespace entries, or false if empty
  */
 function getNamsepaceInfo(attribute) {
     if (!attribute || !attribute.length) {
@@ -122,10 +122,15 @@ function getNamsepaceInfo(attribute) {
     }
 
     return attribute
-        .filter(entry => entry.length >= 2 && typeof entry[0].value === 'string' && typeof entry[1].value === 'string')
+        .filter(
+            entry =>
+                // RFC 2342 §5 allows the delimiter to be NIL when the namespace has
+                // no hierarchy. The token parser emits a literal `null` for NIL.
+                entry.length >= 2 && entry[0] && typeof entry[0].value === 'string' && (entry[1] === null || (entry[1] && typeof entry[1].value === 'string'))
+        )
         .map(entry => {
             let prefix = entry[0].value;
-            let delimiter = entry[1].value;
+            let delimiter = entry[1] === null ? null : entry[1].value;
 
             // Append the delimiter to the prefix if it doesn't already end with one,
             // so callers can construct full paths by simply concatenating prefix + name.

package/lib/imap-flow.d.ts

@@ -60,6 +60,12 @@ export interface ImapFlowOptions {
     greetingTimeout?: number;
     /** How long to wait for socket inactivity before timing out the connection. Defaults to 5 minutes */
     socketTimeout?: number;
+    /**
+     * Threshold in milliseconds for warning that a mailbox lock has been held
+     * for a long time (diagnostic for forgotten release() calls). Defaults to
+     * 30 minutes. Set to 0 or false to disable.
+     */
+    maxLockHoldTime?: number | false;
     /** If true, uses TLS. If false, uses cleartext. If not set, upgrades to TLS if available */
     doSTARTTLS?: boolean;
     /** Custom instance ID string for logs */
@@ -549,6 +555,21 @@ export interface MailboxOpenOptions {
     description?: string;
 }
 
+export interface MailboxLockOptions extends MailboxOpenOptions {
+    /**
+     * Optional timeout in milliseconds to wait for the lock to be granted.
+     * If the lock cannot be acquired within this time, the promise rejects
+     * with an error whose `code` is `'LockTimeout'`. Defaults to no timeout.
+     */
+    acquireTimeout?: number;
+    /**
+     * Per-call override for the threshold after which a held lock triggers
+     * a warning log entry. Overrides the ImapFlow constructor option of the
+     * same name. Set to 0 or false to disable for this lock only.
+     */
+    maxLockHoldTime?: number | false;
+}
+
 export interface ExpungeEvent {
     /** Mailbox path */
     path: string;
@@ -783,7 +804,7 @@ export class ImapFlow extends EventEmitter {
     }>;
 
     /** Opens a mailbox if not already open and returns a lock */
-    getMailboxLock(path: string | string[], options?: MailboxOpenOptions): Promise<MailboxLockObject>;
+    getMailboxLock(path: string | string[], options?: MailboxLockOptions): Promise<MailboxLockObject>;
 
     /** Returns byte counters for the current connection, optionally resets them */
     stats(reset?: boolean): { sent: number; received: number };

package/lib/imap-flow.js

@@ -48,6 +48,12 @@ const UPGRADE_TIMEOUT = 10 * 1000;
 
 const SOCKET_TIMEOUT = 5 * 60 * 1000;
 
+// Default threshold for warning that a mailbox lock has been held for a long
+// time. Intended to catch forgotten release() calls, not legitimate long ops
+// (e.g. fetching hundreds of thousands of messages). Configurable via the
+// ImapFlow constructor option `maxLockHoldTime`. Set to 0 or false to disable.
+const HELD_LOCK_WARN_MS = 30 * 60 * 1000;
+
 const states = {
     NOT_AUTHENTICATED: 0x01,
     AUTHENTICATED: 0x02,
@@ -670,7 +676,11 @@ class ImapFlow extends EventEmitter {
             // 1. During IDLE or AUTHENTICATE, where a custom handler (onPlusTag) processes it
             // 2. During literal data transfer, where we send the next queued literal chunk
             if (parsed.tag === '+' && this.currentRequest && this.currentRequest.options && typeof this.currentRequest.options.onPlusTag === 'function') {
-                await this.currentRequest.options.onPlusTag(parsed);
+                try {
+                    await this.currentRequest.options.onPlusTag(parsed);
+                } catch (err) {
+                    this.log.warn({ err, cid: this.id });
+                }
                 data.next();
                 continue;
             }
@@ -688,7 +698,11 @@ class ImapFlow extends EventEmitter {
             if (section && section.length && section[0].type === 'ATOM' && typeof section[0].value === 'string') {
                 let sectionHandler = this.getSectionHandler(section[0].value.toUpperCase().trim());
                 if (sectionHandler) {
-                    await sectionHandler(section.slice(1));
+                    try {
+                        await sectionHandler(section.slice(1));
+                    } catch (err) {
+                        this.log.warn({ err, cid: this.id });
+                    }
                 }
             }
 
@@ -1209,6 +1223,12 @@ class ImapFlow extends EventEmitter {
         });
 
         if (upgraded && this.expectCapabilityUpdate) {
+            // After STARTTLS the server may advertise a different capability set
+            // (e.g., LOGINDISABLED removed, new AUTH= methods). Clear the pre-TLS
+            // map before re-fetching so stale capabilities cannot leak through
+            // if the CAPABILITY response is delayed or absent.
+            this.capabilities.clear();
+            this.authCapabilities.clear();
             await this.run('CAPABILITY');
         }
 
@@ -1841,12 +1861,21 @@ class ImapFlow extends EventEmitter {
                 request.reject(createNoConnectionError(byeReason));
             }
 
-            // Clear current lock - holder will see errors when they try operations
+            // Clear current lock - holder will see errors when they try operations.
+            // Also clear the held-lock diagnostic timer so it doesn't fire post-close.
+            if (this.currentLock && this.currentLock.heldWarnTimer) {
+                clearTimeout(this.currentLock.heldWarnTimer);
+                this.currentLock.heldWarnTimer = null;
+            }
             this.currentLock = false;
 
             if (this.locks && this.locks.length) {
                 let pendingLocks = this.locks.splice(0); // Take all locks and clear the array
                 for (let lock of pendingLocks) {
+                    if (lock.acquireTimer) {
+                        clearTimeout(lock.acquireTimer);
+                        lock.acquireTimer = null;
+                    }
                     if (typeof lock.reject === 'function') {
                         lock.reject(createNoConnectionError(byeReason));
                     }
@@ -3180,6 +3209,15 @@ class ImapFlow extends EventEmitter {
             if (meta.charset && !['ascii', 'usascii', 'utf8'].includes(meta.charset.toLowerCase().replace(/[^a-z0-9]+/g, ''))) {
                 try {
                     let decoder = getDecoder(meta.charset);
+                    // Safety listener attached first so the decoder always has at least
+                    // one 'error' listener. Prevents Node.js from throwing
+                    // ERR_UNHANDLED_ERROR if a later pipe setup step throws and leaves
+                    // the source-forwarding closure attached without a downstream
+                    // listener wired up. Any real listener the caller attaches still
+                    // fires in addition to this one.
+                    decoder.on('error', err => {
+                        this.log.warn({ err, charset: meta.charset, cid: this.id });
+                    });
                     output.on('error', err => {
                         decoder.emit('error', err);
                     });
@@ -3516,32 +3554,79 @@ class ImapFlow extends EventEmitter {
             // Process all locks in queue until empty
             let processedCount = 0;
             while (this.locks.length > 0) {
+                // Mutex invariant: at most one lock may be held at a time.
+                // If a lock is already granted, stop processing; release() will
+                // clear currentLock and reschedule us to pick up the next queued lock.
+                if (this.currentLock) {
+                    break;
+                }
+
                 // Yield to event loop periodically to prevent CPU blocking
                 processedCount++;
                 if (processedCount % 5 === 0) {
                     await new Promise(resolve => setImmediate(resolve));
                 }
 
+                const lock = this.locks.shift();
+                const { resolve, reject, path, options, lockId } = lock;
+
+                // From here on the grant/reject path owns the outcome; the acquire
+                // timer must not race with resolution.
+                if (lock.acquireTimer) {
+                    clearTimeout(lock.acquireTimer);
+                    lock.acquireTimer = null;
+                }
+
+                const armHeldTimer = () => {
+                    let threshold = Number(options.maxLockHoldTime ?? this.options.maxLockHoldTime ?? HELD_LOCK_WARN_MS);
+                    if (!threshold || threshold <= 0) {
+                        return;
+                    }
+                    lock.heldAt = Date.now();
+                    lock.heldWarnTimer = setTimeout(() => {
+                        lock.heldWarnTimer = null;
+                        this.log.warn({
+                            msg: 'Mailbox lock held for a long time',
+                            lockId: lock.lockId,
+                            path,
+                            heldFor: Date.now() - lock.heldAt,
+                            ...(options.description && { description: options.description }),
+                            cid: this.id
+                        });
+                    }, threshold);
+                };
+
+                // release() is captured per-lock. It must only clear this.currentLock
+                // if the caller still owns it — otherwise a stale release (after a
+                // disconnect replaced the lock, or a double-release from user code)
+                // would clear the new holder's lock and allow concurrent access.
                 const release = () => {
-                    if (this.currentLock) {
+                    if (this.currentLock === lock) {
+                        if (lock.heldWarnTimer) {
+                            clearTimeout(lock.heldWarnTimer);
+                            lock.heldWarnTimer = null;
+                        }
                         this.log.trace({
                             msg: 'Mailbox lock released',
-                            lockId: this.currentLock.lockId,
+                            lockId: lock.lockId,
                             path: this.mailbox && this.mailbox.path,
                             pending: this.locks.length,
                             idling: this.idling
                         });
                         this.currentLock = false;
+                        // Use setImmediate to avoid stack overflow
+                        setImmediate(() => {
+                            this.processLocks().catch(err => this.log.error({ err, cid: this.id }));
+                        });
+                    } else {
+                        this.log.trace({
+                            msg: 'Ignoring stale lock release',
+                            lockId: lock.lockId,
+                            cid: this.id
+                        });
                     }
-                    // Use setImmediate to avoid stack overflow
-                    setImmediate(() => {
-                        this.processLocks().catch(err => this.log.error({ err, cid: this.id }));
-                    });
                 };
 
-                const lock = this.locks.shift();
-                const { resolve, reject, path, options, lockId } = lock;
-
                 if (!this.usable || !this.socket || this.socket.destroyed) {
                     this.log.trace({ msg: 'Failed to acquire mailbox lock', path, lockId, idling: this.idling });
                     let error = new Error('Connection not available');
@@ -3560,6 +3645,7 @@ class ImapFlow extends EventEmitter {
                         ...(options.description && { description: options.description })
                     });
                     this.currentLock = lock;
+                    armHeldTimer();
                     resolve({ path, release });
                     break; // Stop processing; next lock waits for release()
                 }
@@ -3575,6 +3661,7 @@ class ImapFlow extends EventEmitter {
                         ...(options.description && { description: options.description })
                     });
                     this.currentLock = lock;
+                    armHeldTimer();
                     resolve({ path, release });
                     break; // Wait for this lock to be released
                 } catch (err) {
@@ -3659,7 +3746,26 @@ class ImapFlow extends EventEmitter {
         });
 
         let lockPromise = new Promise((resolve, reject) => {
-            this.locks.push({ resolve, reject, path, options, lockId });
+            let lockEntry = { resolve, reject, path, options, lockId };
+            this.locks.push(lockEntry);
+
+            // Opt-in acquire timeout: if the lock has not been granted within
+            // acquireTimeout ms, remove it from the queue and reject. Only
+            // affects queued (pending) locks — once granted, the timer is cleared.
+            if (Number(options.acquireTimeout) > 0) {
+                lockEntry.acquireTimer = setTimeout(() => {
+                    lockEntry.acquireTimer = null;
+                    const idx = this.locks.indexOf(lockEntry);
+                    if (idx !== -1) {
+                        this.locks.splice(idx, 1);
+                        let err = new Error('Timed out waiting for mailbox lock');
+                        err.code = 'LockTimeout';
+                        err.lockId = lockEntry.lockId;
+                        reject(err);
+                    }
+                }, Number(options.acquireTimeout));
+            }
+
             this.processLocks().catch(err => reject(err));
         });
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.3.1",
+    "version": "1.3.3",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",
@@ -28,28 +28,28 @@
     "homepage": "https://imapflow.com/",
     "devDependencies": {
         "@eslint/js": "10.0.1",
-        "@types/node": "25.5.2",
+        "@types/node": "25.6.0",
         "c8": "11.0.0",
-        "eslint": "10.2.0",
+        "eslint": "10.2.1",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "10.1.8",
-        "grunt": "1.6.1",
+        "grunt": "1.6.2",
         "grunt-cli": "1.5.0",
         "grunt-contrib-nodeunit": "5.0.0",
         "grunt-eslint": "26.0.0",
-        "prettier": "3.8.1",
+        "prettier": "3.8.3",
         "proxyquire": "^2.1.3",
-        "typescript": "6.0.2"
+        "typescript": "6.0.3"
     },
     "dependencies": {
-        "@zone-eu/mailsplit": "5.4.8",
+        "@zone-eu/mailsplit": "5.4.9",
         "encoding-japanese": "2.2.0",
         "iconv-lite": "0.7.2",
         "libbase64": "1.3.0",
         "libmime": "5.3.8",
         "libqp": "2.1.1",
-        "nodemailer": "8.0.5",
+        "nodemailer": "8.0.7",
         "pino": "10.3.1",
-        "socks": "2.8.7"
+        "socks": "2.8.8"
     }
 }

package/test/commands-integration-test.js

@@ -6457,6 +6457,185 @@ module.exports['Commands: namespace handles NIL namespaces'] = async test => {
     test.done();
 };
 
+module.exports['Commands: namespace handles NIL delimiter (RFC 2342)'] = async test => {
+    // RFC 2342 §5: NIL delimiter means the namespace has no hierarchy.
+    // The token parser emits a literal `null` for NIL.
+
+    const connection = createMockConnection({
+        state: 2,
+        capabilities: new Map([['NAMESPACE', true]]),
+        exec: async (cmd, args, opts) => {
+            if (opts && opts.untagged && opts.untagged.NAMESPACE) {
+                await opts.untagged.NAMESPACE({
+                    attributes: [
+                        [
+                            [{ value: '' }, { value: '/' }],
+                            [{ value: '#hidden' }, null]
+                        ],
+                        null,
+                        null
+                    ]
+                });
+            }
+            return { next: () => {} };
+        }
+    });
+
+    const result = await namespaceCommand(connection);
+
+    // Guard against handler crash so a regression surfaces as a failed
+    // assertion rather than fatal-halting the whole nodeunit suite.
+    if (result && result.error) {
+        test.ok(false, 'namespace command returned error sentinel — likely crashed on NIL delimiter');
+        test.done();
+        return;
+    }
+    if (!Array.isArray(connection.namespaces && connection.namespaces.personal)) {
+        test.ok(false, 'connection.namespaces.personal is not an array (handler crashed mid-untagged-callback)');
+        test.done();
+        return;
+    }
+
+    test.equal(connection.namespaces.personal.length, 2, 'both personal entries should be parsed');
+
+    test.equal(connection.namespaces.personal[0].prefix, '');
+    test.equal(connection.namespaces.personal[0].delimiter, '/');
+
+    // NIL-delimiter entry preserved with delimiter:null rather than dropped silently.
+    test.equal(connection.namespaces.personal[1].prefix, '#hidden');
+    test.equal(connection.namespaces.personal[1].delimiter, null);
+
+    // Default namespace pointer resolves to the first valid personal entry.
+    test.equal(connection.namespace.prefix, '');
+    test.equal(connection.namespace.delimiter, '/');
+
+    test.done();
+};
+
+module.exports['Commands: namespace handles NIL delimiter as only personal entry'] = async test => {
+    // Edge case: only a NIL-delimiter entry in the personal section.
+    // connection.namespace must still be set and usable downstream.
+
+    const connection = createMockConnection({
+        state: 2,
+        capabilities: new Map([['NAMESPACE', true]]),
+        exec: async (cmd, args, opts) => {
+            if (opts && opts.untagged && opts.untagged.NAMESPACE) {
+                await opts.untagged.NAMESPACE({
+                    attributes: [[[{ value: '#hidden' }, null]], null, null]
+                });
+            }
+            return { next: () => {} };
+        }
+    });
+
+    const result = await namespaceCommand(connection);
+
+    if (result && result.error) {
+        test.ok(false, 'namespace command returned error sentinel — likely crashed on NIL delimiter');
+        test.done();
+        return;
+    }
+    if (!Array.isArray(connection.namespaces && connection.namespaces.personal)) {
+        test.ok(false, 'connection.namespaces.personal is not an array (handler crashed mid-untagged-callback)');
+        test.done();
+        return;
+    }
+
+    test.equal(connection.namespaces.personal.length, 1);
+    test.equal(connection.namespaces.personal[0].prefix, '#hidden');
+    test.equal(connection.namespaces.personal[0].delimiter, null);
+
+    test.ok(connection.namespace);
+    test.equal(connection.namespace.prefix, '#hidden');
+    test.equal(connection.namespace.delimiter, null);
+
+    test.done();
+};
+
+module.exports['Commands: namespace handles NIL delimiter in other and shared sections'] = async test => {
+    // NIL delimiter is also valid in the `other` and `shared` sections,
+    // not just `personal`.
+
+    const connection = createMockConnection({
+        state: 2,
+        capabilities: new Map([['NAMESPACE', true]]),
+        exec: async (cmd, args, opts) => {
+            if (opts && opts.untagged && opts.untagged.NAMESPACE) {
+                await opts.untagged.NAMESPACE({
+                    attributes: [[[{ value: '' }, { value: '/' }]], [[{ value: 'Other Users/' }, null]], [[{ value: 'Public/' }, null]]]
+                });
+            }
+            return { next: () => {} };
+        }
+    });
+
+    const result = await namespaceCommand(connection);
+
+    if (result && result.error) {
+        test.ok(false, 'namespace command returned error sentinel — likely crashed on NIL delimiter');
+        test.done();
+        return;
+    }
+
+    test.ok(Array.isArray(connection.namespaces.other), 'other should be an array');
+    test.equal(connection.namespaces.other.length, 1);
+    test.equal(connection.namespaces.other[0].prefix, 'Other Users/');
+    test.equal(connection.namespaces.other[0].delimiter, null);
+
+    test.ok(Array.isArray(connection.namespaces.shared), 'shared should be an array');
+    test.equal(connection.namespaces.shared.length, 1);
+    test.equal(connection.namespaces.shared[0].prefix, 'Public/');
+    test.equal(connection.namespaces.shared[0].delimiter, null);
+
+    test.done();
+};
+
+module.exports['Commands: namespace skips malformed entries without crashing'] = async test => {
+    // The filter must reject entries that don't match either the
+    // (string-prefix, string-delimiter) or (string-prefix, NIL) shape,
+    // so a single broken entry from a buggy server doesn't poison
+    // the whole namespace list or crash the handler.
+
+    const connection = createMockConnection({
+        state: 2,
+        capabilities: new Map([['NAMESPACE', true]]),
+        exec: async (cmd, args, opts) => {
+            if (opts && opts.untagged && opts.untagged.NAMESPACE) {
+                await opts.untagged.NAMESPACE({
+                    attributes: [
+                        [
+                            [{ value: '' }, { value: '/' }], // valid
+                            [{ value: '#hidden' }, null], // valid (NIL delimiter)
+                            [{ value: 'broken' }], // too short — rejected
+                            [null, { value: '/' }], // null prefix — rejected
+                            [{ value: 123 }, { value: '/' }] // non-string prefix — rejected
+                        ],
+                        null,
+                        null
+                    ]
+                });
+            }
+            return { next: () => {} };
+        }
+    });
+
+    const result = await namespaceCommand(connection);
+
+    if (result && result.error) {
+        test.ok(false, 'namespace command returned error sentinel — likely crashed on malformed entry');
+        test.done();
+        return;
+    }
+
+    test.equal(connection.namespaces.personal.length, 2, 'only the two well-formed entries should be kept');
+    test.equal(connection.namespaces.personal[0].prefix, '');
+    test.equal(connection.namespaces.personal[1].prefix, '#hidden');
+    test.equal(connection.namespaces.personal[1].delimiter, null);
+
+    test.done();
+};
+
 module.exports['Commands: namespace handles multiple personal namespaces'] = async test => {
     const connection = createMockConnection({
         state: 2,

package/test/reliability-improvements-test.js

@@ -0,0 +1,370 @@
+'use strict';
+
+// Tests for reliability/stability improvements: lock identity, acquireTimeout,
+// maxLockHoldTime diagnostic, capability-clear-on-STARTTLS, and related
+// cleanup paths.
+
+const { ImapFlow } = require('../lib/imap-flow');
+const iconv = require('iconv-lite');
+
+// Helper: client with stubbed socket/usable state so the fast path of
+// getMailboxLock() can grant locks synchronously (no network I/O).
+const makeClient = (overrides = {}) => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        port: 993,
+        auth: { user: 'test', pass: 'test' },
+        logger: false,
+        ...overrides
+    });
+    client.socket = { destroyed: false, destroy: () => {} };
+    client.usable = true;
+    client.mailbox = { path: 'INBOX', readOnly: false };
+    return client;
+};
+
+// Helper: wait for any queued setImmediate callbacks (processLocks reschedules
+// itself via setImmediate after a release).
+const drain = () => new Promise(resolve => setImmediate(resolve));
+
+// ============================================================================
+// release() identity check
+// ============================================================================
+
+module.exports['Reliability: stale release() does not clear replacement lock'] = async test => {
+    let client = makeClient();
+
+    // Grant L1 via fast path
+    let lockA = await client.getMailboxLock('INBOX');
+    let staleRelease = lockA.release;
+
+    // Release L1 normally
+    staleRelease();
+    await drain();
+    test.equal(client.currentLock, false, 'L1 released');
+
+    // Grant L2
+    let lockB = await client.getMailboxLock('INBOX');
+    test.ok(client.currentLock, 'L2 active');
+    let currentBeforeStale = client.currentLock;
+
+    // Stale call — must NOT clear L2's hold
+    staleRelease();
+    test.equal(client.currentLock, currentBeforeStale, 'L2 still active after stale release');
+
+    lockB.release();
+    await drain();
+    test.done();
+};
+
+module.exports['Reliability: double release() is idempotent'] = async test => {
+    let client = makeClient();
+
+    let lock = await client.getMailboxLock('INBOX');
+
+    // First release clears
+    lock.release();
+    await drain();
+    test.equal(client.currentLock, false);
+
+    // Second release is a no-op — must not throw, must not affect state
+    test.doesNotThrow(() => lock.release());
+    test.equal(client.currentLock, false);
+
+    test.done();
+};
+
+// ============================================================================
+// acquireTimeout
+// ============================================================================
+
+module.exports['Reliability: acquireTimeout rejects with LockTimeout code'] = async test => {
+    let client = makeClient();
+
+    // Hold the first lock so the next one queues
+    let lockA = await client.getMailboxLock('INBOX');
+
+    let start = Date.now();
+    try {
+        await client.getMailboxLock('INBOX', { acquireTimeout: 30 });
+        test.ok(false, 'Should have timed out');
+    } catch (err) {
+        let elapsed = Date.now() - start;
+        test.equal(err.code, 'LockTimeout');
+        test.ok(err.message.includes('Timed out'));
+        test.ok(typeof err.lockId === 'number');
+        test.ok(elapsed >= 25, `expected to wait ~30ms, got ${elapsed}`);
+    }
+
+    // Original lock must still be held
+    test.ok(client.currentLock, 'L1 still held after L2 timeout');
+
+    lockA.release();
+    await drain();
+    test.done();
+};
+
+module.exports['Reliability: acquireTimeout cleared when lock is granted'] = async test => {
+    let client = makeClient();
+
+    // Fast path grants immediately; timer never fires
+    let lock = await client.getMailboxLock('INBOX', { acquireTimeout: 50 });
+    test.ok(lock);
+    test.ok(client.currentLock, 'L1 granted');
+
+    // Wait past the timeout — no rejection should occur post-grant, no dangling timer
+    await new Promise(r => setTimeout(r, 80));
+    test.ok(client.currentLock, 'Still held after timer would have fired');
+
+    lock.release();
+    await drain();
+    test.done();
+};
+
+module.exports['Reliability: acquireTimeout cleared on close()'] = async test => {
+    let client = makeClient();
+    // Hold L1 so L2 queues
+    let lockA = await client.getMailboxLock('INBOX');
+
+    let rejectedCode = null;
+    client.getMailboxLock('INBOX', { acquireTimeout: 10_000 }).catch(err => {
+        rejectedCode = err.code;
+    });
+
+    // Immediately close — pending lock should reject with NoConnection (not LockTimeout),
+    // and its acquireTimer should be cleared so it never fires afterward.
+    client.close();
+
+    await drain();
+    await new Promise(r => setTimeout(r, 30));
+    test.equal(rejectedCode, 'NoConnection', 'Pending lock rejects with NoConnection on close');
+
+    // Keep reference so linter doesn't complain
+    test.ok(lockA);
+    test.done();
+};
+
+// ============================================================================
+// maxLockHoldTime diagnostic
+// ============================================================================
+
+module.exports['Reliability: maxLockHoldTime warning fires when lock held past threshold'] = async test => {
+    let warnings = [];
+    let client = makeClient();
+    client.log.warn = obj => warnings.push(obj);
+
+    let lock = await client.getMailboxLock('INBOX', { maxLockHoldTime: 30 });
+    await new Promise(r => setTimeout(r, 60));
+
+    let hit = warnings.find(w => w && w.msg === 'Mailbox lock held for a long time');
+    test.ok(hit, 'Warning log must fire');
+    test.ok(typeof hit.heldFor === 'number' && hit.heldFor >= 25);
+
+    lock.release();
+    await drain();
+    test.done();
+};
+
+module.exports['Reliability: maxLockHoldTime=0 disables the warning'] = async test => {
+    let warnings = [];
+    let client = makeClient();
+    client.log.warn = obj => warnings.push(obj);
+
+    let lock = await client.getMailboxLock('INBOX', { maxLockHoldTime: 0 });
+    await new Promise(r => setTimeout(r, 30));
+
+    test.ok(!warnings.some(w => w && w.msg === 'Mailbox lock held for a long time'), 'No warn when disabled');
+
+    lock.release();
+    await drain();
+    test.done();
+};
+
+module.exports['Reliability: maxLockHoldTime=false disables the warning'] = async test => {
+    let warnings = [];
+    let client = makeClient();
+    client.log.warn = obj => warnings.push(obj);
+
+    let lock = await client.getMailboxLock('INBOX', { maxLockHoldTime: false });
+    await new Promise(r => setTimeout(r, 30));
+
+    test.ok(!warnings.some(w => w && w.msg === 'Mailbox lock held for a long time'));
+
+    lock.release();
+    await drain();
+    test.done();
+};
+
+module.exports['Reliability: per-call maxLockHoldTime overrides constructor option'] = async test => {
+    let warnings = [];
+    // Constructor sets a long threshold; per-call sets a short one
+    let client = makeClient({ maxLockHoldTime: 10_000 });
+    client.log.warn = obj => warnings.push(obj);
+
+    let lock = await client.getMailboxLock('INBOX', { maxLockHoldTime: 20 });
+    await new Promise(r => setTimeout(r, 50));
+
+    test.ok(warnings.some(w => w && w.msg === 'Mailbox lock held for a long time'), 'Per-call override must take effect');
+
+    lock.release();
+    await drain();
+    test.done();
+};
+
+module.exports['Reliability: held-lock timer cleared on release (does not fire after)'] = async test => {
+    let warnings = [];
+    let client = makeClient();
+    client.log.warn = obj => warnings.push(obj);
+
+    let lock = await client.getMailboxLock('INBOX', { maxLockHoldTime: 50 });
+    lock.release();
+    await drain();
+
+    // Wait longer than the threshold — no warning should appear because release cleared it
+    await new Promise(r => setTimeout(r, 80));
+    test.ok(!warnings.some(w => w && w.msg === 'Mailbox lock held for a long time'));
+
+    test.done();
+};
+
+module.exports['Reliability: held-lock timer cleared on close()'] = async test => {
+    let warnings = [];
+    let client = makeClient();
+    client.log.warn = obj => warnings.push(obj);
+
+    let lock = await client.getMailboxLock('INBOX', { maxLockHoldTime: 30 });
+    test.ok(lock);
+    client.close();
+
+    await new Promise(r => setTimeout(r, 60));
+    test.ok(!warnings.some(w => w && w.msg === 'Mailbox lock held for a long time'));
+
+    test.done();
+};
+
+// ============================================================================
+// STARTTLS capability reset
+// ============================================================================
+
+module.exports['Reliability: STARTTLS code path clears capabilities before re-fetch'] = async test => {
+    // Verify the clear() calls happen by driving the same branch directly.
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        port: 993,
+        auth: { user: 'test', pass: 'test' },
+        logger: false
+    });
+
+    client.capabilities.set('LOGINDISABLED', true);
+    client.capabilities.set('STARTTLS', true);
+    client.authCapabilities.set('AUTH=PLAIN', false);
+
+    // Stub the run() that would re-fetch CAPABILITY post-TLS
+    let ran = [];
+    client.run = async command => {
+        ran.push(command);
+        return true;
+    };
+
+    client.expectCapabilityUpdate = true;
+    // Execute the same statements that the STARTTLS-success branch runs
+    // (guards the behavior contract: caches are cleared before re-fetch)
+    if (client.expectCapabilityUpdate) {
+        client.capabilities.clear();
+        client.authCapabilities.clear();
+        await client.run('CAPABILITY');
+    }
+
+    test.equal(client.capabilities.size, 0, 'capabilities map cleared');
+    test.equal(client.authCapabilities.size, 0, 'authCapabilities map cleared');
+    test.deepEqual(ran, ['CAPABILITY']);
+
+    test.done();
+};
+
+// ============================================================================
+// Handler try/catch (smoke tests via direct invocation)
+// ============================================================================
+
+module.exports['Reliability: sectionHandler throw is caught (no handler -> no effect)'] = async test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        port: 993,
+        auth: { user: 'test', pass: 'test' },
+        logger: false
+    });
+
+    // Install a section handler that throws
+    client.getSectionHandler = () => async () => {
+        throw new Error('handler boom');
+    };
+
+    // The production path awaits the handler inside a try/catch in reader().
+    // Replicate that contract: the wrapping semantics here should not reject.
+    let handler = client.getSectionHandler('TEST');
+    let caught = false;
+    try {
+        // Mimic reader() — it does: try { await handler(...) } catch (err) { log.warn(...) }
+        try {
+            await handler([]);
+        } catch (err) {
+            caught = true;
+            test.ok(err.message.includes('boom'));
+        }
+    } catch (unexpected) {
+        test.ok(false, 'Outer catch should not observe: ' + unexpected.message);
+    }
+
+    test.ok(caught, 'Thrown error is captured by inner try/catch');
+    test.done();
+};
+
+module.exports['Reliability: onPlusTag throw is caught (no handler -> no effect)'] = async test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        port: 993,
+        auth: { user: 'test', pass: 'test' },
+        logger: false
+    });
+    test.ok(client);
+
+    // Simulate a currentRequest with a throwing onPlusTag
+    let onPlusTag = async () => {
+        throw new Error('plus tag boom');
+    };
+
+    // The reader() path wraps this call in try/catch; replicate the contract.
+    let caught = false;
+    try {
+        await onPlusTag({});
+    } catch (err) {
+        caught = true;
+        test.ok(err.message.includes('boom'));
+    }
+    test.ok(caught);
+    test.done();
+};
+
+// ============================================================================
+// Charset decoder defensive listener
+// ============================================================================
+
+module.exports['Reliability: decoder emit(error) does not crash when user has not attached listener'] = test => {
+    // Pattern: after a getDecoder() + defensive .on('error') + decoder.emit('error', err),
+    // the process does not throw (because at least one listener was registered).
+    let decoder = iconv.decodeStream('latin1');
+
+    // Attach the same kind of safety listener the production code installs
+    let warned = 0;
+    decoder.on('error', () => {
+        warned++;
+    });
+
+    // Simulate forwarding a source error into the decoder
+    test.doesNotThrow(() => {
+        decoder.emit('error', new Error('source stream failed'));
+    });
+    test.equal(warned, 1);
+
+    test.done();
+};