@bobfrankston/mailx 1.0.451 → 1.0.452

package/packages/mailx-service/index.ts

@@ -0,0 +1,2461 @@
+/**
+ * @bobfrankston/mailx-service
+ * Pure business logic — no HTTP, no Express.
+ * Both the Express API (mailx-api) and the Android bridge call these functions.
+ */
+
+import * as dns from "node:dns/promises";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { MailxDB } from "@bobfrankston/mailx-store";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+import { ImapManager } from "@bobfrankston/mailx-imap";
+import * as gsync from "./google-sync.js";
+import { loadSettings, saveSettings, loadAccounts, loadAccountsAsync, saveAccounts, initCloudConfig, loadAllowlist, saveAllowlist, loadAutocomplete, saveAutocomplete, getStorePath, getStorageInfo, getConfigDir } from "@bobfrankston/mailx-settings";
+import type { AccountConfig, Folder, AutocompleteRequest, AutocompleteResponse, AutocompleteSettings, AiTransformRequest, AiTransformResponse } from "@bobfrankston/mailx-types";
+import { sanitizeHtml, encodeQuotedPrintable, htmlToPlainText } from "@bobfrankston/mailx-types";
+import { simpleParser } from "mailparser";
+
+/** Parse `List-Unsubscribe` (RFC 2369) and `List-Unsubscribe-Post` (RFC 8058).
+ *  mailparser only exposes ONE of mail/url even when both are present, so we
+ *  also scan the raw header text for the full set of angle-bracketed URIs. */
+function parseListUnsubscribe(headers: any): { listUnsubscribeMail: string; listUnsubscribeHttp: string; listUnsubscribeOneClick: boolean } {
+    let mail = "";
+    let http = "";
+    let oneClick = false;
+
+    const raw = headers.get("list-unsubscribe");
+    const rawStr = typeof raw === "string" ? raw : (raw && typeof (raw as any).text === "string" ? (raw as any).text : "");
+    if (rawStr) {
+        const matches = rawStr.match(/<([^>]+)>/g) || [];
+        for (const m of matches) {
+            const url = m.slice(1, -1).trim();
+            if (!mail && /^mailto:/i.test(url)) mail = url;
+            else if (!http && /^https?:/i.test(url)) http = url;
+        }
+    }
+    if (!mail && !http) {
+        const listHeaders = headers.get("list");
+        if (listHeaders?.unsubscribe) {
+            const unsub = listHeaders.unsubscribe;
+            if (unsub.url) http = Array.isArray(unsub.url) ? unsub.url[0] : unsub.url;
+            if (unsub.mail) mail = `mailto:${Array.isArray(unsub.mail) ? unsub.mail[0] : unsub.mail}`;
+        }
+    }
+
+    const post = headers.get("list-unsubscribe-post");
+    const postStr = typeof post === "string" ? post : (post && typeof (post as any).text === "string" ? (post as any).text : "");
+    if (postStr && /one-?click/i.test(postStr)) oneClick = true;
+
+    return { listUnsubscribeMail: mail, listUnsubscribeHttp: http, listUnsubscribeOneClick: oneClick };
+}
+
+// ── Email provider detection (MX-based) ──
+
+const GOOGLE_DOMAINS = ["gmail.com", "googlemail.com"];
+const MS_DOMAINS = ["outlook.com", "hotmail.com", "live.com"];
+
+async function detectEmailProvider(domain: string): Promise<{ cloud?: "gdrive"; imapHost: string; smtpHost: string; auth: "oauth2" } | null> {
+    if (GOOGLE_DOMAINS.includes(domain)) return { cloud: "gdrive", imapHost: "imap.gmail.com", smtpHost: "smtp.gmail.com", auth: "oauth2" };
+    if (MS_DOMAINS.includes(domain)) return { imapHost: "outlook.office365.com", smtpHost: "smtp.office365.com", auth: "oauth2" };
+    try {
+        const records = await dns.resolveMx(domain);
+        for (const mx of records) {
+            const host = mx.exchange.toLowerCase();
+            if (host.endsWith(".google.com") || host.endsWith(".googlemail.com")) {
+                return { cloud: "gdrive", imapHost: "imap.gmail.com", smtpHost: "smtp.gmail.com", auth: "oauth2" };
+            }
+            if (host.endsWith(".outlook.com") || host.endsWith(".protection.outlook.com")) {
+                return { imapHost: "outlook.office365.com", smtpHost: "smtp.office365.com", auth: "oauth2" };
+            }
+        }
+    } catch { /* DNS lookup failed */ }
+    return null;
+}
+
+// sanitizeHtml and encodeQuotedPrintable imported from @bobfrankston/mailx-types (shared with Android)
+
+/** Compare a local task row to an incoming Google task projection. Used by
+ *  refreshTasks to skip no-op upserts that would otherwise emit `tasksUpdated`
+ *  on every poll, feeding back into the UI's getTasks-on-event listener and
+ *  burning the daily Google Tasks API quota. */
+function taskRowEquals(prior: any, fresh: any): boolean {
+    return prior.providerId === fresh.providerId
+        && prior.title === fresh.title
+        && (prior.notes || "") === (fresh.notes || "")
+        && (prior.dueMs ?? null) === (fresh.dueMs ?? null)
+        && (prior.completedMs ?? null) === (fresh.completedMs ?? null)
+        && (prior.etag || "") === (fresh.etag || "");
+}
+
+/** Same shape as taskRowEquals — compares the calendar-event fields the
+ *  Google projection actually carries, ignoring derived/local-only columns. */
+function calendarRowEquals(prior: any, fresh: any): boolean {
+    return prior.providerId === fresh.providerId
+        && prior.title === fresh.title
+        && prior.startMs === fresh.startMs
+        && prior.endMs === fresh.endMs
+        && !!prior.allDay === !!fresh.allDay
+        && (prior.location || "") === (fresh.location || "")
+        && (prior.notes || "") === (fresh.notes || "")
+        && (prior.etag || "") === (fresh.etag || "")
+        && (prior.recurringEventId || null) === (fresh.recurringEventId || null)
+        && (prior.htmlLink || null) === (fresh.htmlLink || null);
+}
+
+interface ReputationResult {
+    flagged: boolean;
+    listedCount: number;
+    checkedCount: number;
+    sources: Array<{ service: string; flagged: boolean; verdict: string }>;
+    verdict: string;
+    service: string;
+}
+
+// ── Service ──
+
+export class MailxService {
+    // Cached accounts — loadSettings() reads from the cloud-mounted
+    // accounts.jsonc, which can stall on a flaky GDrive File Stream.
+    // Refresh on configChanged (fs.watch) so edits still land.
+    private _accountsCache: AccountConfig[] | null = null;
+
+    constructor(
+        private db: MailxDB,
+        private imapManager: ImapManager,
+    ) {
+        // Invalidate account cache when accounts.jsonc changes on disk or GDrive.
+        this.imapManager.on?.("configChanged", (filename: string) => {
+            if (filename === "accounts.jsonc") this._accountsCache = null;
+            if (filename === "contacts.jsonc") {
+                this.loadContactsConfig().catch(e =>
+                    console.error(`  [contacts] reload failed: ${e?.message || e}`));
+            }
+        });
+        // Wire DB → cloud flush. Debounced to absorb bursts (a sync run can
+        // call recordSentAddress hundreds of times). 30s flush window is
+        // long enough that the steady state is one cloud write per sync,
+        // short enough that quitting after a single send still flushes.
+        this.db.setOnContactsChanged(() => this.markContactsDirty());
+
+        // Initial load of contacts.jsonc — fire-and-forget; missing file is fine.
+        this.loadContactsConfig().catch(() => { /* file may not exist yet */ });
+    }
+
+    private _contactsFlushTimer: ReturnType<typeof setTimeout> | null = null;
+    private _contactsFlushInFlight = false;
+    private readonly CONTACTS_FLUSH_DEBOUNCE_MS = 30_000;
+    /** Schedule a debounced flush of the local contacts state to GDrive.
+     *  Multiple changes within the debounce window collapse to one write. */
+    markContactsDirty(): void {
+        if (this._contactsFlushTimer) clearTimeout(this._contactsFlushTimer);
+        this._contactsFlushTimer = setTimeout(() => {
+            this._contactsFlushTimer = null;
+            this.flushContactsConfig().catch(e =>
+                console.error(`  [contacts] flush failed: ${e?.message || e}`));
+        }, this.CONTACTS_FLUSH_DEBOUNCE_MS);
+    }
+
+    /** Write current DB contacts state to GDrive contacts.jsonc. Called via
+     *  the debounced timer; also exposed for force-flush on shutdown or
+     *  after a manual seed. Idempotent — safe to call multiple times. */
+    async flushContactsConfig(): Promise<void> {
+        if (this._contactsFlushInFlight) return;
+        this._contactsFlushInFlight = true;
+        try {
+            const cfg = this.db.exportContactsConfig();
+            const { cloudWrite } = await import("@bobfrankston/mailx-settings");
+            await cloudWrite("contacts.jsonc", JSON.stringify(cfg, null, 2));
+            console.log(`  [contacts] flushed to cloud: ${cfg.preferred.length} preferred + ${cfg.discovered.length} discovered + ${cfg.denylist.length} denylisted`);
+        } finally {
+            this._contactsFlushInFlight = false;
+        }
+    }
+
+    /** Read contacts.jsonc from cloud + apply (preferred + denylist + discovered)
+     *  into the DB. On first run with no file, seed from message corpus and
+     *  write a fresh contacts.jsonc to GDrive — that auto-bootstrap is what
+     *  makes a new device useful immediately on a shared GDrive setup. */
+    async loadContactsConfig(): Promise<{ preferred: number; discovered: number; purged: number; conflicts: string[] } | null> {
+        let raw: string | null = null;
+        let cloudAvailable = false;
+        try {
+            const { cloudRead } = await import("@bobfrankston/mailx-settings");
+            raw = await cloudRead("contacts.jsonc");
+            cloudAvailable = true;
+        } catch { /* cloud unavailable */ }
+
+        if (!raw) {
+            // No file (yet). Reset in-memory denylist and seed discovered
+            // from the local message corpus so autocomplete works immediately.
+            this.db.applyContactsConfig({ preferred: [], denylist: [], discovered: [] });
+            try { this.db.seedContactsFromMessages(); } catch { /* corpus may be empty */ }
+            // Auto-bootstrap GDrive copy if cloud is reachable. The file gets
+            // a header comment so a user opening it on Drive sees what it is.
+            if (cloudAvailable) {
+                try {
+                    await this.flushContactsConfig();
+                    console.log("  [contacts] auto-seeded contacts.jsonc on GDrive from local corpus");
+                } catch (e: any) {
+                    console.error(`  [contacts] auto-seed flush failed: ${e?.message || e}`);
+                }
+            }
+            return null;
+        }
+
+        const { parse: parseJsonc } = await import("jsonc-parser");
+        const errors: any[] = [];
+        const cfg = parseJsonc(raw, errors, { allowTrailingComma: true });
+        if (errors.length) {
+            console.error(`  [contacts] contacts.jsonc has parse errors — applying empty config: ${errors.map((e: any) => e.error).join(", ")}`);
+            this.db.applyContactsConfig({ preferred: [], denylist: [], discovered: [] });
+            return null;
+        }
+        const result = this.db.applyContactsConfig(cfg || {});
+        // Run local seeder in case this device has corpus addresses the cloud
+        // copy doesn't know about yet. The seeder will fire notifyContactsChanged
+        // if it adds anything, which schedules a flush back to GDrive.
+        try { this.db.seedContactsFromMessages(); } catch { /* corpus may be empty */ }
+        return result;
+    }
+
+    /** Append an entry to contacts.jsonc#preferred[] and write back to cloud,
+     *  then re-apply. Mutates the file in place — preserves existing entries
+     *  and the user's hand-formatting where the parser permits. */
+    async addPreferredContact(entry: { name: string; email: string; source?: string; organization?: string }): Promise<void> {
+        const { cloudRead, cloudWrite } = await import("@bobfrankston/mailx-settings");
+        const { parse: parseJsonc } = await import("jsonc-parser");
+        let cfg: any = {};
+        const raw = await cloudRead("contacts.jsonc");
+        if (raw) {
+            try { cfg = parseJsonc(raw, [], { allowTrailingComma: true }) || {}; } catch { cfg = {}; }
+        }
+        if (!Array.isArray(cfg.preferred)) cfg.preferred = [];
+        // Dedup: skip if an entry with the same email + name + source already exists.
+        const dupKey = `${(entry.source || "preferred").toLowerCase()}|${entry.email.toLowerCase()}|${(entry.name || "").toLowerCase()}`;
+        const exists = cfg.preferred.some((e: any) =>
+            `${(e?.source || "preferred").toLowerCase()}|${(e?.email || "").toLowerCase()}|${(e?.name || "").toLowerCase()}` === dupKey);
+        if (!exists) {
+            const row: any = { name: entry.name || "", email: entry.email };
+            if (entry.source) row.source = entry.source;
+            if (entry.organization) row.organization = entry.organization;
+            cfg.preferred.push(row);
+        }
+        await cloudWrite("contacts.jsonc", JSON.stringify(cfg, null, 2));
+        await this.loadContactsConfig();
+    }
+
+    /** Append an email to contacts.jsonc#denylist[] and write back to cloud,
+     *  then re-apply (which purges any matching discovered rows). */
+    async addToDenylist(email: string): Promise<void> {
+        const lower = (email || "").trim().toLowerCase();
+        if (!lower) return;
+        const { cloudRead, cloudWrite } = await import("@bobfrankston/mailx-settings");
+        const { parse: parseJsonc } = await import("jsonc-parser");
+        let cfg: any = {};
+        const raw = await cloudRead("contacts.jsonc");
+        if (raw) {
+            try { cfg = parseJsonc(raw, [], { allowTrailingComma: true }) || {}; } catch { cfg = {}; }
+        }
+        if (!Array.isArray(cfg.denylist)) cfg.denylist = [];
+        if (!cfg.denylist.some((e: any) => (e || "").toLowerCase() === lower)) {
+            cfg.denylist.push(email);
+        }
+        await cloudWrite("contacts.jsonc", JSON.stringify(cfg, null, 2));
+        await this.loadContactsConfig();
+    }
+
+    /** Return accounts from cache — load once, reuse until configChanged. */
+    private getCachedAccounts(): AccountConfig[] {
+        if (!this._accountsCache) this._accountsCache = loadAccounts();
+        return this._accountsCache;
+    }
+
+    // ── Accounts ──
+
+    getAccounts(): any[] {
+        const dbAccounts = this.db.getAccounts();
+        const cfgs = this.getCachedAccounts();
+        // Order by settings (accounts.jsonc is the source of truth for order)
+        const ordered: any[] = [];
+        for (const cfg of cfgs) {
+            const a = dbAccounts.find(d => d.id === cfg.id);
+            if (a) ordered.push({
+                ...a, label: cfg.label, defaultSend: cfg.defaultSend || false,
+                primary: !!(cfg as any).primary,
+                primaryCalendar: !!(cfg as any).primaryCalendar,
+                primaryTasks: !!(cfg as any).primaryTasks,
+                primaryContacts: !!(cfg as any).primaryContacts,
+                identityDomains: (cfg as any).identityDomains || [],
+            });
+        }
+        // Append any DB accounts not in settings
+        for (const a of dbAccounts) {
+            if (!ordered.find((o: any) => o.id === a.id)) ordered.push(a);
+        }
+        return ordered;
+    }
+
+    // ── Folders ──
+
+    getFolders(accountId: string): Folder[] {
+        return this.db.getFolders(accountId);
+    }
+
+    // ── Messages ──
+
+    getUnifiedInbox(page = 1, pageSize = 50): any {
+        return this.db.getUnifiedInbox(page, pageSize);
+    }
+
+    getMessages(accountId: string, folderId: number, page = 1, pageSize = 50, sort = "date", sortDir = "desc", search?: string, flaggedOnly = false): any {
+        return this.db.getMessages({ accountId, folderId, page, pageSize, sort: sort as any, sortDir: sortDir as any, search, flaggedOnly });
+    }
+
+    async getMessage(accountId: string, uid: number, allowRemote = false, folderId?: number): Promise<any> {
+        const envelope = this.db.getMessageByUid(accountId, uid, folderId);
+        if (!envelope) throw new Error("Message not found");
+
+        let bodyHtml = "";
+        let bodyText = "";
+        let hasRemoteContent = false;
+        let attachments: { id: number; filename: string; mimeType: string; size: number; contentId: string }[] = [];
+
+        // The per-account ops queue inside ImapManager has its own per-task
+        // timeout that destroys a wedged client and unblocks the queue. This
+        // outer race is a safety net only — the underlying timeout in
+        // withConnection should trigger first.
+        const BODY_FETCH_TIMEOUT_MS = 60_000;
+        let raw: Buffer | null = null;
+        try {
+            raw = await Promise.race([
+                this.imapManager.fetchMessageBody(accountId, envelope.folderId, envelope.uid),
+                new Promise<never>((_, reject) =>
+                    setTimeout(() => reject(new Error("body fetch timed out — try again")), BODY_FETCH_TIMEOUT_MS)
+                ),
+            ]);
+        } catch (fetchErr: any) {
+            // Message was deleted from the server (another device, expunge, etc.) —
+            // drop the stale local row so the UI removes it instead of showing a
+            // confusing error. Throwing a tagged error lets the client react.
+            if ((fetchErr as any)?.isNotFound) {
+                try {
+                    this.db.deleteMessage(accountId, envelope.uid);
+                    this.db.recalcFolderCounts(envelope.folderId);
+                } catch { /* ignore */ }
+                const err = new Error("Message was deleted from the server");
+                (err as any).isNotFound = true;
+                throw err;
+            }
+            // Don't stuff the error text into bodyText — it bleeds into the
+            // viewer's main content area. Surface as a structured error field
+            // so the UI can render a banner with retry UX above the (empty)
+            // body. The caller keeps the envelope so the header still shows.
+            const rawErr = fetchErr.message || "connection failed";
+            const isTransient = /connection|Too many|UNAVAILABLE|rate|429|5\d\d|timeout|ENOTFOUND|ECONNRESET|ETIMEDOUT/i.test(rawErr);
+            return {
+                ...envelope, bodyHtml: "", bodyText: "",
+                bodyError: rawErr,
+                bodyErrorTransient: isTransient,
+                hasRemoteContent: false, remoteAllowed: false, attachments: [], emlPath: "", deliveredTo: "", returnPath: "", listUnsubscribe: ""
+            };
+        }
+
+        if (!raw) {
+            // Same treatment as the thrown-error case: structured field, not body text.
+            return {
+                ...envelope, bodyHtml: "", bodyText: "",
+                bodyError: "Message body not cached locally and the server fetch returned nothing.",
+                bodyErrorTransient: true,
+                hasRemoteContent: false, remoteAllowed: false, attachments: [], emlPath: "", deliveredTo: "", returnPath: "", listUnsubscribe: ""
+            };
+        } else {
+            const parsed = await simpleParser(raw);
+            bodyHtml = parsed.html || "";
+            bodyText = parsed.text || "";
+            attachments = (parsed.attachments || []).map((a, i) => ({
+                id: i,
+                filename: a.filename || `attachment-${i}`,
+                mimeType: a.contentType || "application/octet-stream",
+                size: a.size || 0,
+                contentId: a.contentId || ""
+            }));
+        }
+
+        // Sanitize HTML
+        if (bodyHtml && !allowRemote) {
+            const allowList = loadAllowlist();
+            const senderAddr = envelope.from?.address || "";
+            const senderDomain = senderAddr.split("@")[1] || "";
+            const toAddrs = (envelope.to || []).map((a: any) => a.address);
+            const isAllowed = allowList.senders.includes(senderAddr) ||
+                allowList.domains.includes(senderDomain) ||
+                toAddrs.some((a: string) => allowList.recipients?.includes(a));
+
+            if (isAllowed) {
+                allowRemote = true;
+            } else {
+                const result = sanitizeHtml(bodyHtml);
+                bodyHtml = result.html;
+                hasRemoteContent = result.hasRemoteContent;
+            }
+        }
+
+        // Extract headers
+        let deliveredTo = "";
+        let returnPath = "";
+        let listUnsubscribe = "";
+        let listUnsubscribeMail = "";
+        let listUnsubscribeHttp = "";
+        let listUnsubscribeOneClick = false;
+        if (raw) {
+            const parsed2 = await simpleParser(raw);
+            const hdr = (key: string): string => {
+                let v = parsed2.headers.get(key);
+                if (!v) return "";
+                if (Array.isArray(v)) v = v[0];
+                if (typeof v === "string") return v;
+                if (typeof v === "object" && v !== null) {
+                    if ("text" in v) return (v as any).text || "";
+                    if ("value" in v) return String((v as any).value);
+                    if ("address" in v) return (v as any).address || "";
+                }
+                return String(v);
+            };
+
+            const msgSettings = loadSettings();
+            const acctConfig = msgSettings.accounts.find((a: any) => a.id === accountId);
+            const relayDomains: string[] = acctConfig?.relayDomains || [];
+            const prefixes: string[] = acctConfig?.deliveredToPrefix || [];
+            const rawDelivered = parsed2.headers.get("delivered-to");
+            if (rawDelivered) {
+                const deliveredList = Array.isArray(rawDelivered) ? rawDelivered : [rawDelivered];
+                for (let i = deliveredList.length - 1; i >= 0; i--) {
+                    const d = deliveredList[i];
+                    const addr = typeof d === "string" ? d : (d as any)?.text || (d as any)?.address || String(d);
+                    if (!relayDomains.some(rd => addr.includes(`@${rd}`))) {
+                        deliveredTo = addr;
+                        break;
+                    }
+                }
+                if (!deliveredTo && deliveredList.length > 0) {
+                    const d = deliveredList[deliveredList.length - 1];
+                    deliveredTo = typeof d === "string" ? d : (d as any)?.text || (d as any)?.address || String(d);
+                }
+                if (deliveredTo && prefixes.length > 0) {
+                    const [local, domain] = deliveredTo.split("@");
+                    for (const prefix of prefixes) {
+                        if (local.startsWith(prefix)) {
+                            deliveredTo = `${local.slice(prefix.length)}@${domain}`;
+                            break;
+                        }
+                    }
+                }
+            }
+            returnPath = hdr("return-path").replace(/[<>]/g, "");
+            ({ listUnsubscribeMail, listUnsubscribeHttp, listUnsubscribeOneClick } =
+                parseListUnsubscribe(parsed2.headers));
+            listUnsubscribe = listUnsubscribeHttp || listUnsubscribeMail;
+        }
+
+        // EML path: re-read the row after the fetch — `fetchMessageBody`
+        // writes the body to disk and updates `body_path` on success, but the
+        // `envelope` snapshot above pre-dates that write, so trusting it
+        // hides the Source button on every just-opened message.
+        const refreshed: any = this.db.getMessageByUid(accountId, uid, folderId);
+        const emlPath = refreshed?.bodyPath || envelope.bodyPath || "";
+
+        // Flag check — surfaced in the remote-content banner as a red
+        // warning when the sender's address or domain is on the user's
+        // flagged list. Cheap lookup; loadAllowlist is already cached.
+        const allowList = loadAllowlist() as any;
+        const senderAddr = (envelope.from?.address || "").toLowerCase();
+        const senderDomain = senderAddr.split("@")[1] || "";
+        const isFlagged = !!(
+            (allowList.flaggedSenders || []).some((s: string) => (s || "").toLowerCase() === senderAddr) ||
+            (allowList.flaggedDomains || []).some((d: string) => (d || "").toLowerCase() === senderDomain)
+        );
+
+        // External reputation check — Spamhaus DBL + SURBL + URIBL in parallel.
+        // Off by default (privacy: the domain leaks to those DNSBLs and the
+        // user's local resolver). User opts in via Settings → "Check sender
+        // reputation". Each lookup is bounded at 500 ms; the whole check is
+        // bounded by the slowest, ~500 ms worst case.
+        let reputation: ReputationResult | null = null;
+        const settings = (loadSettings() as any) || {};
+        if (settings.checkDomainReputation && senderDomain && hasRemoteContent) {
+            reputation = await this.checkDomainReputation(senderDomain);
+        }
+
+        return {
+            ...envelope, bodyHtml, bodyText, hasRemoteContent, remoteAllowed: allowRemote,
+            attachments, emlPath, deliveredTo, returnPath,
+            listUnsubscribe, listUnsubscribeMail, listUnsubscribeHttp, listUnsubscribeOneClick,
+            isFlagged,
+            reputation,
+        };
+    }
+
+    /** RFC 8058 one-click unsubscribe: POST `List-Unsubscribe=One-Click` to the
+     *  HTTPS URL the message's List-Unsubscribe header advertised. Done server-
+     *  side because the unsubscribe endpoint usually doesn't set CORS headers,
+     *  so a browser-side fetch would be blocked. */
+    async unsubscribeOneClick(url: string): Promise<{ ok: boolean; status: number; statusText: string }> {
+        if (!/^https:\/\//i.test(url)) throw new Error("one-click unsubscribe requires an https URL");
+        // RFC 8058 POST with List-Unsubscribe=One-Click body. A User-Agent
+        // header appeases servers that reject anonymous clients as "malformed".
+        const headers: Record<string, string> = {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "User-Agent": "mailx/1.0 (https://github.com/BobFrankston/mailx)",
+        };
+        let resp = await fetch(url, {
+            method: "POST",
+            headers,
+            body: "List-Unsubscribe=One-Click",
+            redirect: "follow",
+        });
+        // Some mailers advertise List-Unsubscribe-Post but their endpoint
+        // actually only handles GET (older RFC 2369 style). Fall back once
+        // on 4xx so the user doesn't have to open the URL manually.
+        if (!resp.ok && resp.status >= 400 && resp.status < 500) {
+            const body = await resp.text().catch(() => "");
+            console.log(`  [unsub] POST ${url} → ${resp.status} ${resp.statusText}; body: ${body.slice(0, 200)}`);
+            try {
+                const fallback = await fetch(url, { method: "GET", headers, redirect: "follow" });
+                if (fallback.ok) {
+                    return { ok: true, status: fallback.status, statusText: `${fallback.statusText} (via GET)` };
+                }
+                const fbody = await fallback.text().catch(() => "");
+                console.log(`  [unsub] GET ${url} → ${fallback.status} ${fallback.statusText}; body: ${fbody.slice(0, 200)}`);
+                // Surface the server's own error so the UI shows the real reason.
+                return { ok: false, status: fallback.status, statusText: (fbody.trim().split("\n")[0] || fallback.statusText).slice(0, 200) };
+            } catch { /* fall through to POST error */ }
+            return { ok: false, status: resp.status, statusText: (body.trim().split("\n")[0] || resp.statusText).slice(0, 200) };
+        }
+        return { ok: resp.ok, status: resp.status, statusText: resp.statusText };
+    }
+
+    // ── External edit in Microsoft Word ──
+
+    /** Per-session map: editId → temp file path + watcher cleanup.
+     *  Lives in memory only — cleared when the user closes compose or sends. */
+    private wordEdits = new Map<string, { path: string; stop: () => void }>();
+
+    /** Hand the current compose body off to Microsoft Word for editing. Writes
+     *  the HTML to `~/.mailx/external-edit/<editId>.html`, opens it via the
+     *  default OS handler (Word on Windows when .html is associated; otherwise
+     *  the user's chosen editor for HTML), and starts an fs.watch that emits
+     *  `wordEditUpdated` when Word saves. The compose UI listens for that
+     *  event and reloads the editor.
+     *
+     *  Windows-only by current default — on Mac/Linux there's no equivalent
+     *  reliable round-trip. The compose toolbar should hide the button on
+     *  non-win32 platforms. */
+    async openInWord(editId: string, html: string): Promise<{ ok: boolean; path: string; opener: string }> {
+        const dir = path.join(getConfigDir(), "external-edit");
+        fs.mkdirSync(dir, { recursive: true });
+        const filePath = path.join(dir, `${editId}.html`);
+        // Wrap in a minimal HTML doc so Word picks up encoding + treats the
+        // body content as the document. Word imports the <body> contents and
+        // converts them to its own model; saving HTML preserves enough of
+        // the structure for re-import (paragraphs, links, basic formatting).
+        const wrapped = `<!doctype html>
+<html><head><meta charset="utf-8"><title>mailx draft</title></head>
+<body>${html || "<p></p>"}</body></html>
+`;
+        fs.writeFileSync(filePath, wrapped, "utf-8");
+
+        // Stop any existing watcher for this edit (re-open re-arms cleanly).
+        this.wordEdits.get(editId)?.stop();
+
+        // Try Word explicitly first; on failure (Word not installed, exec not
+        // in PATH) fall back to the OS default handler so the user still gets
+        // *some* editor. Report which one ran so the UI can say "Opening in
+        // Word…" vs "Opening in default editor…".
+        //
+        // CRITICAL: must use async spawn (not spawnSync). spawnSync blocks
+        // the Node event loop until the spawned process exits — and on
+        // Windows, `cmd /c start ... <gui-app>` sometimes does not return
+        // immediately when the GUI app hangs around. That froze the entire
+        // mailx IPC bridge on Edit-in-Word click; subsequent clicks
+        // (Discard, X, anything) hung waiting for a response that never
+        // came back. Async spawn launches and returns immediately;
+        // success/failure of the GUI launch is invisible from here, but
+        // the file is written and the watcher is armed regardless.
+        const { spawn } = await import("node:child_process");
+        const tryLaunch = (cmd: string, args: string[]): boolean => {
+            try {
+                const child = spawn(cmd, args, { detached: true, stdio: "ignore", windowsHide: true });
+                child.on("error", () => { /* ENOENT etc. — caller already moved on */ });
+                child.unref();
+                return true;
+            } catch { return false; }
+        };
+        // Editor preference: settings.externalEditor in `~/.mailx/config.jsonc`
+        // can be "word" | "libreoffice" | "auto" (default). Auto means try
+        // Word first, then LibreOffice, then OS default — gives Word users the
+        // expected experience while still working when Word isn't installed.
+        // LibreOffice tends to round-trip email-shaped HTML cleaner than
+        // Word, so users on either platform may want to flip it via the
+        // config editor.
+        const settings = (loadSettings() as any) || {};
+        const pref = (settings.externalEditor || "auto") as "word" | "libreoffice" | "auto";
+        const tryWord = (): boolean => {
+            if (process.platform === "win32") return tryLaunch("cmd", ["/c", "start", "", "/B", "winword.exe", filePath]);
+            if (process.platform === "darwin") return tryLaunch("open", ["-a", "Microsoft Word", filePath]);
+            return false; // no MS Word on Linux
+        };
+        const tryLibreOffice = (): boolean => {
+            if (process.platform === "win32") return tryLaunch("cmd", ["/c", "start", "", "/B", "soffice.exe", "--writer", filePath]);
+            if (process.platform === "darwin") return tryLaunch("open", ["-a", "LibreOffice", filePath]);
+            return tryLaunch("soffice", ["--writer", filePath]) || tryLaunch("libreoffice", ["--writer", filePath]);
+        };
+        const tryDefault = (): boolean => {
+            if (process.platform === "win32") return tryLaunch("cmd", ["/c", "start", "", filePath]);
+            if (process.platform === "darwin") return tryLaunch("open", [filePath]);
+            return tryLaunch("xdg-open", [filePath]);
+        };
+        let opener = "none";
+        const order: Array<[string, () => boolean]> =
+            pref === "libreoffice"
+                ? [["libreoffice", tryLibreOffice], ["word", tryWord], ["default", tryDefault]]
+            : pref === "word"
+                ? [["word", tryWord], ["default", tryDefault]]
+            : [["word", tryWord], ["libreoffice", tryLibreOffice], ["default", tryDefault]]; // auto
+        for (const [name, fn] of order) {
+            if (fn()) { opener = name; break; }
+        }
+        if (opener === "none") {
+            console.error(`  [word-edit] no editor found on this platform — file written to ${filePath}`);
+        } else {
+            console.log(`  [word-edit] opened ${filePath} via ${opener}`);
+        }
+
+        // Watch for save events. fs.watch on Windows fires multiple events
+        // per save (rename + change for atomic replacement); debounce so the
+        // UI only reloads once per save. Watch the directory rather than the
+        // file directly because Word writes via temp-file rename, which can
+        // invalidate a file-level watch.
+        let debounce: ReturnType<typeof setTimeout> | null = null;
+        let lastSize = -1;
+        const watcher = fs.watch(dir, (eventType, name) => {
+            if (name !== `${editId}.html`) return;
+            if (debounce) clearTimeout(debounce);
+            debounce = setTimeout(() => {
+                let stat: fs.Stats;
+                try { stat = fs.statSync(filePath); } catch { return; }
+                // Skip duplicate events with the same size — Word fires several
+                // change notifications per save and we only want one reload.
+                if (stat.size === lastSize) return;
+                lastSize = stat.size;
+                try {
+                    const updatedHtml = fs.readFileSync(filePath, "utf-8");
+                    // Strip the wrapper to extract just the body content.
+                    const bodyMatch = updatedHtml.match(/<body[^>]*>([\s\S]*?)<\/body>/i);
+                    const inner = bodyMatch ? bodyMatch[1] : updatedHtml;
+                    this.imapManager.emit("wordEditUpdated", { editId, html: inner });
+                } catch (e: any) {
+                    console.error(`  [word-edit] read after save failed: ${e.message}`);
+                }
+            }, 300);
+        });
+        const stop = () => {
+            try { watcher.close(); } catch { /* */ }
+            if (debounce) clearTimeout(debounce);
+        };
+        this.wordEdits.set(editId, { path: filePath, stop });
+
+        return { ok: opener !== "none", path: filePath, opener };
+    }
+
+    /** End external editing. Stops the watcher, removes the temp file.
+     *  Caller is the compose UI when the user closes the window or sends. */
+    async closeWordEdit(editId: string): Promise<void> {
+        const entry = this.wordEdits.get(editId);
+        if (!entry) return;
+        entry.stop();
+        this.wordEdits.delete(editId);
+        try { fs.unlinkSync(entry.path); } catch { /* file already gone — fine */ }
+    }
+
+    async updateFlags(accountId: string, uid: number, flags: string[]): Promise<void> {
+        const envelope = this.db.getMessageByUid(accountId, uid);
+        await this.imapManager.updateFlagsLocal(accountId, uid, envelope?.folderId || 0, flags);
+    }
+
+    // ── Remote content allow-list ──
+
+    async allowRemoteContent(type: "sender" | "domain" | "recipient", value: string): Promise<void> {
+        const list = loadAllowlist();
+        if (type === "sender" && !list.senders.includes(value)) list.senders.push(value);
+        else if (type === "domain" && !list.domains.includes(value)) list.domains.push(value);
+        else if (type === "recipient") {
+            if (!list.recipients) list.recipients = [];
+            if (!list.recipients.includes(value)) list.recipients.push(value);
+        }
+        await saveAllowlist(list);
+        console.log(`  [allow] Added ${type}: ${value}`);
+    }
+
+    /** Domain-reputation cache. Lookups are fast (~50ms each, three in
+     *  parallel) but we still don't want to redo them on every render of
+     *  the same sender's mail. Five-minute TTL — long enough that scrolling
+     *  a folder fans out one query set, short enough that a newly-listed
+     *  domain surfaces within minutes. */
+    private reputationCache = new Map<string, { result: ReputationResult; expiresAt: number }>();
+    private static readonly REPUTATION_TTL_MS = 5 * 60_000;
+    private static readonly REPUTATION_TIMEOUT_MS = 500;
+
+    /** Check a domain against three free no-key DNS blocklists in parallel:
+     *
+     *    Spamhaus DBL    — `<d>.dbl.spamhaus.org`     spam/phish/malware
+     *    SURBL multi     — `<d>.multi.surbl.org`      mixed (ph/mw/abuse)
+     *    URIBL multi     — `<d>.multi.uribl.com`      black/grey/red lists
+     *
+     *  Each lookup is bounded at 500 ms; missing/slow services are treated
+     *  as "unknown" (don't poison the cache). Returns the aggregate plus
+     *  the per-service detail so the UI can show "N of 3 services flag
+     *  this domain" with the contributing source list.
+     *
+     *  Privacy: each query leaks the bare domain to that DNSBL's
+     *  infrastructure plus the user's local resolver. Opt-in via Settings.
+     *
+     *  No API keys, free for personal use across all three services. */
+    async checkDomainReputation(domain: string): Promise<ReputationResult | null> {
+        domain = (domain || "").toLowerCase().trim();
+        if (!domain) return null;
+        const cached = this.reputationCache.get(domain);
+        if (cached && cached.expiresAt > Date.now()) return cached.result;
+
+        const probe = async (service: string, host: string, mapVerdict: (lastOctet: string) => string)
+            : Promise<{ service: string; flagged: boolean; verdict: string } | null> => {
+            try {
+                const lookup = dns.resolve4(`${domain}.${host}`);
+                const timeout = new Promise<never>((_, reject) =>
+                    setTimeout(() => reject(new Error("dnsbl-timeout")), MailxService.REPUTATION_TIMEOUT_MS));
+                const records = await Promise.race([lookup, timeout]) as string[];
+                const last = records[0]?.split(".").pop() || "";
+                return { service, flagged: true, verdict: mapVerdict(last) };
+            } catch (e: any) {
+                const code = e?.code || "";
+                if (code === "ENOTFOUND" || code === "ENODATA") {
+                    return { service, flagged: false, verdict: "clean" };
+                }
+                return null; // timeout / network — unknown
+            }
+        };
+
+        const dblVerdict = (last: string) =>
+            last === "2" ? "spam" :
+            last === "4" ? "phishing" :
+            last === "5" ? "malware" :
+            last === "6" ? "botnet" :
+            "listed";
+        // SURBL/URIBL encode multiple list memberships in a bitfield; the
+        // distinction matters less to the end user than "how many sources
+        // agree", so we keep a generic "listed" verdict for both.
+        const generic = (_last: string) => "listed";
+
+        const sources = await Promise.all([
+            probe("Spamhaus DBL", "dbl.spamhaus.org", dblVerdict),
+            probe("SURBL", "multi.surbl.org", generic),
+            probe("URIBL", "multi.uribl.com", generic),
+        ]);
+
+        const known = sources.filter((s): s is { service: string; flagged: boolean; verdict: string } => s !== null);
+        const flagged = known.filter(s => s.flagged);
+        const result: ReputationResult = {
+            flagged: flagged.length > 0,
+            listedCount: flagged.length,
+            checkedCount: known.length,
+            sources: flagged,
+            // Pick the most specific verdict if Spamhaus contributed (since
+            // DBL distinguishes phishing/malware/etc); otherwise generic.
+            verdict: flagged.find(s => s.service === "Spamhaus DBL")?.verdict || flagged[0]?.verdict || "clean",
+            service: flagged.map(s => s.service).join(", ") || "Spamhaus DBL / SURBL / URIBL",
+        };
+        this.reputationCache.set(domain, { result, expiresAt: Date.now() + MailxService.REPUTATION_TTL_MS });
+        return result;
+    }
+
+    /** Mark a sender or domain as suspect. Surfaced in the remote-content
+     *  banner as a red warning on subsequent messages. Toggle: calling with
+     *  the same value removes it. Returns the new state for UI feedback. */
+    async flagSenderOrDomain(type: "sender" | "domain", value: string): Promise<{ flagged: boolean }> {
+        const list = loadAllowlist() as any;
+        const key = type === "sender" ? "flaggedSenders" : "flaggedDomains";
+        if (!Array.isArray(list[key])) list[key] = [];
+        const lower = (value || "").toLowerCase();
+        const idx = list[key].findIndex((v: string) => (v || "").toLowerCase() === lower);
+        if (idx >= 0) {
+            list[key].splice(idx, 1);
+            await saveAllowlist(list);
+            console.log(`  [flag] Removed ${type}: ${value}`);
+            return { flagged: false };
+        }
+        list[key].push(value);
+        await saveAllowlist(list);
+        console.log(`  [flag] Added ${type}: ${value}`);
+        return { flagged: true };
+    }
+
+    // ── Search ──
+
+    async search(q: string, page = 1, pageSize = 50, scope = "all", accountId?: string, folderId?: number): Promise<any> {
+        q = (q || "").trim();
+        if (!q) return { items: [], total: 0, page, pageSize };
+
+        if (scope === "server") {
+            // Parse qualifiers once; SEARCH runs per folder.
+            const criteria: any = {};
+            const fromMatch = q.match(/from:(\S+)/i);
+            const toMatch = q.match(/to:(\S+)/i);
+            const subjectMatch = q.match(/subject:(.+?)(?:\s+\w+:|$)/i);
+            const bodyText = q.replace(/(?:from|to|subject):\S+/gi, "").trim();
+            if (fromMatch) criteria.from = fromMatch[1];
+            if (toMatch) criteria.to = toMatch[1];
+            if (subjectMatch) criteria.subject = subjectMatch[1].trim();
+            if (bodyText) criteria.body = bodyText;
+
+            // Server search spans every selectable folder on every enabled
+            // account — otherwise a message that got moved / was in Sent /
+            // only exists in an archive folder silently fails to turn up.
+            // Each folder runs as its own SEARCH; we dedupe by messageId.
+            const dbAccounts = accountId
+                ? [{ id: accountId }]
+                : this.db.getAccounts();
+            const seen = new Set<string>();
+            const items: any[] = [];
+            let total = 0;
+
+            for (const acct of dbAccounts) {
+                const folders = this.db.getFolders(acct.id)
+                    .filter((f: any) => !(f.flags || []).some((x: string) => /noselect/i.test(x)));
+                const results = await Promise.allSettled(
+                    folders.map(f =>
+                        this.imapManager.searchAndFetchOnServer(acct.id, f.id, f.path, criteria)
+                            .then(uids => ({ folderId: f.id, uids }))
+                    )
+                );
+                for (const r of results) {
+                    if (r.status !== "fulfilled") continue;
+                    for (const uid of r.value.uids) {
+                        const msg = this.db.getMessageByUid(acct.id, uid, r.value.folderId);
+                        if (!msg) continue;
+                        const key = msg.messageId || `${acct.id}:${r.value.folderId}:${uid}`;
+                        if (seen.has(key)) continue;
+                        seen.add(key);
+                        items.push(msg);
+                        total++;
+                    }
+                }
+            }
+
+            // Newest first, then paginate.
+            items.sort((a: any, b: any) => (b.date?.getTime?.() || 0) - (a.date?.getTime?.() || 0));
+            const sliced = items.slice((page - 1) * pageSize, page * pageSize);
+            return { items: sliced, total, page, pageSize };
+        } else if (scope === "current" && accountId && folderId) {
+            return this.db.searchMessages(q, page, pageSize, accountId, folderId);
+        } else {
+            return this.db.searchMessages(q, page, pageSize);
+        }
+    }
+
+    rebuildSearchIndex(): number {
+        const count = this.db.rebuildSearchIndex();
+        console.log(`  Rebuilt search index: ${count} messages`);
+        return count;
+    }
+
+    // ── Sync ──
+
+    getSyncPending(): { pending: number } {
+        return { pending: this.db.getTotalPendingSyncCount() };
+    }
+
+    /** Outbox queue depth + retry status for the UI status bar. Cheap to call. */
+    getOutboxStatus(): any {
+        return this.imapManager.getOutboxStatus();
+    }
+
+    /** Per-account health snapshot: inactivity-timeout count, conn-cap hits,
+     *  last failed IMAP command. Drives the diagnostics ⚠ badge in the UI. */
+    getDiagnostics(): any {
+        return this.imapManager.getDiagnosticsSnapshot();
+    }
+
+    /** Return the account that supplies `feature` data (calendar / tasks /
+     *  contacts). Resolution order:
+     *    1. Any account with `primary<Feature>: true`   (per-feature override)
+     *    2. Any account with `primary: true`            (catch-all default)
+     *    3. First account                               (fallback)
+     *  Called without `feature` it returns the catch-all primary — same
+     *  semantics as the original single-flag version for back-compat. */
+    getPrimaryAccount(feature?: string): any {
+        const all = this.getAccounts();
+        if (feature) {
+            const perFeatureKey = "primary" + feature.charAt(0).toUpperCase() + feature.slice(1);
+            const perFeature = all.find((a: any) => a[perFeatureKey]);
+            if (perFeature) return perFeature;
+        }
+        return all.find((a: any) => a.primary) || all[0] || null;
+    }
+
+    // ── Calendar / Tasks / Contacts: two-way cache (2026-04-23) ──
+
+    /** Feature names that have already emitted authScopeError this session.
+     *  Stops the "banner flashing on and off continually" loop where every
+     *  5-min poll / sidebar nav re-fired the event and the client re-rendered
+     *  the red banner. Cleared when the user hits Re-authenticate. */
+    private scopeErrorEmitted = new Set<string>();
+
+    /** Quota cooldown — feature → epoch-ms when the next API call is allowed.
+     *  Set when Google returns 429 (rate limit / daily-quota exceeded). While
+     *  cooldown is in effect, getCalendarEvents/getTasks return local DB rows
+     *  without firing a refresh. Heuristic cooldown is one hour; the daily
+     *  Google Tasks quota actually resets at Pacific midnight, but a one-hour
+     *  short-circuit keeps the log clean and avoids hammering after a burst. */
+    private quotaCooldown = new Map<string, number>();
+
+    /** Sticky "quota exceeded" emit guard — same shape as scopeErrorEmitted. */
+    private quotaErrorEmitted = new Set<string>();
+
+    /** In-flight refresh promises keyed by feature, so concurrent UI calls
+     *  share one Google round-trip instead of stacking N parallel fetches.
+     *  The fire-and-forget loop where `tasksUpdated` re-triggers `getTasks`
+     *  used to spawn a new refresh on every event RTT — this dedupes them. */
+    private refreshingCalendar = new Map<string, Promise<boolean>>();
+    private refreshingTasks = new Map<string, Promise<boolean>>();
+
+    /** Delete the cached Google OAuth token (the one used for Calendar / Tasks
+     *  / Contacts scopes — NOT the IMAP token which `reauthenticate()` handles)
+     *  and clear the sticky auth-error state so a subsequent refresh can
+     *  re-trigger browser consent with the current scope set. Equivalent of
+     *  `mailx -reauth` but callable from the UI. Returns `{ cleared: N }` so
+     *  the caller can tell the user what happened. */
+    reauthGoogleScopes(): { cleared: number } {
+        const tokensDir = path.join(getConfigDir(), "tokens");
+        let cleared = 0;
+        if (fs.existsSync(tokensDir)) {
+            for (const entry of fs.readdirSync(tokensDir)) {
+                const userDir = path.join(tokensDir, entry);
+                try {
+                    if (!fs.statSync(userDir).isDirectory()) continue;
+                    const tokenFile = path.join(userDir, "oauth-token.json");
+                    if (fs.existsSync(tokenFile)) {
+                        fs.unlinkSync(tokenFile);
+                        console.log(`  [reauth-google] cleared ${tokenFile}`);
+                        cleared++;
+                    }
+                } catch { /* skip */ }
+            }
+        }
+        // Reset the sticky set so the next failure (if re-consent didn't take)
+        // can fire a fresh banner. Also trigger a kickoff refresh so the
+        // browser consent pops open now instead of on next sidebar nav.
+        this.scopeErrorEmitted.clear();
+        this.quotaCooldown.clear();
+        this.quotaErrorEmitted.clear();
+        const now = Date.now();
+        const horizonMs = 90 * 86400_000;
+        this.getCalendarEvents(now, now + horizonMs);  // fire-and-forget — triggers consent via primaryTokenProvider
+        this.getTasks(false);                           // same path, `tasks` scope
+        return { cleared };
+    }
+
+    private async primaryTokenProvider(feature: string): Promise<(() => Promise<string>)> {
+        const acct = this.getPrimaryAccount(feature);
+        if (!acct) throw new Error(`No primary account for ${feature}`);
+        return async () => {
+            const tok = await this.imapManager.getOAuthToken(acct.id);
+            if (!tok) throw new Error(`No OAuth token for ${acct.id}`);
+            return tok;
+        };
+    }
+
+    /** Return cal events visible in [fromMs..toMs), refreshing from Google
+     *  in the background. Caller displays local results immediately; after
+     *  the refresh completes the service emits `calendarUpdated` so the UI
+     *  re-renders with pulled-in rows. Fire-and-forget-with-event, not
+     *  fire-and-forget-and-pray. */
+    async getCalendarEvents(fromMs: number, toMs: number): Promise<any[]> {
+        const acct = this.getPrimaryAccount("calendar");
+        if (!acct) return [];
+        const acctId = acct.id;
+        // Skip the network entirely while in quota cooldown — return DB rows.
+        if (!this.inQuotaCooldown("calendar")) {
+            let promise = this.refreshingCalendar.get(acctId);
+            if (!promise) {
+                promise = this.refreshCalendarEvents(acctId, fromMs, toMs)
+                    .finally(() => this.refreshingCalendar.delete(acctId));
+                this.refreshingCalendar.set(acctId, promise);
+                promise
+                    .then(changed => {
+                        if (changed) this.imapManager.emit("calendarUpdated", { accountId: acctId });
+                    })
+                    .catch(e => this.handleGoogleRefreshError("calendar", e));
+            }
+        }
+        return this.db.getCalendarEvents(acctId, fromMs, toMs);
+    }
+
+    /** Returns true if the feature is currently in a quota-exceeded cooldown. */
+    private inQuotaCooldown(feature: string): boolean {
+        const until = this.quotaCooldown.get(feature);
+        if (!until) return false;
+        if (Date.now() < until) return true;
+        this.quotaCooldown.delete(feature);
+        this.quotaErrorEmitted.delete(feature);
+        return false;
+    }
+
+    /** Single error-handling path for Google refresh failures.
+     *  Distinguishes 429 (quota) from 401/403 (scope) so each gets the right
+     *  cooldown + sticky-emit treatment without duplicating the regex blocks. */
+    private handleGoogleRefreshError(feature: string, e: any): void {
+        const msg = String(e?.message || e);
+        const status = e instanceof gsync.GoogleHttpError ? e.status : 0;
+        const is429 = status === 429 || /\b429\b|rateLimitExceeded|quotaExceeded|userRateLimitExceeded/i.test(msg);
+        const isScope = !is429 && (status === 401 || status === 403
+            || /insufficient (authentication )?scope|PERMISSION_DENIED|\b403\b/i.test(msg));
+        console.error(`[${feature}] refresh failed: ${msg}`);
+        if (is429) {
+            const cooldownMs = 60 * 60_000; // one hour heuristic
+            this.quotaCooldown.set(feature, Date.now() + cooldownMs);
+            if (!this.quotaErrorEmitted.has(feature)) {
+                this.quotaErrorEmitted.add(feature);
+                this.imapManager.emit("quotaError", {
+                    feature,
+                    message: `Google ${feature} daily quota exceeded — try again later.`,
+                    untilMs: Date.now() + cooldownMs,
+                });
+            }
+            return;
+        }
+        if (isScope) {
+            if (!this.scopeErrorEmitted.has(feature)) {
+                this.scopeErrorEmitted.add(feature);
+                const labels: Record<string, string> = {
+                    calendar: "Google Calendar", tasks: "Google Tasks", contacts: "Google Contacts",
+                };
+                this.imapManager.emit("authScopeError", {
+                    feature,
+                    message: `${labels[feature] || feature} access needs re-consent.`,
+                });
+            }
+        }
+    }
+
+    /** Pull events in [fromMs..toMs) from Google, upsert locally, reconcile
+     *  server-side deletions. Returns true if anything changed so callers
+     *  can decide whether to emit a refresh event. `changed` is only true
+     *  when at least one row's data actually differs — without this guard
+     *  the UI's `calendarUpdated` listener re-triggers `getCalendarEvents`,
+     *  which fires another `refreshCalendarEvents`, which emits again, etc.
+     *  Tight loop = 429 quota burn. */
+    private async refreshCalendarEvents(accountId: string, fromMs: number, toMs: number): Promise<boolean> {
+        const tp = await this.primaryTokenProvider("calendar");
+        const events = await gsync.listCalendarEvents(tp, fromMs, toMs);
+        console.log(`  [calendar] pulled ${events.length} events from ${new Date(fromMs).toISOString().slice(0, 10)} to ${new Date(toMs).toISOString().slice(0, 10)}`);
+        let changed = false;
+        // Upsert by provider_id — dedup globally, not just within the window,
+        // so an event whose start moves outside the prior query range doesn't
+        // get a second row on the next pull.
+        const seenProviderIds = new Set<string>();
+        for (const ev of events) {
+            const local = gsync.calendarEventToLocal(ev, accountId);
+            seenProviderIds.add(ev.id);
+            const existing = this.db.getCalendarEventByProviderId(accountId, ev.id);
+            if (existing && calendarRowEquals(existing, local)) continue;
+            this.db.upsertCalendarEvent({ uuid: existing?.uuid, ...local });
+            changed = true;
+        }
+        // Server-side delete reconciliation: any local non-dirty row whose
+        // start falls in the queried window and whose provider_id wasn't
+        // returned must have been deleted on Google. Purge it. Dirty rows
+        // are local-only edits that haven't been pushed yet — don't touch.
+        const localWindow = this.db.getCalendarEvents(accountId, fromMs, toMs);
+        for (const row of localWindow) {
+            if (!row.providerId) continue; // local-only, never pushed
+            if (row.dirty) continue;       // locally edited, pending push
+            if (seenProviderIds.has(row.providerId)) continue;
+            this.db.purgeCalendarEvent(row.uuid);
+            changed = true;
+        }
+        return changed;
+    }
+
+    async createCalendarEventLocal(ev: {
+        title: string; startMs: number; endMs: number; allDay?: boolean;
+        location?: string; notes?: string;
+    }): Promise<string> {
+        const acct = this.getPrimaryAccount("calendar");
+        if (!acct) throw new Error("No primary calendar account");
+        const uuid = this.db.upsertCalendarEvent({
+            accountId: acct.id, ...ev, dirty: true,
+        });
+        this.db.enqueueStoreSync("calendar", "create", acct.id, uuid, ev);
+        this.drainStoreSync().catch(() => { /* best-effort; retried on poll */ });
+        return uuid;
+    }
+
+    async updateCalendarEventLocal(uuid: string, patch: {
+        title?: string; startMs?: number; endMs?: number; allDay?: boolean;
+        location?: string; notes?: string;
+    }): Promise<void> {
+        // Merge with existing row before writing so partial patches don't
+        // null-out unspecified fields in upsert.
+        const existing = this.db.getCalendarEventByUuid(uuid);
+        if (!existing) throw new Error(`No calendar event ${uuid}`);
+        this.db.upsertCalendarEvent({
+            uuid, accountId: existing.accountId, providerId: existing.providerId,
+            calendarId: existing.calendarId, dirty: true,
+            title: patch.title ?? existing.title,
+            startMs: patch.startMs ?? existing.startMs,
+            endMs: patch.endMs ?? existing.endMs,
+            allDay: patch.allDay ?? existing.allDay,
+            location: patch.location ?? existing.location,
+            notes: patch.notes ?? existing.notes,
+        });
+        this.db.enqueueStoreSync("calendar", "update", existing.accountId, uuid,
+            { providerId: existing.providerId, patch });
+        this.drainStoreSync().catch(() => { /* */ });
+    }
+
+    async deleteCalendarEventLocal(uuid: string): Promise<void> {
+        const ev = this.db.getCalendarEventByUuid(uuid);
+        if (!ev) return;
+        this.db.deleteCalendarEventLocal(uuid);
+        if (ev.providerId) {
+            this.db.enqueueStoreSync("calendar", "delete", ev.accountId, uuid, { providerId: ev.providerId });
+            this.drainStoreSync().catch(() => { /* */ });
+        } else {
+            // Never made it to the server; just purge locally.
+            this.db.purgeCalendarEvent(uuid);
+        }
+    }
+
+    async getTasks(includeCompleted = false): Promise<any[]> {
+        const acct = this.getPrimaryAccount("tasks");
+        if (!acct) return [];
+        const acctId = acct.id;
+        if (!this.inQuotaCooldown("tasks")) {
+            const key = `${acctId}:${includeCompleted ? 1 : 0}`;
+            let promise = this.refreshingTasks.get(key);
+            if (!promise) {
+                promise = this.refreshTasks(acctId, includeCompleted)
+                    .finally(() => this.refreshingTasks.delete(key));
+                this.refreshingTasks.set(key, promise);
+                promise
+                    .then(changed => {
+                        if (changed) this.imapManager.emit("tasksUpdated", { accountId: acctId });
+                    })
+                    .catch(e => this.handleGoogleRefreshError("tasks", e));
+            }
+        }
+        return this.db.getTasks(acctId, includeCompleted);
+    }
+
+    private async refreshTasks(accountId: string, includeCompleted: boolean): Promise<boolean> {
+        const tp = await this.primaryTokenProvider("tasks");
+        const tasks = await gsync.listTasks(tp, "@default", includeCompleted);
+        console.log(`  [tasks] pulled ${tasks.length} tasks`);
+        const existing = this.db.getTasks(accountId, true);
+        let changed = false;
+        const seen = new Set<string>();
+        for (const t of tasks) {
+            const local = gsync.taskToLocal(t, accountId);
+            const prior = existing.find(e => e.providerId === t.id);
+            seen.add(t.id);
+            // Skip the upsert when nothing actually differs. Otherwise every
+            // refresh emits `tasksUpdated`, the UI listener calls `getTasks`,
+            // which fires another `refreshTasks` — tight loop, 429 quota burn.
+            if (prior && taskRowEquals(prior, local)) continue;
+            this.db.upsertTask({ uuid: prior?.uuid, ...local });
+            changed = true;
+        }
+        // Server-side delete reconciliation: any non-dirty local task whose
+        // provider_id wasn't returned has been deleted on Google. Purge.
+        for (const row of existing) {
+            if (!row.providerId || row.dirty) continue;
+            if (seen.has(row.providerId)) continue;
+            this.db.purgeTask(row.uuid);
+            changed = true;
+        }
+        return changed;
+    }
+
+    async createTaskLocal(t: { title: string; notes?: string; dueMs?: number }): Promise<string> {
+        const acct = this.getPrimaryAccount("tasks");
+        if (!acct) throw new Error("No primary tasks account");
+        const uuid = this.db.upsertTask({ accountId: acct.id, ...t, dirty: true });
+        this.db.enqueueStoreSync("tasks", "create", acct.id, uuid, t);
+        this.drainStoreSync().catch(() => { /* */ });
+        return uuid;
+    }
+
+    async updateTaskLocal(uuid: string, patch: {
+        title?: string; notes?: string; dueMs?: number; completedMs?: number;
+    }): Promise<void> {
+        const existing = this.db.getTaskByUuid(uuid);
+        if (!existing) throw new Error(`No task ${uuid}`);
+        this.db.upsertTask({
+            uuid, accountId: existing.accountId, providerId: existing.providerId,
+            listId: existing.listId, dirty: true,
+            title: patch.title ?? existing.title,
+            notes: patch.notes ?? existing.notes,
+            dueMs: patch.dueMs ?? existing.dueMs,
+            completedMs: patch.completedMs ?? existing.completedMs,
+        });
+        this.db.enqueueStoreSync("tasks", "update", existing.accountId, uuid,
+            { providerId: existing.providerId, patch });
+        this.drainStoreSync().catch(() => { /* */ });
+    }
+
+    async deleteTaskLocal(uuid: string): Promise<void> {
+        const task = this.db.getTaskByUuid(uuid);
+        if (!task) return;
+        this.db.deleteTaskLocal(uuid);
+        if (task.providerId) {
+            this.db.enqueueStoreSync("tasks", "delete", task.accountId, uuid, { providerId: task.providerId });
+            this.drainStoreSync().catch(() => { /* */ });
+        } else {
+            this.db.purgeTask(uuid);
+        }
+    }
+
+    /** Drain the store_sync queue — calendar / tasks / contacts push-to-server.
+     *  Called on every local edit, and on a periodic tick from the outbox worker. */
+    async drainStoreSync(): Promise<void> {
+        const queue = this.db.getStoreSyncQueue();
+        for (const entry of queue) {
+            try {
+                if (entry.kind === "calendar") {
+                    const tp = await this.primaryTokenProvider("calendar");
+                    if (entry.op === "create") {
+                        const created = await gsync.createCalendarEvent(tp, gsync.localToCalendarEvent(entry.payload));
+                        this.db.markCalendarEventClean(entry.targetUuid, created.id, created.etag || "");
+                    } else if (entry.op === "update") {
+                        const updated = await gsync.updateCalendarEvent(tp, entry.payload.providerId,
+                            gsync.localToCalendarEvent(entry.payload.patch));
+                        this.db.markCalendarEventClean(entry.targetUuid, updated.id, updated.etag || "");
+                    } else if (entry.op === "delete") {
+                        await gsync.deleteCalendarEvent(tp, entry.payload.providerId);
+                        this.db.purgeCalendarEvent(entry.targetUuid);
+                    }
+                } else if (entry.kind === "tasks") {
+                    const tp = await this.primaryTokenProvider("tasks");
+                    if (entry.op === "create") {
+                        const created = await gsync.createTask(tp, gsync.localToTask(entry.payload));
+                        this.db.markTaskClean(entry.targetUuid, created.id, created.etag || "");
+                    } else if (entry.op === "update") {
+                        const updated = await gsync.updateTask(tp, entry.payload.providerId,
+                            gsync.localToTask(entry.payload.patch));
+                        this.db.markTaskClean(entry.targetUuid, updated.id, updated.etag || "");
+                    } else if (entry.op === "delete") {
+                        await gsync.deleteTask(tp, entry.payload.providerId);
+                        this.db.purgeTask(entry.targetUuid);
+                    }
+                } else if (entry.kind === "contacts") {
+                    const tp = await this.primaryTokenProvider("contacts");
+                    if (entry.op === "create") {
+                        await gsync.createContact(tp, entry.payload);
+                    } else if (entry.op === "update") {
+                        await gsync.updateContact(tp, entry.payload.resourceName,
+                            entry.payload.updatePersonFields || "names,emailAddresses",
+                            entry.payload.person);
+                    } else if (entry.op === "delete") {
+                        await gsync.deleteContact(tp, entry.payload.resourceName);
+                    }
+                }
+                this.db.completeStoreSync(entry.id);
+            } catch (e: any) {
+                console.error(`[store_sync] ${entry.kind}/${entry.op}/${entry.targetUuid} failed: ${e.message}`);
+                this.db.failStoreSync(entry.id, e.message || String(e));
+            }
+        }
+    }
+
+    /** List queued outgoing messages with parsed envelope headers so the UI
+     *  can render a pink-row "pending" view before IMAP APPEND succeeds. */
+    listQueuedOutgoing(): any[] {
+        const configDir = getConfigDir();
+        const outboxRoot = path.join(configDir, "outbox");
+        const sendingRoot = path.join(configDir, "sending");
+        const out: any[] = [];
+        const parseEnv = (raw: string, file: string, dir: string, accountId: string) => {
+            const headerEnd = raw.search(/\r?\n\r?\n/);
+            const headers = headerEnd >= 0 ? raw.slice(0, headerEnd) : raw;
+            const get = (name: string): string => {
+                const re = new RegExp(`^${name}:\\s*(.+(?:\\r?\\n\\s+.+)*)`, "mi");
+                const m = headers.match(re);
+                return m ? m[1].replace(/\r?\n\s+/g, " ").trim() : "";
+            };
+            const retries = (headers.match(/^X-Mailx-Retry:/gmi) || []).length;
+            const st = (() => { try { return fs.statSync(path.join(dir, file)); } catch { return null; } })();
+            return {
+                accountId,
+                file,
+                path: path.join(dir, file),
+                dir,
+                from: get("From"),
+                to: get("To"),
+                cc: get("Cc"),
+                bcc: get("Bcc"),
+                subject: get("Subject"),
+                date: get("Date"),
+                messageId: get("Message-ID"),
+                attempts: retries,
+                sizeBytes: st?.size || 0,
+                createdAt: st?.mtimeMs || 0,
+                claimed: /\.sending-[^-]+-\d+$/.test(file),
+            };
+        };
+        const scanDir = (accountId: string, dir: string) => {
+            if (!fs.existsSync(dir)) return;
+            for (const f of fs.readdirSync(dir)) {
+                if (!f.endsWith(".ltr") && !f.endsWith(".eml") && !/\.sending-/.test(f)) continue;
+                const fp = path.join(dir, f);
+                try {
+                    const raw = fs.readFileSync(fp, "utf-8");
+                    out.push(parseEnv(raw, f, dir, accountId));
+                } catch (err: any) {
+                    // Unreadable file — still show it so the user can cancel.
+                    // Previously silently skipped, which produced the user-reported
+                    // "outbox badge shows 1 but the modal is empty" symptom:
+                    // getOutboxStatus counted the file, listQueuedOutgoing dropped it.
+                    const st = (() => { try { return fs.statSync(fp); } catch { return null; } })();
+                    out.push({
+                        accountId,
+                        file: f,
+                        path: fp,
+                        dir,
+                        from: "",
+                        to: "",
+                        cc: "",
+                        bcc: "",
+                        subject: `[unreadable: ${err?.code || err?.message || "read failed"}]`,
+                        date: "",
+                        messageId: "",
+                        attempts: 0,
+                        sizeBytes: st?.size || 0,
+                        createdAt: st?.mtimeMs || 0,
+                        claimed: /\.sending-[^-]+-\d+$/.test(f),
+                    });
+                }
+            }
+        };
+        try {
+            if (fs.existsSync(outboxRoot)) {
+                for (const acct of fs.readdirSync(outboxRoot)) scanDir(acct, path.join(outboxRoot, acct));
+            }
+            if (fs.existsSync(sendingRoot)) {
+                for (const acct of fs.readdirSync(sendingRoot)) scanDir(acct, path.join(sendingRoot, acct, "queued"));
+            }
+        } catch { /* */ }
+        out.sort((a, b) => b.createdAt - a.createdAt);
+        return out;
+    }
+
+    /** Manually drop a queued message (not yet sent). Removes the .ltr file. */
+    cancelQueuedOutgoing(filePath: string): { ok: true } {
+        // Safety: refuse anything outside the ~/.mailx tree.
+        const dir = getConfigDir();
+        if (!filePath.startsWith(dir)) throw new Error("path outside mailx data dir");
+        if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+        return { ok: true };
+    }
+
+    async syncAll(): Promise<void> {
+        await this.imapManager.syncAll();
+    }
+
+    async syncAccount(accountId: string): Promise<void> {
+        const folders = await this.imapManager.syncFolders(accountId);
+        folders.sort((a, b) => {
+            if (a.specialUse === "inbox") return -1;
+            if (b.specialUse === "inbox") return 1;
+            return 0;
+        });
+        for (const folder of folders) {
+            try {
+                await this.imapManager.syncFolder(accountId, folder.id);
+            } catch (e: any) {
+                console.error(`  Skipping folder ${folder.path}: ${e.message}`);
+            }
+        }
+    }
+
+    /** Force re-authentication for an account (deletes token, opens browser consent) */
+    async reauthenticate(accountId: string): Promise<boolean> {
+        return this.imapManager.reauthenticate(accountId);
+    }
+
+    // ── Send ──
+
+    async send(msg: any): Promise<void> {
+        // Local-first: the critical path is validate → build raw → queue
+        // locally. Everything else (contacts recording, IMAP APPEND,
+        // SMTP) happens after the IPC ACK. Settings come from cache so
+        // a stalled GDrive mount doesn't block the send.
+        const t0 = Date.now();
+        const lap = (label: string) => console.log(`  [send] +${Date.now() - t0}ms ${label}`);
+        console.log(`  [send] ENTRY from=${msg?.from} to=${JSON.stringify(msg?.to)} subject="${msg?.subject}" attachments=${msg?.attachments?.length || 0}`);
+        const accounts = this.getCachedAccounts();
+        let account = accounts.find(a => a.id === msg.from);
+        if (!account) {
+            // Cache miss — invalidate and try one authoritative read.
+            this._accountsCache = null;
+            account = this.getCachedAccounts().find(a => a.id === msg.from);
+        }
+        if (!account) {
+            const ids = accounts.map(a => a.id).join(", ");
+            console.error(`  [send] FAIL: Unknown account "${msg.from}". Known accounts: [${ids}]`);
+            throw new Error(`Unknown account: ${msg.from}`);
+        }
+        lap("account resolved");
+
+        // Vet every recipient address — refuse to send if any field contains a
+        // non-email (e.g. "Bob Frankston <Bob Frankston>" from a bad contact
+        // autocomplete). This catches garbage BEFORE it hits SMTP, where the
+        // server would either accept-and-bounce or reject the whole envelope.
+        const emailRe = /^[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+$/;
+        const validateList = (label: string, list: { name?: string; address?: string }[] | undefined) => {
+            if (!list) return;
+            for (const a of list) {
+                const addr = (a?.address || "").trim();
+                if (!addr) throw new Error(`${label} has an empty address`);
+                if (!emailRe.test(addr)) throw new Error(`${label} has an invalid address: "${addr}"${a?.name ? ` (displayed as "${a.name}")` : ""}`);
+            }
+        };
+        validateList("To", msg.to);
+        validateList("Cc", msg.cc);
+        validateList("Bcc", msg.bcc);
+        if (!msg.to?.length) throw new Error("No To recipients");
+
+        // Extract bare email from fromAddress (may be "Name <addr>" or just "addr")
+        let fromAddr = msg.fromAddress || account.email;
+        const angleMatch = fromAddr.match(/<([^>]+)>/);
+        if (angleMatch) fromAddr = angleMatch[1];
+        if (!emailRe.test(fromAddr)) throw new Error(`From address is not a valid email: "${fromAddr}"`);
+        const fromHeader = `${account.name} <${fromAddr}>`;
+        const to = msg.to.map((a: any) => a.name ? `${a.name} <${a.address}>` : a.address).join(", ");
+        const cc = msg.cc?.map((a: any) => a.name ? `${a.name} <${a.address}>` : a.address).join(", ");
+        const bcc = msg.bcc?.map((a: any) => a.name ? `${a.name} <${a.address}>` : a.address).join(", ");
+        // HTML-bodied mail gets a text/plain alternative part too — spam
+        // filters (SpamAssassin / Rspamd / Google) penalise HTML-only mail
+        // by 1-2 points, and plain-text-only readers still exist. The text
+        // part is derived from the HTML via htmlToPlainText when the caller
+        // didn't supply an explicit bodyText.
+        const hasHtml = !!msg.bodyHtml;
+        const htmlBody = msg.bodyHtml || "";
+        const textBody = msg.bodyText || (hasHtml ? htmlToPlainText(htmlBody) : "");
+        const htmlEncoded = hasHtml ? encodeQuotedPrintable(htmlBody) : "";
+        const textEncoded = encodeQuotedPrintable(textBody);
+
+        // Generate a unique Message-ID (required for threading, dedup, and RFC compliance)
+        const domain = account.email.split("@")[1] || "mailx.local";
+        const messageId = `<${Date.now()}.${Math.random().toString(36).slice(2)}@${domain}>`;
+
+        const hasAttachments = Array.isArray(msg.attachments) && msg.attachments.length > 0;
+        const commonHeaders = [
+            `From: ${fromHeader}`, `To: ${to}`,
+            cc ? `Cc: ${cc}` : null, bcc ? `Bcc: ${bcc}` : null,
+            `Subject: ${msg.subject}`, `Date: ${new Date().toUTCString()}`,
+            `Message-ID: ${messageId}`,
+            msg.inReplyTo ? `In-Reply-To: ${msg.inReplyTo}` : null,
+            msg.references?.length ? `References: ${msg.references.join(" ")}` : null,
+            `MIME-Version: 1.0`,
+        ].filter(h => h !== null);
+
+        let rawMessage: string;
+        const newBoundary = () =>
+            `mailx_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+        // Inner body: either a multipart/alternative (text+html) or a single
+        // text/plain. `innerBody` is the body-only portion (no envelope
+        // headers) that will be wrapped by the attachments multipart if any.
+        const makeInner = (): { headers: string[]; body: string } => {
+            if (hasHtml) {
+                const altBoundary = newBoundary();
+                const body =
+                    `--${altBoundary}\r\n` +
+                    `Content-Type: text/plain; charset=UTF-8\r\n` +
+                    `Content-Transfer-Encoding: quoted-printable\r\n\r\n` +
+                    `${textEncoded}\r\n` +
+                    `--${altBoundary}\r\n` +
+                    `Content-Type: text/html; charset=UTF-8\r\n` +
+                    `Content-Transfer-Encoding: quoted-printable\r\n\r\n` +
+                    `${htmlEncoded}\r\n` +
+                    `--${altBoundary}--\r\n`;
+                return {
+                    headers: [`Content-Type: multipart/alternative; boundary="${altBoundary}"`],
+                    body,
+                };
+            }
+            // Plain-text-only send — no HTML supplied, no alternative needed.
+            return {
+                headers: [
+                    `Content-Type: text/plain; charset=UTF-8`,
+                    `Content-Transfer-Encoding: quoted-printable`,
+                ],
+                body: textEncoded,
+            };
+        };
+        if (hasAttachments) {
+            // multipart/mixed wrapping (multipart/alternative | text/plain)
+            // + one base64 attachment part per file. Attachment chunks are
+            // wrapped at 76-char lines per RFC 2045.
+            const mixedBoundary = newBoundary();
+            const wrap76 = (s: string): string => s.replace(/.{1,76}/g, m => m).match(/.{1,76}/g)?.join("\r\n") || s;
+            const inner = makeInner();
+            const parts: string[] = [];
+            parts.push(
+                `--${mixedBoundary}\r\n` +
+                inner.headers.join("\r\n") +
+                `\r\n\r\n` +
+                inner.body
+            );
+            for (const att of msg.attachments) {
+                const filename = (att.filename || "attachment").replace(/[\r\n"]/g, "_");
+                const mime = att.mimeType || "application/octet-stream";
+                const wrapped = wrap76(att.dataBase64 || "");
+                parts.push(
+                    `--${mixedBoundary}\r\n` +
+                    `Content-Type: ${mime}; name="${filename}"\r\n` +
+                    `Content-Disposition: attachment; filename="${filename}"\r\n` +
+                    `Content-Transfer-Encoding: base64\r\n\r\n` +
+                    `${wrapped}\r\n`
+                );
+            }
+            const headers = [
+                ...commonHeaders,
+                `Content-Type: multipart/mixed; boundary="${mixedBoundary}"`,
+            ].join("\r\n");
+            rawMessage = `${headers}\r\n\r\n${parts.join("")}--${mixedBoundary}--\r\n`;
+        } else {
+            const inner = makeInner();
+            const headers = [
+                ...commonHeaders,
+                ...inner.headers,
+            ].join("\r\n");
+            rawMessage = `${headers}\r\n\r\n${inner.body}`;
+        }
+
+        lap(`MIME assembled (${rawMessage.length} bytes${hasAttachments ? `, ${msg.attachments.length} attachment(s)` : ""})`);
+        this.imapManager.queueOutgoingLocal(account.id, rawMessage);
+        lap("queued to disk");
+        // Local-first Sent: don't wait for SMTP+APPEND+sync — put a pink row
+        // into the local Sent folder right now so the user sees their letter
+        // the instant they click Send. upsertMessage's Message-ID rebind
+        // picks up the real APPENDUID later (same row, different UID).
+        // Fire-and-forget: failure here must not hold up the send ACK.
+        this.imapManager.insertOptimisticSentRow(account.id, {
+            messageId,
+            inReplyTo: msg.inReplyTo || "",
+            references: msg.references || [],
+            subject: msg.subject || "",
+            from: { name: account.name, address: fromAddr },
+            to: msg.to || [],
+            cc: msg.cc || [],
+            bcc: msg.bcc || [],
+            date: Date.now(),
+        }, rawMessage).catch(() => { /* already logged inside */ });
+        console.log(`  Queued locally: ${msg.subject} via ${account.id} from ${fromHeader}`);
+
+        // Contacts recording is off the critical path — deferred until after
+        // the IPC ACK so a slow DB write can't stall the send.
+        setImmediate(() => {
+            try {
+                for (const addr of msg.to) this.db.recordSentAddress(addr.name, addr.address);
+                if (msg.cc) for (const addr of msg.cc) this.db.recordSentAddress(addr.name, addr.address);
+                if (msg.bcc) for (const addr of msg.bcc) this.db.recordSentAddress(addr.name, addr.address);
+            } catch (e: any) {
+                console.error(`  recordSentAddress failed: ${e?.message || e}`);
+            }
+        });
+    }
+
+    // ── Delete / Move / Undelete ──
+
+    async deleteMessage(accountId: string, uid: number): Promise<void> {
+        const envelope = this.db.getMessageByUid(accountId, uid);
+        if (!envelope) throw new Error("Message not found");
+        // Tombstone the Message-ID so a subsequent sync pass can't resurrect
+        // the row if the server's EXPUNGE hasn't propagated yet. `undelete`
+        // removes the tombstone.
+        if (envelope.messageId) this.db.addTombstone(accountId, envelope.messageId, envelope.subject || "");
+        await this.imapManager.trashMessage(accountId, envelope.folderId, envelope.uid);
+    }
+
+    async deleteMessages(accountId: string, uids: number[]): Promise<void> {
+        const messages = uids.map(uid => {
+            const env = this.db.getMessageByUid(accountId, uid);
+            if (!env) return null;
+            // Tombstone each — same reason as single-delete above.
+            if (env.messageId) this.db.addTombstone(accountId, env.messageId, env.subject || "");
+            return { uid: env.uid, folderId: env.folderId };
+        }).filter(m => m !== null);
+        await this.imapManager.trashMessages(accountId, messages);
+    }
+
+    async moveMessage(accountId: string, uid: number, targetFolderId: number, targetAccountId?: string): Promise<void> {
+        const envelope = this.db.getMessageByUid(accountId, uid);
+        if (!envelope) throw new Error("Message not found");
+
+        // Update local DB immediately (local-first)
+        this.db.updateMessageFolder(accountId, uid, targetFolderId);
+        this.db.recalcFolderCounts(envelope.folderId);
+        this.db.recalcFolderCounts(targetFolderId);
+
+        // Sync to server in background
+        if (targetAccountId && targetAccountId !== accountId) {
+            this.imapManager.moveMessageCrossAccount(accountId, envelope.uid, envelope.folderId, targetAccountId, targetFolderId).catch(e => console.error(`  Move sync failed: ${e.message}`));
+        } else {
+            this.imapManager.moveMessage(accountId, envelope.uid, envelope.folderId, targetFolderId).catch(e => console.error(`  Move sync failed: ${e.message}`));
+        }
+    }
+
+    async moveMessages(accountId: string, uids: number[], targetFolderId: number): Promise<void> {
+        const messages = uids.map(uid => {
+            const env = this.db.getMessageByUid(accountId, uid);
+            if (!env) return null;
+            return { uid: env.uid, folderId: env.folderId };
+        }).filter(m => m !== null);
+
+        // Update local DB immediately
+        for (const msg of messages) {
+            if (msg) {
+                this.db.updateMessageFolder(accountId, msg.uid, targetFolderId);
+                this.db.recalcFolderCounts(msg.folderId);
+            }
+        }
+        this.db.recalcFolderCounts(targetFolderId);
+
+        // Sync to server in background
+        this.imapManager.moveMessages(accountId, messages, targetFolderId).catch(e => console.error(`  Move sync failed: ${e.message}`));
+    }
+
+    /** Move messages to the account's configured spam folder (accounts.jsonc "spam" path).
+     *  Throws if the account has no spam folder configured or the folder doesn't exist locally. */
+    async markAsSpamMessages(accountId: string, uids: number[]): Promise<{ targetFolderId: number; moved: number }> {
+        // The spam folder is whatever the provider's getSpecialFolders() said
+        // it is. iflow-direct's compat client fills this in from RFC 6154
+        // \Junk / \Spam flags (with sensible defaults if the server doesn't
+        // advertise them); Gmail has SPAM built in. mailx stores the result
+        // as `specialUse: "junk"` on the matching folder row.
+        //
+        // Earlier versions required an explicit `spam:` field in accounts.jsonc
+        // and the button erroring out when that was absent. That's obsolete —
+        // the provider knows where spam goes. Just look up the flagged folder.
+        const folders = this.db.getFolders(accountId);
+        const target = folders.find(f => f.specialUse === "junk");
+        if (!target) throw new Error(`No \\Junk/\\Spam folder found for ${accountId}`);
+        await this.moveMessages(accountId, uids, target.id);
+        return { targetFolderId: target.id, moved: uids.length };
+    }
+
+    /** Append a spam report row to `~/.mailx/spam.csv` — placeholder mechanism
+     *  per user 2026-04-23 ("let's make it smart later; no auto-delete until
+     *  safety issues are addressed"). One row per click. Columns: timestamp
+     *  (ms since epoch), ISO date, ISO time, accountId, Delivered-To, From
+     *  address, Subject, eml file path. CSV fields RFC 4180-quoted so commas
+     *  and quotes in subjects survive. No move, no flag change, no server
+     *  hit — just the log. Useful as training data for a future classifier.
+     */
+    async recordSpamReport(accountId: string, uid: number, folderId: number): Promise<{ ok: true; row: string }> {
+        const env = this.db.getMessageByUid(accountId, uid, folderId);
+        if (!env) throw new Error(`Message not found: ${accountId}/${uid}`);
+        const bodyPath = env.bodyPath || "";
+        // Prefer `body_path` (authoritative). `Delivered-To` isn't in the
+        // envelope struct, so parse from the cached `.eml` if available.
+        let deliveredTo = "";
+        if (bodyPath) {
+            try {
+                const raw = fs.readFileSync(bodyPath, "utf-8").slice(0, 4096);
+                const m = raw.match(/^Delivered-To:\s*(.+)$/mi);
+                if (m) deliveredTo = m[1].trim();
+            } catch { /* not fatal — leave blank */ }
+        }
+        const now = new Date();
+        const isoDate = now.toISOString().slice(0, 10);
+        const isoTime = now.toISOString().slice(11, 19);
+        const fromAddr = env.from?.address || "";
+        const subject = env.subject || "";
+        const csvEscape = (s: string) => `"${String(s).replace(/"/g, '""')}"`;
+        const row = [
+            String(now.getTime()),
+            csvEscape(isoDate),
+            csvEscape(isoTime),
+            csvEscape(accountId),
+            csvEscape(deliveredTo),
+            csvEscape(fromAddr),
+            csvEscape(subject),
+            csvEscape(bodyPath),
+        ].join(",") + "\n";
+        const spamCsvPath = path.join(getConfigDir(), "spam.csv");
+        // Write a header if the file doesn't exist yet so the CSV is self-describing.
+        if (!fs.existsSync(spamCsvPath)) {
+            fs.writeFileSync(spamCsvPath, "timestamp_ms,date,time,account,delivered_to,from,subject,eml_path\n", "utf-8");
+        }
+        fs.appendFileSync(spamCsvPath, row, "utf-8");
+        console.log(`  [spam] reported ${accountId}/${uid} → spam.csv`);
+        return { ok: true, row };
+    }
+
+    async undeleteMessage(accountId: string, uid: number, folderId: number): Promise<void> {
+        // Clear the tombstone first so a subsequent sync can re-import if
+        // the server still has the row. Messages with no Message-ID just
+        // didn't get a tombstone — this is a no-op for them.
+        const envelope = this.db.getMessageByUid(accountId, uid, folderId);
+        if (envelope?.messageId) this.db.removeTombstone(accountId, envelope.messageId);
+        await this.imapManager.undeleteMessage(accountId, uid, folderId);
+    }
+
+    async deleteOnServer(accountId: string, folderPath: string, uid: number): Promise<void> {
+        await this.imapManager.deleteOnServer(accountId, folderPath, uid);
+    }
+
+    // ── Folder management ──
+
+    async createFolder(accountId: string, parentPath: string, name: string): Promise<void> {
+        const fullPath = parentPath ? `${parentPath}.${name}` : name;
+        const client = await this.imapManager.createPublicClient(accountId);
+        try {
+            await client.createmailbox(fullPath);
+            await this.imapManager.syncFolders(accountId, client);
+            await client.logout();
+        } finally { try { await client.logout(); } catch { /* */ } }
+    }
+
+    async renameFolder(accountId: string, folderId: number, newName: string): Promise<void> {
+        const folder = this.db.getFolders(accountId).find(f => f.id === folderId);
+        if (!folder) throw new Error("Folder not found");
+        const parts = folder.path.split(folder.delimiter || ".");
+        parts[parts.length - 1] = newName;
+        const newPath = parts.join(folder.delimiter || ".");
+        const client = await this.imapManager.createPublicClient(accountId);
+        try {
+            if (client.renameMailbox) {
+                await client.renameMailbox(folder.path, newPath);
+            } else {
+                await (client as any).withConnection(async () => {
+                    await (client as any).client.mailboxRename(folder.path, newPath);
+                });
+            }
+            await this.imapManager.syncFolders(accountId, client);
+            await client.logout();
+        } finally { try { await client.logout(); } catch { /* */ } }
+    }
+
+    async deleteFolder(accountId: string, folderId: number): Promise<void> {
+        const folder = this.db.getFolders(accountId).find(f => f.id === folderId);
+        if (!folder) throw new Error("Folder not found");
+        const client = await this.imapManager.createPublicClient(accountId);
+        try {
+            try {
+                if (client.deleteMailbox) {
+                    await client.deleteMailbox(folder.path);
+                } else {
+                    await (client as any).withConnection(async () => {
+                        await (client as any).client.mailboxDelete(folder.path);
+                    });
+                }
+            } catch (e: any) {
+                // Server already doesn't have this folder — common case when
+                // the user deleted / renamed it from another client and mailx
+                // is still showing the stale local row. Silently treat as
+                // success and proceed with local cleanup; the user's intent
+                // ("make this go away") is met either way.
+                const msg = String(e?.message || e || "").toLowerCase();
+                const alreadyGone = /nonexistent|does not exist|no such|not found|NO \[.*\] Mailbox|404/i.test(msg);
+                if (!alreadyGone) throw e;
+                console.log(`  [folder] ${accountId} delete "${folder.path}": server says already gone — cleaning local DB`);
+            }
+            this.db.deleteFolder(folderId);
+            try { await client.logout(); } catch { /* ignore */ }
+        } finally { try { await client.logout(); } catch { /* */ } }
+    }
+
+    markFolderRead(folderId: number): void {
+        this.db.markFolderRead(folderId);
+    }
+
+    async emptyFolder(accountId: string, folderId: number): Promise<void> {
+        const folder = this.db.getFolders(accountId).find(f => f.id === folderId);
+        if (!folder) throw new Error("Folder not found");
+        this.db.deleteAllMessages(accountId, folderId);
+        // Recalc + broadcast so the folder-tree badge drops to 0 immediately.
+        // Without this, the badge kept showing the old unread count even
+        // though the list was empty (user-reported bug).
+        this.db.recalcFolderCounts(folderId);
+        try {
+            (this.imapManager as any).emit?.("folderCountsChanged", accountId, {});
+        } catch { /* non-fatal */ }
+        const client = await this.imapManager.createPublicClient(accountId);
+        try {
+            const uids = await client.getUids(folder.path);
+            for (const uid of uids) await client.deleteMessageByUid(folder.path, uid);
+            await client.logout();
+        } finally { try { await client.logout(); } catch { /* */ } }
+    }
+
+    // ── Attachments ──
+
+    async getAttachment(accountId: string, uid: number, attachmentId: number, folderId?: number): Promise<{ content: Buffer; contentType: string; filename: string }> {
+        const envelope = this.db.getMessageByUid(accountId, uid, folderId);
+        if (!envelope) throw new Error("Message not found");
+        const raw = await this.imapManager.fetchMessageBody(accountId, envelope.folderId, envelope.uid);
+        if (!raw) throw new Error("Message body not available");
+        const parsed = await simpleParser(raw);
+        const att = parsed.attachments?.[attachmentId];
+        if (!att) throw new Error("Attachment not found");
+        return {
+            content: att.content,
+            contentType: att.contentType || "application/octet-stream",
+            filename: (att.filename || "attachment").replace(/"/g, ""),
+        };
+    }
+
+    // ── Drafts ──
+
+    async saveDraft(accountId: string, subject: string, bodyHtml: string, bodyText: string, to?: string, cc?: string, previousDraftUid?: number, draftId?: string): Promise<{ draftUid: number | null; draftId: string }> {
+        // Local-first: commit the draft to the local filesystem synchronously
+        // and return immediately. The IMAP APPEND (and the previous-draft
+        // delete) run in the background. Previously this method awaited IMAP
+        // inline, which produced the 30/120s `mailxapi timeout: saveDraft`
+        // the user reported — every IMAP stall (slow server, hung OAuth,
+        // maxed connection pool) froze autosave. The local `.eml` written
+        // below is the user's crash-safety net; IMAP is a sync target, not
+        // a prerequisite. X-Mailx-Draft-ID is carried in the MIME headers
+        // so the reconciler can de-duplicate on the server by header search
+        // even without the previousDraftUid round-trip.
+        // Account lookup uses the cached list — `loadSettings()` reads
+        // accounts.jsonc from the GDrive mount and could itself stall for
+        // 120s, which was the actual `mailxapi timeout: saveDraft` source
+        // (the IMAP work was fire-and-forget, but loadSettings wasn't).
+        let account = this.getCachedAccounts().find(a => a.id === accountId);
+        if (!account) {
+            this._accountsCache = null;
+            account = this.getCachedAccounts().find(a => a.id === accountId);
+        }
+        if (!account) throw new Error(`Unknown account: ${accountId}`);
+
+        // Generate or reuse a stable draft ID for dedup
+        const id = draftId || `mailx-draft-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+        const body = bodyHtml || bodyText || "";
+        const bodyEncoded = encodeQuotedPrintable(body);
+
+        const headers = [
+            `From: ${account.name} <${account.email}>`,
+            to ? `To: ${to}` : null, cc ? `Cc: ${cc}` : null,
+            `Subject: ${subject || "(no subject)"}`, `Date: ${new Date().toUTCString()}`,
+            `X-Mailx-Draft-ID: ${id}`,
+            `MIME-Version: 1.0`, `Content-Type: text/html; charset=UTF-8`, `Content-Transfer-Encoding: quoted-printable`,
+        ].filter(h => h !== null).join("\r\n");
+        const raw = `${headers}\r\n\r\n${bodyEncoded}`;
+
+        // Local commit: write editing copy to disk. Crash recovery lives in
+        // the last 3 files. Synchronous fs (~ms) so the caller returns fast.
+        try {
+            const editingDir = path.join(getConfigDir(), "sending", accountId, "editing");
+            fs.mkdirSync(editingDir, { recursive: true });
+            const pad2 = (n: number) => String(n).padStart(2, "0");
+            const now = new Date();
+            const ts = `${now.getFullYear()}${pad2(now.getMonth() + 1)}${pad2(now.getDate())}_${pad2(now.getHours())}${pad2(now.getMinutes())}${pad2(now.getSeconds())}`;
+            fs.writeFileSync(path.join(editingDir, `${ts}.eml`), raw);
+            // Keep only last 3
+            const files = fs.readdirSync(editingDir).filter(f => f.endsWith(".eml")).sort();
+            while (files.length > 3) {
+                fs.unlinkSync(path.join(editingDir, files.shift()!));
+            }
+        } catch { /* non-fatal — draft stays in memory at least */ }
+
+        // Background reconcile to server Drafts folder. Fire-and-forget —
+        // the ACK to the client is already on its way.
+        this.imapManager.saveDraft(accountId, raw, previousDraftUid, id).catch((e: any) => {
+            console.error(`  [draft] background IMAP save failed for ${id}: ${e?.message || e}`);
+            // Surface as an event so the UI can show a status-bar hint without
+            // blocking the caller. Draft is preserved on disk regardless.
+            (this as any).emit?.("draftSaveDeferred", { accountId, draftId: id, error: String(e?.message || e) });
+        });
+
+        return { draftUid: null, draftId: id };
+    }
+
+    async deleteDraft(accountId: string, draftUid: number, draftId?: string): Promise<void> {
+        await this.imapManager.deleteDraft(accountId, draftUid, draftId);
+    }
+
+    // ── Contacts ──
+
+    searchContacts(query: string): any[] {
+        query = (query || "").trim();
+        if (query.length < 1) return [];
+        return this.db.searchContacts(query);
+    }
+
+    /** Q49: boolean hint for compose to auto-expand Cc when replying to this
+     *  address. True when at least one past sent message to the same recipient
+     *  had a non-empty Cc field. */
+    hasCcHistoryTo(email: string): boolean {
+        return this.db.hasCcHistoryTo(email);
+    }
+
+    /** Q49: same shape, for Bcc. Sent folder is the only place Bcc appears,
+     *  so the signal is local-only but still reflects the user's habit. */
+    hasBccHistoryTo(email: string): boolean {
+        return this.db.hasBccHistoryTo(email);
+    }
+
+    async syncGoogleContacts(): Promise<void> {
+        await this.imapManager.syncAllContacts();
+    }
+
+    seedContacts(): number {
+        const added = this.db.seedContactsFromMessages();
+        console.log(`  Seeded ${added} contacts from message history`);
+        return added;
+    }
+
+    /** Explicit add to address book — used by the right-click "Add to contacts"
+     *  action on From/To/Cc addresses in the message viewer. Just calls the same
+     *  validated upsert path as recordSentAddress. */
+    addContact(name: string, email: string): boolean {
+        if (!email || !/^[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+$/.test(email)) return false;
+        this.db.recordSentAddress(name || "", email);
+        return true;
+    }
+
+    /** Address-book listing — paginated, filterable. */
+    listContacts(query: string, page = 1, pageSize = 100): any {
+        return this.db.listContacts(query || "", page, pageSize);
+    }
+
+    /** Upsert a contact from the address book UI (edit name). Two-way cache:
+     *  commits locally, queues a Google People push. */
+    upsertContact(name: string, email: string): { ok: true } {
+        this.db.upsertContact(name || "", email);
+        const acct = this.getPrimaryAccount("contacts");
+        if (acct) {
+            // Google People `createContact` — resourceName is assigned by the
+            // server and stored back as google_id once the drainer gets an ACK.
+            this.db.enqueueStoreSync("contacts", "create", acct.id, email, {
+                names: [{ givenName: name || "" }],
+                emailAddresses: [{ value: email }],
+            });
+            this.drainStoreSync().catch(() => { /* retried on next tick */ });
+        }
+        return { ok: true };
+    }
+
+    /** Delete a contact from the address book. Also pushes the deletion to
+     *  Google People if the contact had a resourceName (i.e. was synced). */
+    deleteContact(email: string): { ok: true } {
+        const acct = this.getPrimaryAccount("contacts");
+        // Look up the resourceName before deleting so we can push to Google.
+        const contacts = this.db.listContacts("", 1, 10_000) as any;
+        const contact = (contacts.items || []).find((c: any) => c.email === email);
+        this.db.deleteContactLocal(email);
+        if (acct && contact?.googleId) {
+            this.db.enqueueStoreSync("contacts", "delete", acct.id, email, {
+                resourceName: contact.googleId,
+            });
+            this.drainStoreSync().catch(() => { /* */ });
+        }
+        return { ok: true };
+    }
+
+    /** Open a configured local path in the OS file explorer. Whitelisted to
+     *  avoid the UI poking at arbitrary paths. */
+    async openLocalPath(which: "config" | "log"): Promise<{ ok: true; path: string }> {
+        const dir = getConfigDir();
+        let target = dir;
+        if (which === "log") {
+            const today = new Date();
+            const pad = (n: number) => String(n).padStart(2, "0");
+            const fname = `mailx-${today.getFullYear()}-${pad(today.getMonth() + 1)}-${pad(today.getDate())}.log`;
+            target = path.join(dir, "logs", fname);
+        }
+        const { spawn } = await import("child_process");
+        const cmd = process.platform === "win32" ? "explorer"
+            : process.platform === "darwin" ? "open"
+            : "xdg-open";
+        const args = process.platform === "win32" && which === "log"
+            ? ["/select,", target]
+            : [target];
+        spawn(cmd, args, { detached: true, stdio: "ignore", windowsHide: true }).unref();
+        return { ok: true, path: target };
+    }
+
+    /** Get all messages in a thread (across folders) for an account. */
+    getThreadMessages(accountId: string, threadId: string): any {
+        return this.db.getThreadMessages(accountId, threadId);
+    }
+
+    /** Read a JSONC config file from the shared cloud dir or local ~/.mailx.
+     *  Names are whitelisted so the UI can't read arbitrary files.
+     *  `config.jsonc` is the local per-machine config (not cloud-synced). */
+    async readJsoncFile(name: string): Promise<string | null> {
+        const WHITELIST = ["accounts.jsonc", "allowlist.jsonc", "clients.jsonc", "config.jsonc", "contacts.jsonc"];
+        if (!WHITELIST.includes(name)) throw new Error(`File not allowed: ${name}`);
+        if (name === "config.jsonc") {
+            const configPath = path.join(getConfigDir(), "config.jsonc");
+            try { return fs.readFileSync(configPath, "utf-8"); } catch { return null; }
+        }
+        const { cloudRead } = await import("@bobfrankston/mailx-settings");
+        return cloudRead(name);
+    }
+
+    // Reformat JSONC preserving comments — applyEdits returns whitespace-only edits.
+    async formatJsonc(content: string): Promise<string> {
+        const { format, applyEdits } = await import("jsonc-parser");
+        const edits = format(content, undefined, {
+            tabSize: 2,
+            insertSpaces: true,
+            eol: "\n",
+            insertFinalNewline: true,
+        });
+        return applyEdits(content, edits);
+    }
+
+    /** Return the help section for a named config file, extracted from docs/config-help.md.
+     *  Matches a level-2 heading whose text equals the filename. Returns markdown. */
+    async readConfigHelp(name: string): Promise<string> {
+        const WHITELIST = ["accounts.jsonc", "allowlist.jsonc", "clients.jsonc", "config.jsonc", "contacts.jsonc"];
+        if (!WHITELIST.includes(name)) return "";
+        // Look in the repo root (dev) and in the installed package dir (production).
+        const candidates = [
+            path.join(__dirname, "..", "..", "docs", "config-help.md"),
+            path.join(__dirname, "config-help.md"),
+        ];
+        let md = "";
+        for (const p of candidates) {
+            try { md = fs.readFileSync(p, "utf-8"); break; } catch { /* try next */ }
+        }
+        if (!md) return "";
+        const lines = md.split(/\r?\n/);
+        let inSection = false;
+        const out: string[] = [];
+        for (const line of lines) {
+            const h2 = /^##\s+(.+?)\s*$/.exec(line);
+            if (h2) {
+                if (inSection) break; // next section — stop
+                if (h2[1].trim() === name) { inSection = true; continue; }
+            }
+            if (inSection) out.push(line);
+        }
+        return out.join("\n").trim();
+    }
+
+    /** Write a JSONC config file. Validates that the content parses as JSONC
+     *  (loosely — strips comments/trailing commas) before writing.
+     *  Saves the prior content to a dated backup file first — manual edits
+     *  occasionally have typos that survive validation (semantically wrong
+     *  but syntactically OK), and a one-key undo isn't enough; the user
+     *  asked to be able to recover yesterday's accounts.jsonc. Automatic
+     *  saveAccounts/saveAllowlist paths skip backups (they're driven by
+     *  trusted code, not the JSONC editor). */
+    async writeJsoncFile(name: string, content: string): Promise<void> {
+        const WHITELIST = ["accounts.jsonc", "allowlist.jsonc", "clients.jsonc", "config.jsonc", "contacts.jsonc"];
+        if (!WHITELIST.includes(name)) throw new Error(`File not allowed: ${name}`);
+        // Validate the content parses before writing
+        const { parse: parseJsonc } = await import("jsonc-parser");
+        const errors: any[] = [];
+        parseJsonc(content, errors, { allowTrailingComma: true });
+        if (errors.length) {
+            throw new Error(`JSONC parse error: ${errors.map(e => e.error).join(", ")}`);
+        }
+        const previous = await this.readJsoncForBackup(name);
+        await this.backupJsoncIfChanged(name, previous, content);
+        if (name === "config.jsonc") {
+            const configPath = path.join(getConfigDir(), "config.jsonc");
+            fs.writeFileSync(configPath, content);
+            return;
+        }
+        const { cloudWrite } = await import("@bobfrankston/mailx-settings");
+        await cloudWrite(name, content); // throws on failure with descriptive error
+    }
+
+    /** Read the current content of a config file (cloud or local) so it can
+     *  be saved as a backup before being overwritten. Returns null if the
+     *  file doesn't exist yet (first save — nothing to back up). */
+    private async readJsoncForBackup(name: string): Promise<string | null> {
+        if (name === "config.jsonc") {
+            const configPath = path.join(getConfigDir(), "config.jsonc");
+            try { return fs.readFileSync(configPath, "utf-8"); } catch { return null; }
+        }
+        try {
+            const { cloudRead } = await import("@bobfrankston/mailx-settings");
+            return await cloudRead(name);
+        } catch { return null; }
+    }
+
+    /** Write the prior content to `<configDir>/backup/<name>.<ts>.bak` and
+     *  prune so at most 10 backups per file remain AND none are older than 7
+     *  days. Skipped when previous content is null (first write) or
+     *  identical to the new content (no-op save). */
+    private async backupJsoncIfChanged(name: string, previous: string | null, next: string): Promise<void> {
+        if (previous == null || previous === next) return;
+        const backupDir = path.join(getConfigDir(), "backup");
+        try { fs.mkdirSync(backupDir, { recursive: true }); } catch { /* */ }
+        // Filename-safe ISO timestamp (colons become hyphens on Windows).
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const backupPath = path.join(backupDir, `${name}.${stamp}.bak`);
+        try { fs.writeFileSync(backupPath, previous); }
+        catch (e: any) {
+            console.error(`[backup] failed to write ${backupPath}: ${e.message}`);
+            return; // don't block the save just because backup failed
+        }
+        // Prune: keep at most 10 most-recent for this filename, drop anything
+        // older than 7 days. Whichever cuts more wins.
+        const MAX_KEEP = 10;
+        const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+        const now = Date.now();
+        let entries: { path: string; mtime: number }[];
+        try {
+            entries = fs.readdirSync(backupDir)
+                .filter(f => f.startsWith(`${name}.`) && f.endsWith(".bak"))
+                .map(f => {
+                    const p = path.join(backupDir, f);
+                    return { path: p, mtime: fs.statSync(p).mtimeMs };
+                })
+                .sort((a, b) => b.mtime - a.mtime); // newest first
+        } catch { return; }
+        for (let i = 0; i < entries.length; i++) {
+            const tooOld = now - entries[i].mtime > MAX_AGE_MS;
+            const tooMany = i >= MAX_KEEP;
+            if (tooOld || tooMany) {
+                try { fs.unlinkSync(entries[i].path); } catch { /* */ }
+            }
+        }
+    }
+
+    // ── Settings ──
+
+    getSettings(): any {
+        return loadSettings();
+    }
+
+    saveSettings(settings: any): void {
+        saveSettings(settings);
+    }
+
+    getStorageInfo(): { provider: string; mode: string } {
+        return getStorageInfo();
+    }
+
+    // ── Setup & Repair ──
+
+    async setupAccount(name: string, email: string, password?: string): Promise<{ ok: boolean; error?: string; message?: string }> {
+        if (!email) return { ok: false, error: "Email address required" };
+        const domain = email.split("@")[1]?.toLowerCase() || "";
+        const detected = await detectEmailProvider(domain);
+        if (detected?.cloud) {
+            await initCloudConfig(detected.cloud);
+        }
+        // Check cloud for existing accounts — if found, just load them all
+        let accounts = loadAccounts();
+        if (accounts.length === 0) {
+            accounts = await loadAccountsAsync();
+        }
+        if (accounts.length > 0) {
+            // Existing accounts found on cloud — use them directly
+            console.log(`  Found ${accounts.length} existing account(s) from cloud settings`);
+            const settings = loadSettings();
+            for (const acct of settings.accounts) {
+                if (!acct.enabled) continue;
+                try {
+                    await this.imapManager.addAccount(acct);
+                    console.log(`  Account loaded: ${acct.label || acct.name} (${acct.id})`);
+                } catch (e: any) {
+                    console.error(`  Account ${acct.id} error: ${e.message}`);
+                }
+            }
+            this.imapManager.syncAll().catch(() => {});
+            return { ok: true, message: `Loaded ${accounts.length} existing account(s) from cloud.` };
+        }
+        // No existing accounts — create new one
+        const isGoogle = ["gmail.com", "googlemail.com"].includes(domain) || detected?.cloud === "gdrive";
+        const isOAuth = ["gmail.com", "googlemail.com", "outlook.com", "hotmail.com", "live.com"].includes(domain);
+
+        const account: any = { email, name: name || email.split("@")[0] };
+        if (password) account.password = password;
+        if (detected && !isOAuth) {
+            account.imap = { host: detected.imapHost, port: 993, tls: true, auth: detected.auth, user: email };
+            account.smtp = { host: detected.smtpHost, port: 587, tls: true, auth: detected.auth, user: email };
+        }
+        account.id = domain.split(".")[0] || "account";
+
+        // Save provisional account so addAccount can register it. Cloud failures
+        // surface via onCloudError listeners (UI banner) — don't fail setup itself.
+        try {
+            await saveAccounts([account]);
+        } catch (e: any) {
+            console.error(`  [setup] saveAccounts failed: ${e.message}`);
+            return { ok: false, error: `Failed to save account: ${e.message}` };
+        }
+        // Re-read normalized settings and register
+        let settings = loadSettings();
+        for (const acct of settings.accounts) {
+            if (!acct.enabled) continue;
+            try {
+                await this.imapManager.addAccount(acct);
+                console.log(`  Account loaded: ${acct.label || acct.name} (${acct.id})`);
+            } catch (e: any) {
+                console.error(`  Account ${acct.id} error: ${e.message}`);
+            }
+        }
+        // For Google accounts where the user didn't supply a name, fetch the
+        // display name from the People API now that addAccount has authenticated.
+        // contacts.readonly is in the Gmail OAuth scope, so the same token works.
+        if (!name && isGoogle) {
+            try {
+                const tok = await this.imapManager.getOAuthToken(account.id);
+                if (tok) {
+                    const { getGoogleProfile } = await import("@bobfrankston/mailx-settings/cloud.js");
+                    const profile = await getGoogleProfile(tok);
+                    if (profile?.name && profile.name !== account.name) {
+                        console.log(`  [setup] Display name from Google: ${profile.name}`);
+                        account.name = profile.name;
+                        // Re-save with the resolved name (best-effort; cloud errors
+                        // surface via onCloudError).
+                        try { await saveAccounts([account]); } catch (e: any) {
+                            console.error(`  [setup] re-saveAccounts with profile name failed: ${e.message}`);
+                        }
+                        settings = loadSettings();
+                    }
+                }
+            } catch (e: any) {
+                console.error(`  [setup] getGoogleProfile failed: ${e.message}`);
+            }
+        }
+        this.imapManager.syncAll().catch(() => {});
+        return { ok: true, message: `${settings.accounts.length} account(s) configured and syncing.` };
+    }
+
+    async repairAccounts(): Promise<{ ok: boolean; error?: string; message?: string }> {
+        const dbAccounts = this.db.getAccountConfigs();
+        if (dbAccounts.length === 0) {
+            return { ok: false, error: "No cached accounts in database" };
+        }
+        const restored: AccountConfig[] = [];
+        for (const a of dbAccounts) {
+            try { restored.push(JSON.parse(a.configJson)); }
+            catch { /* skip corrupt */ }
+        }
+        if (restored.length === 0) {
+            return { ok: false, error: "Could not parse cached account configs" };
+        }
+        await saveAccounts(restored);
+        for (const acct of restored) {
+            try {
+                await this.imapManager.addAccount(acct);
+                console.log(`  [repair] Re-registered account: ${acct.name} (${acct.id})`);
+            } catch (e: any) {
+                console.error(`  [repair] Failed to register ${acct.id}: ${e.message}`);
+            }
+        }
+        this.imapManager.syncAll().catch(() => {});
+        return { ok: true, message: `Restored ${restored.length} account(s) and started sync.` };
+    }
+
+    // ── Autocomplete ──
+
+    getAutocompleteSettings(): AutocompleteSettings {
+        return loadAutocomplete();
+    }
+
+    saveAutocompleteSettings(settings: AutocompleteSettings): void {
+        saveAutocomplete(settings);
+    }
+
+    async autocomplete(req: AutocompleteRequest): Promise<AutocompleteResponse> {
+        const acConfig = loadAutocomplete();
+        if (!acConfig.enabled || acConfig.provider === "off") {
+            return { suggestion: "" };
+        }
+
+        const bodyText = req.bodyText || "";
+        const prompt = `You are an email writing assistant. Complete the following email naturally.\nOutput ONLY the completion text — no explanation, no greeting repeat.\nKeep it to 1-2 sentences max.\n\nTo: ${req.to || ""}\nSubject: ${req.subject || ""}\n\n${bodyText}`;
+
+        try {
+            if (acConfig.provider === "ollama") {
+                const truncated = bodyText.slice(-500);
+                const ollamaPrompt = prompt.replace(bodyText, truncated);
+                const res = await fetch(`${acConfig.ollamaUrl}/api/generate`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({
+                        model: acConfig.ollamaModel,
+                        prompt: ollamaPrompt,
+                        stream: false,
+                        options: { num_predict: acConfig.maxTokens },
+                    }),
+                });
+                if (!res.ok) return { suggestion: "" };
+                const data = await res.json() as any;
+                return { suggestion: trimSuggestion(data.response || "") };
+            }
+
+            if (acConfig.provider === "claude") {
+                const res = await fetch("https://api.anthropic.com/v1/messages", {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        "x-api-key": acConfig.cloudApiKey,
+                        "anthropic-version": "2023-06-01",
+                    },
+                    body: JSON.stringify({
+                        model: acConfig.cloudModel,
+                        max_tokens: acConfig.maxTokens,
+                        messages: [{ role: "user", content: prompt }],
+                    }),
+                });
+                if (!res.ok) return { suggestion: "" };
+                const data = await res.json() as any;
+                const text = data.content?.[0]?.text || "";
+                return { suggestion: trimSuggestion(text) };
+            }
+
+            if (acConfig.provider === "openai") {
+                const res = await fetch("https://api.openai.com/v1/chat/completions", {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        "Authorization": `Bearer ${acConfig.cloudApiKey}`,
+                    },
+                    body: JSON.stringify({
+                        model: acConfig.cloudModel,
+                        max_tokens: acConfig.maxTokens,
+                        messages: [
+                            { role: "system", content: "You are an email writing assistant. Output ONLY the completion text." },
+                            { role: "user", content: prompt },
+                        ],
+                    }),
+                });
+                if (!res.ok) return { suggestion: "" };
+                const data = await res.json() as any;
+                const text = data.choices?.[0]?.message?.content || "";
+                return { suggestion: trimSuggestion(text) };
+            }
+        } catch (e: any) {
+            console.error(`  [autocomplete] ${acConfig.provider} error: ${e.message}`);
+        }
+
+        return { suggestion: "" };
+    }
+
+    /** Generic AI text transform — translate / proofread / summarize.
+     *  Shares the autocomplete provider config (provider, key, model). Each
+     *  feature has its own opt-in toggle (translateEnabled / proofreadEnabled),
+     *  default false. Returns empty text + reason when disabled or on error. */
+    async aiTransform(req: AiTransformRequest): Promise<AiTransformResponse> {
+        const cfg = loadAutocomplete();
+        if (cfg.provider === "off") return { text: "", reason: "AI provider not configured" };
+
+        const featureGate: Record<string, boolean | undefined> = {
+            translate: cfg.translateEnabled,
+            proofread: cfg.proofreadEnabled,
+            summarize: cfg.proofreadEnabled, // bundled with proofread for now
+        };
+        if (!featureGate[req.action]) return { text: "", reason: `AI ${req.action} disabled in settings` };
+
+        const text = (req.text || "").slice(0, 8000); // sanity cap
+        if (!text.trim()) return { text: "", reason: "no input" };
+
+        const target = req.targetLang || "en";
+        let systemPrompt: string;
+        let userPrompt: string;
+        switch (req.action) {
+            case "translate":
+                systemPrompt = `You are a translator. Render the user's text into ${target}. Preserve formatting (paragraphs, lists). Output ONLY the translation, no explanation.`;
+                userPrompt = text;
+                break;
+            case "proofread":
+                systemPrompt = `You are an editor. Return the user's text with grammar, spelling, and clarity fixed. Preserve voice and meaning. Output ONLY the corrected text, no explanation.`;
+                userPrompt = text;
+                break;
+            case "summarize":
+                systemPrompt = `You are a summarizer. Render the user's text as a short paragraph (2-4 sentences). Output ONLY the summary.`;
+                userPrompt = text;
+                break;
+        }
+
+        try {
+            if (cfg.provider === "ollama") {
+                const res = await fetch(`${cfg.ollamaUrl}/api/generate`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({
+                        model: cfg.ollamaModel,
+                        prompt: `${systemPrompt}\n\n${userPrompt}`,
+                        stream: false,
+                        options: { num_predict: 1024 },
+                    }),
+                });
+                if (!res.ok) return { text: "", reason: `ollama ${res.status}` };
+                const data = await res.json() as any;
+                return { text: (data.response || "").trim() };
+            }
+            if (cfg.provider === "claude") {
+                const res = await fetch("https://api.anthropic.com/v1/messages", {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        "x-api-key": cfg.cloudApiKey,
+                        "anthropic-version": "2023-06-01",
+                    },
+                    body: JSON.stringify({
+                        model: cfg.cloudModel,
+                        max_tokens: 2048,
+                        system: systemPrompt,
+                        messages: [{ role: "user", content: userPrompt }],
+                    }),
+                });
+                if (!res.ok) return { text: "", reason: `claude ${res.status}` };
+                const data = await res.json() as any;
+                return { text: (data.content?.[0]?.text || "").trim() };
+            }
+            if (cfg.provider === "openai") {
+                const res = await fetch("https://api.openai.com/v1/chat/completions", {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        "Authorization": `Bearer ${cfg.cloudApiKey}`,
+                    },
+                    body: JSON.stringify({
+                        model: cfg.cloudModel,
+                        max_tokens: 2048,
+                        messages: [
+                            { role: "system", content: systemPrompt },
+                            { role: "user", content: userPrompt },
+                        ],
+                    }),
+                });
+                if (!res.ok) return { text: "", reason: `openai ${res.status}` };
+                const data = await res.json() as any;
+                return { text: (data.choices?.[0]?.message?.content || "").trim() };
+            }
+        } catch (e: any) {
+            console.error(`  [aiTransform] ${cfg.provider} ${req.action} error: ${e.message}`);
+            return { text: "", reason: e.message };
+        }
+        return { text: "", reason: "no provider matched" };
+    }
+}
+
+/** Trim suggestion: remove leading/trailing whitespace, cap at sentence boundary */
+function trimSuggestion(text: string): string {
+    let s = text.trim();
+    if (!s) return "";
+    // Cap at 2 sentences
+    const sentences = s.match(/[^.!?]*[.!?]/g);
+    if (sentences && sentences.length > 2) {
+        s = sentences.slice(0, 2).join("").trim();
+    }
+    return s;
+}