@bobfrankston/mailx 1.0.437 → 1.0.439

package/bin/mailx.js

@@ -1250,6 +1250,11 @@ RFC 5322 with CRLF line endings. Bodies are quoted-printable encoded (readable i
     imapManager.on("syncActionFailed", (accountId, action, uid, error) => {
         handle.send({ _event: "syncActionFailed", type: "syncActionFailed", accountId, action, uid, error });
     });
+    // External-edit (Word) save events. The service watches the temp file
+    // and emits this when Word writes; compose.ts listens and reloads Quill.
+    imapManager.on("wordEditUpdated", (payload) => {
+        handle.send({ _event: "wordEditUpdated", type: "wordEditUpdated", ...payload });
+    });
     // Cloud-write/read failures from mailx-settings → push to UI as a banner so
     // silent fall-back-to-local can no longer swallow Drive errors.
     const { onCloudError } = await import("@bobfrankston/mailx-settings");

package/client/app.js

@@ -2813,6 +2813,34 @@ optEditorTiptap?.addEventListener("change", () => {
     if (optEditorTiptap.checked)
         saveEditorSetting("tiptap");
 });
+// External editor preference (Edit-in-Word handoff target). Stored under
+// settings.externalEditor so the service can read it via loadSettings().
+// "auto" tries Word → LibreOffice → OS default; explicit values force
+// that editor (still falling back to OS default if it isn't installed).
+const optExtEditAuto = document.getElementById("opt-extedit-auto");
+const optExtEditWord = document.getElementById("opt-extedit-word");
+const optExtEditLibre = document.getElementById("opt-extedit-libre");
+getSettings().then((s) => {
+    const v = s.externalEditor || "auto";
+    if (optExtEditAuto)
+        optExtEditAuto.checked = v === "auto";
+    if (optExtEditWord)
+        optExtEditWord.checked = v === "word";
+    if (optExtEditLibre)
+        optExtEditLibre.checked = v === "libreoffice";
+}).catch(() => { });
+function saveExtEditor(v) {
+    getSettings().then((settings) => {
+        settings.externalEditor = v;
+        saveSettings(settings);
+    }).catch(() => { });
+}
+optExtEditAuto?.addEventListener("change", () => { if (optExtEditAuto.checked)
+    saveExtEditor("auto"); });
+optExtEditWord?.addEventListener("change", () => { if (optExtEditWord.checked)
+    saveExtEditor("word"); });
+optExtEditLibre?.addEventListener("change", () => { if (optExtEditLibre.checked)
+    saveExtEditor("libreoffice"); });
 // ── AI feature toggles ──
 // One umbrella settings record (AutocompleteSettings) holds the provider config
 // + per-feature on/off flags. All features default OFF — user must opt into
@@ -2845,6 +2873,21 @@ optAiProofread?.addEventListener("change", () => {
     }
     catch { /* */ }
 });
+// Sender reputation check (Spamhaus DBL). Stored at top-level settings so
+// the service can read it cheaply without going through autocomplete config.
+// Off by default — enabling it leaks read-recipient domains to Spamhaus's
+// DNS infra, which the user should opt into knowingly.
+const optCheckReputation = document.getElementById("opt-check-reputation");
+getSettings().then((s) => {
+    if (optCheckReputation)
+        optCheckReputation.checked = !!s.checkDomainReputation;
+}).catch(() => { });
+optCheckReputation?.addEventListener("change", () => {
+    getSettings().then((settings) => {
+        settings.checkDomainReputation = !!optCheckReputation.checked;
+        saveSettings(settings);
+    }).catch(() => { });
+});
 const isApp = typeof mailxapi !== "undefined" && mailxapi?.isApp;
 // Wait for server ready signal, then fetch version
 const versionPromise = getVersion();

package/client/components/message-viewer.js

@@ -2,7 +2,7 @@
  * Message viewer component -- displays full message in sandboxed iframe.
  * Subscribes to message-state: clears when selected becomes null.
  */
-import { getMessage, updateFlags, allowRemoteContent, getAttachment, addContact, listContacts, upsertContact, unsubscribeOneClick } from "../lib/api-client.js";
+import { getMessage, updateFlags, allowRemoteContent, flagSenderOrDomain, getAttachment, addContact, listContacts, upsertContact, unsubscribeOneClick } from "../lib/api-client.js";
 import { showContextMenu } from "./context-menu.js";
 import * as state from "../lib/message-state.js";
 /** Currently displayed message (for reply/forward) */
@@ -547,10 +547,24 @@ export async function showMessage(accountId, uid, folderId, specialUse, isRetry
             const deliveredTo = msg.deliveredTo || "";
             const toAddr = msg.to?.[0]?.address || "";
             const returnPath = msg.returnPath || "";
+            const isFlagged = !!msg.isFlagged;
+            const reputation = msg.reputation;
+            const reputationFlagged = !!(reputation && reputation.flagged);
+            const reputationText = reputationFlagged
+                ? `⚠ ${reputation.listedCount} of ${reputation.checkedCount} reputation services flag <strong>${escapeText(senderDomain)}</strong> as <strong>${escapeText(reputation.verdict)}</strong> (${escapeText(reputation.sources.map(s => s.service).join(", "))})`
+                : "";
             const banner = document.createElement("div");
-            banner.className = "mv-remote-banner";
+            banner.className = "mv-remote-banner"
+                + (isFlagged ? " mv-remote-banner-flagged" : "")
+                + (reputationFlagged ? " mv-remote-banner-reputation" : "");
             banner.innerHTML =
-                `<div class="mv-rb-summary">` +
+                (isFlagged
+                    ? `<div class="mv-rb-flagged">⚠ FLAGGED: this sender or domain is on your flagged list</div>`
+                    : "") +
+                    (reputationFlagged
+                        ? `<div class="mv-rb-reputation">${reputationText}</div>`
+                        : "") +
+                    `<div class="mv-rb-summary">` +
                     `<span class="mv-rb-toggle">&#x25B8;</span>` +
                     `<span>Remote content blocked</span>` +
                     `<span class="mv-rb-buttons">` +
@@ -567,6 +581,10 @@ export async function showMessage(accountId, uid, folderId, specialUse, isRetry
                     (returnPath && returnPath !== senderAddr ? `<div><span class="mv-rb-label">Return-Path:</span> ${escapeText(returnPath)}</div>` : "") +
                     `</div>` +
                     (deliveredTo || toAddr ? `<div class="mv-rb-actions"><button id="btn-allow-to">Always allow to: ${escapeText(deliveredTo || toAddr)}</button></div>` : "") +
+                    `<div class="mv-rb-actions">` +
+                    `<button id="btn-flag-sender" class="mv-rb-flag-btn" title="${escapeText(senderAddr)}">${isFlagged ? "Unflag" : "Flag"} sender</button>` +
+                    (senderDomain ? `<button id="btn-flag-domain" class="mv-rb-flag-btn" title="*@${escapeText(senderDomain)}">Flag domain *@${escapeText(senderDomain)}</button>` : "") +
+                    `</div>` +
                     `<div class="mv-rb-actions"><button id="btn-edit-allowlist" title="View / edit the full allowlist">Edit allowlist…</button></div>` +
                     `</div>`;
             bodyEl.appendChild(banner);
@@ -609,6 +627,35 @@ export async function showMessage(accountId, uid, folderId, specialUse, isRetry
                 await allowRemoteContent("recipient", addr);
                 loadRemote();
             });
+            // Flag (or unflag) sender / domain — toggles the allowlist's
+            // flaggedSenders / flaggedDomains lists. Subsequent messages
+            // from this sender or domain show a red FLAGGED warning at the
+            // top of this banner. Doesn't load remote content; this is a
+            // signal-to-the-user feature, orthogonal to allow/block.
+            const onFlagToggle = async (type, value) => {
+                if (!value)
+                    return;
+                try {
+                    const result = await flagSenderOrDomain(type, value);
+                    const status = document.getElementById("status-sync");
+                    if (status)
+                        status.textContent = result.flagged
+                            ? `Flagged ${type}: ${value}`
+                            : `Unflagged ${type}: ${value}`;
+                    // Re-render this message so the banner picks up the new
+                    // flagged state without the user having to reselect.
+                    if (currentMessage) {
+                        showMessage(currentAccountId, currentMessage.uid, currentMessage.folderId, specialUse).catch(() => { });
+                    }
+                }
+                catch (e) {
+                    const status = document.getElementById("status-sync");
+                    if (status)
+                        status.textContent = `Flag failed: ${e?.message || e}`;
+                }
+            };
+            banner.querySelector("#btn-flag-sender")?.addEventListener("click", () => onFlagToggle("sender", senderAddr));
+            banner.querySelector("#btn-flag-domain")?.addEventListener("click", () => onFlagToggle("domain", senderDomain));
             // "Edit allowlist…" — fires a document-level event that app.ts
             // listens for and opens the JSONC editor pre-selected to
             // allowlist.jsonc. Keeps message-viewer free of the editor import.

package/client/compose/compose.html

@@ -42,6 +42,7 @@
         <button class="tb-btn" id="btn-send">Send</button>
         <button class="tb-btn" id="btn-attach">Attach</button>
         <input type="file" id="compose-file" multiple hidden>
+        <button class="tb-btn" id="btn-edit-in-word" title="Open the body in Microsoft Word — saves in Word reload back into the editor">Edit in Word</button>
         <button class="tb-btn" id="btn-discard">Discard</button>
         <span id="compose-status" class="compose-status"></span>
     </div>

package/client/compose/compose.js

@@ -4,7 +4,7 @@
  * Receives init data via window.opener.postMessage or URL params.
  */
 import { createEditor } from "./editor.js";
-import { getSettings, getAccounts, searchContacts, saveDraft as apiSaveDraft, deleteDraft, logClientEvent, addPreferredContact, addToDenylist } from "../lib/api-client.js";
+import { getSettings, getAccounts, searchContacts, saveDraft as apiSaveDraft, deleteDraft, logClientEvent, addPreferredContact, addToDenylist, openInWord, closeWordEdit, onEvent } from "../lib/api-client.js";
 import { showContextMenu } from "../components/context-menu.js";
 // Very first line the iframe runs — if this doesn't reach Node, the iframe
 // itself isn't loading or the bridge is completely broken.
@@ -1076,6 +1076,54 @@ document.getElementById("btn-attach")?.addEventListener("click", () => {
     attachJustClicked = Date.now();
     fileInput?.click();
 });
+// ── Edit in Word (external editor handoff) ──
+//
+// Click writes the current body to a temp file, opens it in Word (or the
+// platform fallback), and watches the file. When Word saves, the service
+// emits `wordEditUpdated` and we replace the editor's HTML with the new
+// content. The editId is per-compose-window — closeWordEdit cleans up the
+// temp file when the window closes or the message is sent.
+let wordEditId = null;
+document.getElementById("btn-edit-in-word")?.addEventListener("click", async () => {
+    if (!wordEditId)
+        wordEditId = `compose-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    showDraftStatus("Opening in Word…", false);
+    try {
+        const result = await openInWord(wordEditId, editor.getHtml());
+        if (!result.ok || result.opener === "none") {
+            showDraftStatus("Couldn't launch an editor. Install Word, LibreOffice, or set a default for .html.", true);
+            return;
+        }
+        const label = result.opener === "word" ? "Word" :
+            result.opener === "libreoffice" ? "LibreOffice" :
+                "your default editor";
+        showDraftStatus(`Editing in ${label} — saves there will reload here.`, false);
+    }
+    catch (e) {
+        showDraftStatus(`Edit-in-Word failed: ${e?.message || e}`, true);
+    }
+});
+// Listen for external-editor saves. Only react to events for this compose's
+// editId — multiple compose windows can be open and should not stomp each
+// other's bodies.
+onEvent((ev) => {
+    if (ev?.type !== "wordEditUpdated")
+        return;
+    if (!wordEditId || ev.editId !== wordEditId)
+        return;
+    try {
+        editor.setHtml(ev.html || "");
+        showDraftStatus("Reloaded edits from external editor.", false);
+        scheduleDraftSave();
+    }
+    catch (e) {
+        showDraftStatus(`Reload failed: ${e?.message || e}`, true);
+    }
+});
+window.addEventListener("beforeunload", () => {
+    if (wordEditId)
+        closeWordEdit(wordEditId).catch(() => { });
+});
 async function ingestFiles(files) {
     for (const file of Array.from(files)) {
         const buf = await file.arrayBuffer();

package/client/index.html

@@ -47,9 +47,15 @@
                     <label class="tb-menu-item"><input type="radio" name="opt-editor" value="quill" id="opt-editor-quill" checked> Quill</label>
                     <label class="tb-menu-item"><input type="radio" name="opt-editor" value="tiptap" id="opt-editor-tiptap"> tiptap</label>
                     <hr class="tb-menu-sep">
+                    <span class="tb-menu-label" title="Which app the compose 'Edit in Word' button hands the body off to. Auto = Word first, then LibreOffice, then OS default.">External editor</span>
+                    <label class="tb-menu-item"><input type="radio" name="opt-extedit" value="auto" id="opt-extedit-auto" checked> Auto (Word → LibreOffice → default)</label>
+                    <label class="tb-menu-item"><input type="radio" name="opt-extedit" value="word" id="opt-extedit-word"> Microsoft Word</label>
+                    <label class="tb-menu-item"><input type="radio" name="opt-extedit" value="libreoffice" id="opt-extedit-libre"> LibreOffice Writer</label>
+                    <hr class="tb-menu-sep">
                     <label class="tb-menu-item" title="Ghost-text completions while composing — Ollama / Claude / OpenAI back-end, off by default"><input type="checkbox" id="opt-autocomplete"> AI autocomplete</label>
                     <label class="tb-menu-item" title="Right-click in message body → Translate"><input type="checkbox" id="opt-ai-translate"> AI translate (off by default)</label>
                     <label class="tb-menu-item" title="Right-click in compose editor → Proofread (when wired)"><input type="checkbox" id="opt-ai-proofread"> AI proofread (off by default)</label>
+                    <label class="tb-menu-item" title="When opening a message with remote content, look up the sender's domain in Spamhaus DBL. Domain leaks to Spamhaus's DNS. Off by default."><input type="checkbox" id="opt-check-reputation"> Check sender reputation (Spamhaus DBL)</label>
                     <hr class="tb-menu-sep">
                     <button class="tb-menu-item" id="btn-edit-jsonc" title="Edit accounts.jsonc / allowlist.jsonc">Edit config files...</button>
                     <button class="tb-menu-item" id="btn-open-mailx-dir" title="Open ~/.mailx in file explorer">Open mailx folder...</button>

package/client/lib/api-client.js

@@ -218,6 +218,9 @@ export function openLocalPath(which) {
 export function allowRemoteContent(type, value) {
     return ipc().allowRemoteContent(type, value);
 }
+export function flagSenderOrDomain(type, value) {
+    return ipc().flagSenderOrDomain?.(type, value) ?? Promise.resolve({ flagged: false });
+}
 export function deleteMessage(accountId, uid) {
     return ipc().deleteMessage?.(accountId, uid);
 }
@@ -348,6 +351,12 @@ export function readConfigHelp(name) {
 export function unsubscribeOneClick(url) {
     return ipc().unsubscribeOneClick?.(url);
 }
+export function openInWord(editId, html) {
+    return ipc().openInWord?.(editId, html) ?? Promise.resolve({ ok: false, path: "", opener: "none" });
+}
+export function closeWordEdit(editId) {
+    return ipc().closeWordEdit?.(editId) ?? Promise.resolve();
+}
 /** Run an AI text transform (translate / proofread / summarize). Returns
  *  empty `text` with a `reason` when the feature is disabled or the provider
  *  errors — caller should surface `reason` in a status bar, not throw. */

package/client/lib/mailxapi.js

@@ -140,6 +140,12 @@
         unsubscribeOneClick: function(url) {
             return callNode("unsubscribeOneClick", { url: url });
         },
+        openInWord: function(editId, html) {
+            return callNode("openInWord", { editId: editId, html: html });
+        },
+        closeWordEdit: function(editId) {
+            return callNode("closeWordEdit", { editId: editId });
+        },
         aiTransform: function(req) {
             return callNode("aiTransform", req);
         },
@@ -265,6 +271,9 @@
         allowRemoteContent: function(type, value) {
             return callNode("allowRemoteContent", { type: type, value: value });
         },
+        flagSenderOrDomain: function(type, value) {
+            return callNode("flagSenderOrDomain", { type: type, value: value });
+        },
         getSettings: function() { return callNode("getSettings"); },
         saveSettingsData: function(data) { return callNode("saveSettingsData", data); },
         getVersion: function() { return callNode("getVersion"); },

package/client/styles/components.css

@@ -1525,6 +1525,29 @@ body.calendar-sidebar-on .calendar-sidebar { display: flex; }
     font-weight: 600;
 }
 
+/* Flagged sender or domain — red strip above the normal banner. */
+.mv-rb-flagged {
+    background: oklch(0.42 0.20 25);
+    color: white;
+    padding: var(--gap-xs) var(--gap-md);
+    font-weight: 700;
+    letter-spacing: 0.02em;
+}
+.mv-remote-banner-flagged { box-shadow: inset 0 0 0 2px oklch(0.55 0.22 25); }
+.mv-rb-flag-btn { background: oklch(0.42 0.20 25); }
+
+/* External reputation hit (Spamhaus DBL etc) — orange strip, distinct from
+   the user's manual red flag. Renders below the user-flag strip when both
+   are present so the precedence is visible. */
+.mv-rb-reputation {
+    background: oklch(0.55 0.18 50);
+    color: white;
+    padding: var(--gap-xs) var(--gap-md);
+    font-weight: 600;
+    letter-spacing: 0.02em;
+}
+.mv-remote-banner-reputation { box-shadow: inset 0 0 0 2px oklch(0.65 0.20 50); }
+
 .mv-rb-summary {
     display: flex;
     align-items: center;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx",
-  "version": "1.0.437",
+  "version": "1.0.439",
   "description": "Local-first email client with IMAP sync and standalone native app",
   "type": "module",
   "main": "bin/mailx.js",
@@ -36,7 +36,7 @@
     "@bobfrankston/iflow-node": "^0.1.8",
     "@bobfrankston/miscinfo": "^1.0.10",
     "@bobfrankston/oauthsupport": "^1.0.25",
-    "@bobfrankston/msger": "^0.1.362",
+    "@bobfrankston/msger": "^0.1.363",
     "@bobfrankston/mailx-host": "^0.1.8",
     "@capacitor/android": "^8.3.0",
     "@capacitor/cli": "^8.3.0",
@@ -100,7 +100,7 @@
       "@bobfrankston/iflow-node": "^0.1.8",
       "@bobfrankston/miscinfo": "^1.0.10",
       "@bobfrankston/oauthsupport": "^1.0.25",
-      "@bobfrankston/msger": "^0.1.362",
+      "@bobfrankston/msger": "^0.1.363",
       "@bobfrankston/mailx-host": "^0.1.8",
       "@capacitor/android": "^8.3.0",
       "@capacitor/cli": "^8.3.0",

package/packages/mailx-imap/index.d.ts

@@ -69,8 +69,6 @@ export declare class ImapManager extends EventEmitter {
     private inboxSyncing;
     /** Use native IMAP client instead of imapflow. Set to true to enable. */
     useNativeClient: boolean;
-    /** Accounts hitting connection limits — back off until this time */
-    private connectionBackoff;
     /** Per-account health counters. Incremented when the server misbehaves
      *  in ways that suggest a problem the user should know about (inactivity
      *  timeouts, connection-cap hits, rate-limit waits). Surfaced via a
@@ -100,50 +98,82 @@ export declare class ImapManager extends EventEmitter {
     searchOnServer(accountId: string, mailboxPath: string, criteria: any): Promise<number[]>;
     /** Server-side search that also materializes any UIDs we don't yet have
      *  locally. Returns the full result after upsert, so the caller can
-     *  render hits that fall outside the history window. */
+     *  render hits that fall outside the history window. The fetch loop
+     *  can be long for big hit-sets, so this runs on the slow lane and
+     *  yields between chunks (each chunk is a separate withConnection)
+     *  so an interactive body fetch can interleave. */
     searchAndFetchOnServer(accountId: string, folderId: number, mailboxPath: string, criteria: any): Promise<number[]>;
     /** Create a fresh IMAP client for an account (public access for API endpoints) */
-    createPublicClient(accountId: string): any;
-    /** Persistent operational connections — one per account, reused for all operations */
+    createPublicClient(accountId: string): Promise<any>;
+    /** Persistent operational connections — one per account, reused for all operations.
+     *  Body fetch, sync, prefetch, outbox-append, flag/move all serialize through
+     *  this single client per account via withConnection(). The priority lane
+     *  in the queue lets interactive clicks jump ahead of background prefetch. */
     private opsClients;
-    /** Operation queues — ensures sequential access per account */
+    /** Two-lane operation queue per account — interactive ops (body fetch on
+     *  click, flag toggle) drain before background ops (sync, prefetch). FIFO
+     *  within each lane. The single ops connection means there's never a race
+     *  on which folder is SELECTed; commands run strictly sequentially. */
     private opsQueues;
-    /** Persistent body-fetch connections — separate from ops so on-demand
-     *  body reads never queue behind a slow sync operation (bobma's IMAP
-     *  SEARCH can sit idle for 300s during backfill). */
-    private bodyClients;
-    /** Per-account backoff after the IMAP server rejected a connection with
-     *  the per-user+IP cap (Dovecot mail_max_userip_connections). Subsequent
-     *  body fetches short-circuit until the timestamp passes. */
-    private bodyBackoff;
+    /** Per-host semaphore — caps simultaneous IMAP socket opens to one server.
+     *  Defensive guardrail: with the single-ops-per-account model an individual
+     *  user's mailx never hits more than (#accounts × 2) sockets per host, well
+     *  under any reasonable server cap. Exists for the multi-account-on-one-host
+     *  case (e.g. bobma + bobma2 both on imap.iecc.com). */
+    private hostSemaphores;
+    private static readonly HOST_PERMITS;
     /** Get (or create) the persistent operational connection for an account.
      *  logout() is wrapped as a no-op so legacy callers don't close it. */
     private getOpsClient;
     /** Run an operation on the account's connection — queued, sequential, no concurrency */
-    withConnection<T>(accountId: string, fn: (client: any) => Promise<T>): Promise<T>;
+    /** Run an operation against the account's single ops connection. Tasks
+     *  queue strictly sequentially per account — only one IMAP command in
+     *  flight at a time. This eliminates the SELECT-races and "stale client
+     *  recovery" paths the old multi-client design needed.
+     *
+     *  Default lane is `fast` — covers virtually everything (body fetch,
+     *  flag toggle, move, incremental sync). Pass `slow: true` only for
+     *  operations the caller knows will take a long time and shouldn't
+     *  block the user (multi-folder prefetch batches, large backfills).
+     *  When both lanes have tasks, fast drains first.
+     *
+     *  Within a lane, FIFO. The running task always finishes — IMAP can't
+     *  preempt a command mid-flight. */
+    withConnection<T>(accountId: string, fn: (client: any) => Promise<T>, opts?: {
+        slow?: boolean;
+    }): Promise<T>;
+    /** Run the next queued task. Fast lane drains before slow.
+     *  Idempotent — safe to call after each task completes; the running
+     *  flag prevents reentrant draining. */
+    private drainOpsQueue;
+    /** Acquire one slot of the per-host connection semaphore. Returns a release
+     *  function — call exactly once when the socket is closed. Used by
+     *  newClient to cap simultaneous IMAP connections to a single server
+     *  across all mailx accounts. */
+    private acquireHostSlot;
     /** Open IMAP clients per account, used to trace who's opening sockets
      *  when we hit the Dovecot per-user+IP connection cap. */
     private openClients;
     /** Create a new IMAP client (internal — callers use getOpsClient or withConnection).
-     *  `purpose` is a short tag printed alongside the `[conn+]` log so we can tell
-     *  which code path (sync/idle/body/outbox/move/…) opened each connection. */
+     *  Acquires one slot of the per-host semaphore before constructing the
+     *  client; the slot is released when logout() or destroy() runs.
+     *  `purpose` is a short tag printed alongside the `[conn+]` log so we can
+     *  tell which code path (ops/idle/etc.) opened each connection. */
     private newClient;
-    /** Get (or lazily create) the persistent body-fetch client. Separate from
-     *  the ops client so body reads never wait on a slow sync command. */
-    private getBodyClient;
-    /** Drop the body-fetch connection (e.g. after a socket error). */
-    private dropBodyClient;
-    /** Force-close every pooled client for an account — ops, body, any
-     *  lingering ones in openClients. Used when the server reports its
-     *  connection cap is hit so our slot count drops to zero on the
-     *  server side before backoff expires. */
+    /** Force-close every IMAP socket for an account — ops + any lingering
+     *  ones in openClients (e.g. an IDLE watcher in flight). Used during
+     *  account removal and disconnectOps so the server's connection slots
+     *  free immediately rather than waiting for socket idle timeouts. */
     closeAllClients(accountId: string): Promise<void>;
     /** Disconnect the persistent operational connection for an account */
     disconnectOps(accountId: string): Promise<void>;
-    /** Legacy API — callers that still create/destroy connections.
-     *  These return the persistent ops client. logout() is a no-op
-     *  (the connection stays alive for reuse). */
+    /** Legacy entry: returns the shared persistent ops client. Most callers
+     *  should be using `withConnection()` instead — that gives proper
+     *  queueing and lets fast operations jump ahead of slow ones. */
     createClientWithLimit(accountId: string): Promise<any>;
+    /** Disposable fresh client — only used by the IDLE watcher, which holds
+     *  its own socket so the fast/slow ops queue isn't blocked by IDLE
+     *  parking the connection in a wait-for-server state. */
     private createClient;
     private trackLogout;
     /** Number of registered IMAP accounts */
@@ -175,7 +205,12 @@ export declare class ImapManager extends EventEmitter {
     private storeApiMessages;
     /** Kill and recreate the persistent ops connection */
     private reconnectOps;
-    /** Handle sync errors — classify and emit appropriate UI events */
+    /** Handle sync errors — classify and emit appropriate UI events.
+     *  The connection-cap branch was removed: with the unified ops queue +
+     *  per-host semaphore, mailx alone can't exceed the server cap. If the
+     *  cap *is* hit, that means another client (Thunderbird, phone, sibling
+     *  process) is holding slots — punishing mailx with a multi-minute
+     *  blackout doesn't help the user, the next sync tick will retry. */
     private handleSyncError;
     /** Fetch ONLY new messages above highestUid for one account's INBOX —
      *  the IDLE callback's hot path. Skips gap detection, backfill, and the
@@ -211,17 +246,21 @@ export declare class ImapManager extends EventEmitter {
     startWatching(): Promise<void>;
     /** Stop all IDLE watchers */
     stopWatching(): Promise<void>;
-    /** Per-account fetch queue — serializes body fetches so only one IMAP command runs at a time.
-     *  The persistent fetchClient can only handle one command at a time (IMAP protocol limitation). */
-    private fetchQueues;
-    /** Serialize body fetch operations per account — prevents concurrent IMAP commands on same connection */
     /** Unlink the on-disk body file for a message by reading its `body_path`
      *  from the DB. Safe to call either before or after `db.deleteMessage`
      *  — read body_path first, store it, then unlink whenever. */
     private unlinkBodyFile;
-    private enqueueFetch;
     /** Fetch a single message body on demand, caching in the store.
-     *  Uses its own fresh connection — never blocked by background prefetch. */
+     *
+     *  Cache lookup is folder-agnostic: when a UID exists in multiple folders
+     *  (Gmail labels, copy-instead-of-move) the prefetcher may have populated
+     *  body_path on only one row. Looking up by (account, uid) without the
+     *  folder filter finds the cached `.eml` regardless of which folder
+     *  context the UI passed.
+     *
+     *  Server fetch goes through the unified ops queue on the fast lane —
+     *  the user clicked, they're waiting, this jumps ahead of any background
+     *  prefetch sitting in the slow lane. */
     fetchMessageBody(accountId: string, folderId: number, uid: number): Promise<Buffer | null>;
     /** Fetch message body via Gmail/Outlook API.
      *  Throws `MessageNotFoundError` when the server says the message is gone
@@ -360,7 +399,10 @@ export declare class ImapManager extends EventEmitter {
      *  Uses @bobfrankston/smtp-direct with the same TransportFactory as IMAP —
      *  same TCP byte-stream interface, no nodemailer dependency. */
     private sendRawViaSMTP;
-    /** Process Outbox — send pending messages with flag-based interlock */
+    /** Process Outbox — send pending messages with flag-based interlock.
+     *  Each per-UID step is its own withConnection({slow}) call so the queue
+     *  yields between messages: a click-to-view body in the middle of a
+     *  10-message outbox drain doesn't wait for all 10 to finish. */
     processOutbox(accountId: string): Promise<void>;
     /** Start background Outbox worker — runs immediately then every 10 seconds */
     private outboxBackoff;