@rubytech/create-maxy-code 0.1.357 → 0.1.359

package/payload/platform/plugins/email/mcp/dist/lib/imap.js

@@ -1,5 +1,6 @@
 import { ImapFlow } from "imapflow";
-import { trackProbe, releaseProbe, newProbeToken } from "./setup-probe.js";
+import { simpleParser } from "mailparser";
+import { trackProbe, releaseProbe, newProbeToken, containProbeSocket } from "./setup-probe.js";
 const CONNECT_TIMEOUT = 10_000;
 const COMMAND_TIMEOUT = 30_000;
 /** Diagnostic logging to stderr (captured by claude-agent-stderr log on Pi) */
@@ -22,6 +23,61 @@ async function safeLogout(client) {
         catch { /* best effort */ }
     }
 }
+// ─── Transient transport-error retry for draft write cycles ─────────
+// Gmail occasionally drops connect/append/expunge mid-flight ("Unexpected
+// close", "Socket timeout", "Connection not available"). One drop should not
+// fail an entire draft edit. These are the only signatures retried; auth and
+// every other permanent error surface on the first occurrence.
+const TRANSIENT_ERROR_PATTERNS = [
+    "Socket timeout",
+    "Unexpected close",
+    "Connection not available",
+    "ETIMEDOUT",
+    "ECONNRESET",
+];
+/**
+ * Classify a transport error for retry. Returns the matched transient signature,
+ * or null when the error is permanent (auth/login) or otherwise not a known
+ * transient drop. Auth failures are screened out explicitly so a wrong password
+ * is never retried.
+ */
+function transientClass(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("AUTHENTICATIONFAILED") ||
+        msg.includes("Invalid credentials") ||
+        msg.includes("LOGIN failed")) {
+        return null;
+    }
+    return TRANSIENT_ERROR_PATTERNS.find((p) => msg.includes(p)) ?? null;
+}
+/**
+ * Run a draft IMAP write cycle with a bounded retry that fires only for
+ * transient transport drops. `fn` opens its own client, so each attempt gets a
+ * fresh connection. At most two attempts: a single transient drop is absorbed;
+ * a persistent one (or any permanent error) is thrown.
+ *
+ * Atomicity note: the replace cycle appends before it expunges, so if a drop
+ * lands after the append the retry can leave two replacement copies. Two copies
+ * is the deliberate trade — it preserves the "never zero copies" contract that
+ * a lost reply would otherwise violate. The per-attempt log line marks when a
+ * retry re-ran a write cycle.
+ */
+async function withTransientRetry(op, fn) {
+    const MAX_ATTEMPTS = 2;
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            const cls = transientClass(err);
+            if (attempt < MAX_ATTEMPTS && cls) {
+                diag(op, "retry", `attempt=${attempt}/${MAX_ATTEMPTS} reason=${cls}`);
+                continue;
+            }
+            throw err;
+        }
+    }
+}
 // ─── Hard cap for tool-layer limit enforcement ──────────────────────
 export const MAX_LIMIT = 50;
 /**
@@ -80,10 +136,33 @@ export function stripHtml(html) {
         .replace(/\s+/g, " ")
         .trim();
 }
-/** Max bytes to fetch per message body (4KB is plenty for a 500-char preview). */
-const BODY_MAX_BYTES = 4096;
 /** Max characters for body preview in tool output. */
 const BODY_PREVIEW_LENGTH = 500;
+/**
+ * Decode the readable text body of a raw RFC822 message with mailparser.
+ *
+ * Handles every MIME shape — flat text, single-part HTML, multipart/alternative,
+ * and nested multipart/related|mixed (Outlook's inline-image house style) — plus
+ * all transfer encodings and non-UTF-8 charsets. Returns the plain-text part when
+ * present, else the HTML part stripped to text, else the "(body unavailable)"
+ * sentinel. Never truncates; callers cap previews with previewBody.
+ */
+export async function extractBody(source) {
+    const parsed = await simpleParser(source);
+    const text = parsed.text?.trim();
+    if (text)
+        return { body: text, kind: "text" };
+    const html = parsed.html ? stripHtml(parsed.html).trim() : "";
+    if (html)
+        return { body: html, kind: "html" };
+    return { body: "(body unavailable)", kind: "none" };
+}
+/** Cap a body to BODY_PREVIEW_LENGTH for list/triage output, appending an ellipsis. */
+export function previewBody(body) {
+    return body.length > BODY_PREVIEW_LENGTH
+        ? body.slice(0, BODY_PREVIEW_LENGTH) + "…"
+        : body;
+}
 /** Hard cap on a single attachment's bytes — over this size, metadata is surfaced
  *  but bytes are not downloaded. Matches typical provider send limits. */
 export const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
@@ -221,105 +300,99 @@ export async function fetchAttachmentBytesForMessages(config, password, requests
     return results;
 }
 /**
- * Decode a raw IMAP body part buffer according to its transfer encoding.
- * Returns a UTF-8 string. Falls back to raw UTF-8 for unknown encodings.
- */
-export function decodeBodyPart(buf, encoding) {
-    const enc = encoding?.toLowerCase().trim();
-    if (!enc || enc === "7bit" || enc === "8bit" || enc === "binary") {
-        return buf.toString("utf-8");
-    }
-    if (enc === "base64") {
-        return Buffer.from(buf.toString("ascii").replace(/\s/g, ""), "base64").toString("utf-8");
-    }
-    if (enc === "quoted-printable") {
-        return buf
-            .toString("ascii")
-            .replace(/=\r?\n/g, "")
-            .replace(/=([0-9A-Fa-f]{2})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
-    }
-    // Unknown encoding — best-effort UTF-8
-    return buf.toString("utf-8");
-}
-/**
- * Extract a text body preview from a fetched message's inline bodyParts + bodyStructure.
+ * Classify an IMAP probe error by its structured fields, falling back to message
+ * strings only where no structured field carries the signal.
  *
- * Determines the content type and transfer encoding of part "1" from
- * bodyStructure (single-part: structure itself, multipart: first childNode).
- * Skips non-text parts and multipart containers. Strips HTML. Truncates
- * to BODY_PREVIEW_LENGTH characters.
+ * The auth case is why this exists: ImapFlow reports an authentication rejection
+ * as a generic `Error("Command failed")` and carries the real signal in
+ * `authenticationFailed` / `serverResponseCode` / `responseText` (set by
+ * imapflow's login.js / authenticate.js), none of which appear in `err.message`.
+ * The transport cases (refused/not-found/timeout) carry `err.code` from Node's
+ * socket layer; TLS errors carry a cert/TLS/SSL marker in code or message.
  */
-export function extractBodyFromFetch(msg) {
-    const buf = msg.bodyParts?.get("1");
-    if (!buf || buf.length === 0)
-        return "(body unavailable)";
-    const structure = msg.bodyStructure;
-    if (!structure)
-        return "(body unavailable)";
-    // Determine content type and encoding for IMAP part "1":
-    // - Single-part message: bodyStructure itself describes the body
-    // - Multipart message: first childNode describes part "1"
-    let type;
-    let encoding;
-    if (structure.childNodes && structure.childNodes.length > 0) {
-        const firstChild = structure.childNodes[0];
-        type = firstChild.type?.toLowerCase();
-        encoding = firstChild.encoding;
+export function classifyImapError(err) {
+    const e = (err ?? {});
+    const message = typeof e.message === "string" ? e.message : String(err);
+    const code = typeof e.code === "string" ? e.code : "";
+    const serverCode = typeof e.serverResponseCode === "string" ? e.serverResponseCode : "";
+    const responseText = typeof e.responseText === "string" ? e.responseText : "";
+    // Order: structured/code signals beat fuzzy message strings. Auth's structured
+    // fields are unambiguous and come first. The code-bearing transport cases are
+    // checked before the message-only TLS and auth fallbacks, so a timeout/refusal
+    // whose OS message embeds a hostname containing "ssl"/"tls"/"authentication"
+    // is not stolen by a later substring match.
+    if (e.authenticationFailed === true || serverCode === "AUTHENTICATIONFAILED")
+        return "auth";
+    if (code === "ECONNREFUSED" || message.includes("ECONNREFUSED"))
+        return "refused";
+    if (code === "ENOTFOUND" || message.includes("ENOTFOUND"))
+        return "not-found";
+    if (code === "ETIMEDOUT" || code === "CONNECT_TIMEOUT" || code === "GREETING_TIMEOUT")
+        return "timeout";
+    // TLS errors carry a cert/TLS/SSL marker in the code (e.g. CERT_HAS_EXPIRED,
+    // ERR_TLS_*) or the message; checked on code first, message second.
+    if (/cert|TLS|SSL/i.test(`${code} ${message}`))
+        return "tls";
+    // Message-only fallbacks for errors that arrived without a structured field —
+    // last resort, after every code-based case above.
+    if (/AUTHENTICATIONFAILED|Invalid credentials|LOGIN failed|Authentication failed/i.test(`${message} ${responseText}`))
+        return "auth";
+    if (/ETIMEDOUT|timed?\s?out/i.test(message))
+        return "timeout";
+    return "unknown";
+}
+/** Map a classified failure to the operator-actionable message. */
+function imapFailureMessage(kind, config, err) {
+    switch (kind) {
+        case "auth":
+            return `IMAP authentication failed for ${config.email}. Check the password — most providers require an app-specific password when 2FA is enabled.`;
+        case "refused":
+            return `IMAP connection refused at ${config.imapHost}:${config.imapPort}. Check that IMAP is enabled in your email provider settings.`;
+        case "not-found":
+            return `IMAP host ${config.imapHost} not found. Check the hostname.`;
+        case "tls":
+            return `IMAP TLS error connecting to ${config.imapHost}:${config.imapPort}. Try port 993 (TLS) or 143 (STARTTLS).`;
+        case "timeout":
+            return `IMAP connection timed out to ${config.imapHost}:${config.imapPort}. Check the host and port.`;
+        default:
+            return `IMAP connection failed: ${err instanceof Error ? err.message : String(err)}`;
     }
-    else {
-        type = structure.type?.toLowerCase();
-        encoding = structure.encoding;
-    }
-    // Skip non-text content (binary attachments, images, nested multipart containers)
-    if (!type || !type.startsWith("text/"))
-        return "(body unavailable)";
-    let text = decodeBodyPart(buf, encoding);
-    if (type === "text/html") {
-        text = stripHtml(text);
-    }
-    text = text.trim();
-    if (!text)
-        return "(body unavailable)";
-    return text.length > BODY_PREVIEW_LENGTH
-        ? text.slice(0, BODY_PREVIEW_LENGTH) + "\u2026"
-        : text;
 }
 /**
  * Test IMAP connectivity and authentication.
  * Returns null on success, error message on failure.
+ *
+ * Emits one structured attempt line per probe (host/port/security/outcome/reason,
+ * no secret) so a failing setup is visible server-side without opening the session
+ * transcript.
  */
 export async function testConnection(config, password, token = newProbeToken()) {
     const client = createClient(config, password);
     trackProbe("imap", client, token);
+    const attempt = (outcome, reason) => {
+        process.stderr.write(`[email] imap-attempt host=${config.imapHost} port=${config.imapPort} security=${config.imapSecurity} outcome=${outcome} reason=${reason}\n`);
+    };
     try {
         await client.connect();
+        // Socket is live once connect resolves — contain a late socket 'error' that
+        // could fire during logout/teardown.
+        containProbeSocket(client, "imap", token);
         await safeLogout(client);
+        attempt("ok", "none");
         return null;
     }
     catch (err) {
-        // Never abandon the client: an unlistened half-established TLS socket
-        // emitting a late 'error' kills the process.
+        // On the auth-reject path ImapFlow leaves the socket live; contain it before
+        // close() removes ImapFlow's own forwarder, so a late socket 'error' cannot
+        // escape as an uncaughtException once the census has returned to baseline.
+        containProbeSocket(client, "imap", token);
         try {
             client.close();
         }
         catch { /* contained */ }
-        const msg = err instanceof Error ? err.message : String(err);
-        if (msg.includes("AUTHENTICATIONFAILED") || msg.includes("Invalid credentials") || msg.includes("LOGIN failed")) {
-            return `IMAP authentication failed for ${config.email}. Check the password — most providers require an app-specific password when 2FA is enabled.`;
-        }
-        if (msg.includes("ECONNREFUSED")) {
-            return `IMAP connection refused at ${config.imapHost}:${config.imapPort}. Check that IMAP is enabled in your email provider settings.`;
-        }
-        if (msg.includes("ENOTFOUND")) {
-            return `IMAP host ${config.imapHost} not found. Check the hostname.`;
-        }
-        if (msg.includes("certificate") || msg.includes("TLS") || msg.includes("SSL")) {
-            return `IMAP TLS error connecting to ${config.imapHost}:${config.imapPort}. Try port 993 (TLS) or 143 (STARTTLS).`;
-        }
-        if (msg.includes("ETIMEDOUT") || msg.includes("timeout")) {
-            return `IMAP connection timed out to ${config.imapHost}:${config.imapPort}. Check the host and port.`;
-        }
-        return `IMAP connection failed: ${msg}`;
+        const kind = classifyImapError(err);
+        attempt("fail", kind);
+        return imapFailureMessage(kind, config, err);
     }
     finally {
         releaseProbe("imap", token);
@@ -491,11 +564,15 @@ export async function fetchRecent(config, password, options = {}) {
             let envelopeCount = 0;
             let recipientKept = 0;
             let recipientHidden = 0;
+            // Body sources captured during streaming and parsed after the fetch
+            // iterator closes — running simpleParser inside the open fetch loop can
+            // stall the IMAP socket. Aligned by index with `messages`.
+            const bodySources = [];
             for await (const msg of client.fetch(uidList, {
                 envelope: true,
                 uid: true,
                 bodyStructure: true,
-                bodyParts: [{ key: "1", start: 0, maxLength: BODY_MAX_BYTES }],
+                source: true,
             }, { uid: true })) {
                 envelopeCount++;
                 diag("fetchRecent", `envelope #${envelopeCount}`, `uid=${msg.uid} from=${msg.envelope?.from?.[0]?.address ?? "?"} at ${Date.now() - t2}ms`);
@@ -516,12 +593,14 @@ export async function fetchRecent(config, password, options = {}) {
                     continue;
                 // Collect up to `limit` messages for display, but keep iterating past
                 // that point so the recipient kept/hidden accounting covers the whole
-                // fetched window — the envelopes are already fetched, so the extra
-                // iterations cost nothing on the wire and we skip body extraction.
+                // fetched window. Body parsing is deferred until the iterator closes
+                // (see bodySources) and only runs for the displayed messages.
                 if (messages.length < limit) {
-                    const bodyPreview = extractBodyFromFetch(msg);
-                    diag("fetchRecent", `body #${envelopeCount}`, `uid=${msg.uid} preview=${bodyPreview.length}chars type=${msg.bodyStructure?.type ?? "?"}`);
                     const attachments = walkAttachmentMetadata(msg.bodyStructure);
+                    bodySources.push({
+                        source: msg.source ?? Buffer.alloc(0),
+                        structureType: msg.bodyStructure?.type ?? "?",
+                    });
                     messages.push({
                         uid: msg.uid,
                         messageId,
@@ -529,11 +608,17 @@ export async function fetchRecent(config, password, options = {}) {
                         from: fromAddr,
                         subject,
                         date,
-                        bodyPreview,
+                        bodyPreview: "",
                         attachments,
                     });
                 }
             }
+            // Parse the captured sources now that the fetch stream is closed.
+            for (let i = 0; i < messages.length; i++) {
+                const { body, kind } = await extractBody(bodySources[i].source);
+                messages[i].bodyPreview = previewBody(body);
+                diag("fetchRecent", `body #${i + 1}`, `uid=${messages[i].uid} preview=${messages[i].bodyPreview.length}chars type=${bodySources[i].structureType} bodySource=${kind}`);
+            }
             diag("fetchRecent", "fetch done", `${envelopeCount} envelopes, ${messages.length} messages in ${Date.now() - t2}ms (total ${Date.now() - t0}ms)`);
             if (clientSideRecipients) {
                 diag("fetchRecent", "filter applied", `kept=${recipientKept} hidden=${recipientHidden} recipients=[${clientSideRecipients.join(",")}]`);
@@ -608,11 +693,14 @@ export async function searchMessages(config, password, query) {
             let envelopeCount = 0;
             let recipientKept = 0;
             let recipientHidden = 0;
+            // Body sources captured during streaming and parsed after the fetch
+            // iterator closes (see fetchRecent). Aligned by index with `messages`.
+            const bodySources = [];
             for await (const msg of client.fetch(recentUids.map(String).join(","), {
                 envelope: true,
                 uid: true,
                 bodyStructure: true,
-                bodyParts: [{ key: "1", start: 0, maxLength: BODY_MAX_BYTES }],
+                source: true,
             }, { uid: true })) {
                 envelopeCount++;
                 // Client-side recipient filter (replaces IMAP SEARCH TO), with kept-vs-hidden accounting
@@ -630,11 +718,13 @@ export async function searchMessages(config, password, query) {
                 const inReplyTo = msg.envelope?.inReplyTo ?? null;
                 // Collect up to `limit` messages for display, but keep iterating past
                 // that point so the recipient kept/hidden accounting covers the whole
-                // fetched window — the envelopes are already fetched, so the extra
-                // iterations cost nothing on the wire and we skip body extraction.
+                // fetched window. Body parsing is deferred until the iterator closes.
                 if (messages.length < limit) {
-                    const bodyPreview = extractBodyFromFetch(msg);
                     const attachments = walkAttachmentMetadata(msg.bodyStructure);
+                    bodySources.push({
+                        source: msg.source ?? Buffer.alloc(0),
+                        structureType: msg.bodyStructure?.type ?? "?",
+                    });
                     messages.push({
                         uid: msg.uid,
                         messageId,
@@ -642,11 +732,17 @@ export async function searchMessages(config, password, query) {
                         from: fromAddr,
                         subject: subj,
                         date,
-                        bodyPreview,
+                        bodyPreview: "",
                         attachments,
                     });
                 }
             }
+            // Parse the captured sources now that the fetch stream is closed.
+            for (let i = 0; i < messages.length; i++) {
+                const { body, kind } = await extractBody(bodySources[i].source);
+                messages[i].bodyPreview = previewBody(body);
+                diag("searchMessages", `body #${i + 1}`, `uid=${messages[i].uid} preview=${messages[i].bodyPreview.length}chars type=${bodySources[i].structureType} bodySource=${kind}`);
+            }
             diag("searchMessages", "fetch done", `${envelopeCount} envelopes, ${messages.length} messages in ${Date.now() - t2}ms (total ${Date.now() - t0}ms)`);
             if (clientSideRecipients) {
                 diag("searchMessages", "filter applied", `kept=${recipientKept} hidden=${recipientHidden} recipients=[${clientSideRecipients.join(",")}]`);
@@ -728,11 +824,14 @@ export async function fetchSinceUid(config, password, sinceUid, recipients) {
         let hidden = 0;
         const t2 = Date.now();
         const uidList = uids.map(String).join(",");
+        // Body sources captured during streaming and parsed after the fetch
+        // iterator closes (see fetchRecent). Aligned by index with `emails`.
+        const bodySources = [];
         for await (const msg of client.fetch(uidList, {
             envelope: true,
             uid: true,
             bodyStructure: true,
-            bodyParts: [{ key: "1", start: 0, maxLength: BODY_MAX_BYTES }],
+            source: true,
         }, { uid: true })) {
             // Track highest UID for high-water mark
             const uid = Number(msg.uid);
@@ -754,9 +853,18 @@ export async function fetchSinceUid(config, password, sinceUid, recipients) {
             const inReplyTo = msg.envelope?.inReplyTo ?? null;
             const toAddresses = (msg.envelope?.to ?? []).map((a) => a.address).filter((a) => !!a);
             const ccAddresses = (msg.envelope?.cc ?? []).map((a) => a.address).filter((a) => !!a);
-            const bodyPreview = extractBodyFromFetch(msg);
             const attachments = walkAttachmentMetadata(msg.bodyStructure);
-            emails.push({ uid, messageId, inReplyTo, toAddresses, ccAddresses, fromAddress: fromAddr, fromName, subject, date, bodyPreview, attachments });
+            bodySources.push({
+                source: msg.source ?? Buffer.alloc(0),
+                structureType: msg.bodyStructure?.type ?? "?",
+            });
+            emails.push({ uid, messageId, inReplyTo, toAddresses, ccAddresses, fromAddress: fromAddr, fromName, subject, date, bodyPreview: "", attachments });
+        }
+        // Parse the captured sources now that the fetch stream is closed.
+        for (let i = 0; i < emails.length; i++) {
+            const { body, kind } = await extractBody(bodySources[i].source);
+            emails[i].bodyPreview = previewBody(body);
+            diag("fetchSinceUid", `body #${i + 1}`, `uid=${emails[i].uid} preview=${emails[i].bodyPreview.length}chars type=${bodySources[i].structureType} bodySource=${kind}`);
         }
         diag("fetchSinceUid", "fetch done", `${emails.length} emails (maxUid=${maxUid}) in ${Date.now() - t2}ms (total ${Date.now() - t0}ms)`);
         if (recipients) {
@@ -843,6 +951,70 @@ export async function fetchEnvelopeByMessageId(config, password, messageId) {
         await safeLogout(client);
     }
 }
+/**
+ * Fetch the COMPLETE decoded body of one message, addressed by UID (in a
+ * folder) or by Message-ID (resolved across INBOX and \Sent). Downloads the
+ * full RFC822 source and decodes it with mailparser — no 500-char cap and no
+ * MIME-shape blind spot. Returns null when the message cannot be located.
+ */
+export async function fetchFullBody(config, password, target) {
+    let mailbox = "";
+    let uid;
+    if ("messageId" in target) {
+        const env = await fetchEnvelopeByMessageId(config, password, target.messageId);
+        if (!env)
+            return null;
+        mailbox = env.mailbox;
+        uid = env.uid;
+    }
+    else {
+        uid = target.uid;
+    }
+    const client = createClient(config, password);
+    const t0 = Date.now();
+    const label = "messageId" in target
+        ? `messageId=${target.messageId}`
+        : `uid=${target.uid} folder=${target.folder ?? "inbox"}`;
+    diag("fetchFullBody", "start", label);
+    try {
+        await client.connect();
+        if (!("messageId" in target)) {
+            mailbox = await resolveFolderName(client, target.folder ?? "inbox");
+        }
+        const lock = await client.getMailboxLock(mailbox);
+        try {
+            const msg = await client.fetchOne(String(uid), { uid: true, source: true, envelope: true }, { uid: true });
+            if (!msg || !msg.source) {
+                diag("fetchFullBody", "not-found", `uid=${uid} mailbox=${mailbox} in ${Date.now() - t0}ms`);
+                return null;
+            }
+            const src = msg.source;
+            const { body, kind } = await extractBody(src);
+            const env = msg.envelope ?? {};
+            diag("fetchFullBody", "done", `uid=${uid} mailbox=${mailbox} bytes=${src.length} bodyLen=${body.length} bodySource=${kind} in ${Date.now() - t0}ms`);
+            return {
+                uid: msg.uid,
+                messageId: env.messageId ?? null,
+                from: env.from?.[0]?.address ?? "(unknown)",
+                subject: env.subject ?? "(no subject)",
+                date: env.date?.toISOString() ?? "(unknown date)",
+                body,
+                bodySource: kind,
+                bytes: src.length,
+            };
+        }
+        finally {
+            lock.release();
+        }
+    }
+    catch (err) {
+        diag("fetchFullBody", "FAILED", `${err instanceof Error ? err.message : String(err)} after ${Date.now() - t0}ms`);
+        throw err;
+    }
+    finally {
+        await safeLogout(client);
+    }
+}
 /**
  * Get the inbox message count.
  */
@@ -851,6 +1023,7 @@ export async function getInboxCount(config, password, token = newProbeToken()) {
     trackProbe("imap", client, token);
     try {
         await client.connect();
+        containProbeSocket(client, "imap", token);
         const mailbox = await client.mailboxOpen("INBOX");
         return mailbox.exists;
     }
@@ -944,33 +1117,66 @@ export async function fetchDraftSource(config, password, uid) {
     }
 }
 /**
- * Read-modify-replace cycle for an existing draft addressed by Drafts-folder UID.
+ * Read-modify-replace cycle for an existing draft. The recorded Drafts UID is a
+ * fast-path hint; the draft's own `Message-ID` is the stable identity, because
+ * Gmail renumbers a draft's UID when it is touched or re-synced.
+ *
+ * Resolution order, inside the Drafts lock: the recorded UID if still live, else
+ * a `SEARCH HEADER Message-ID` relocate (when a draftMessageId is supplied),
+ * else nothing. In every path the replacement is APPENDed (with the \Draft flag)
+ * BEFORE the resolved old copy is expunged, so a mid-cycle failure never leaves
+ * zero copies.
+ *
+ * When neither identity resolves a live draft, the prior draft is genuinely
+ * gone: the replacement is appended as a fresh draft and `created:true` is
+ * returned — no throw. `newUid` is the APPENDUID when the server supports
+ * UIDPLUS, else null.
  *
- * Atomicity contract: the replacement is APPENDed (with the \Draft flag) BEFORE
- * the superseded UID is expunged, so a mid-cycle failure never leaves zero
- * copies. The old UID's existence is confirmed first; an absent UID throws
- * before any append, so a bad UID never produces an orphan replacement.
- * `newUid` is the APPENDUID when the server supports UIDPLUS, else null.
+ * A single transient transport drop is absorbed by the bounded retry; permanent
+ * errors (auth) surface immediately.
  */
-export async function replaceDraft(config, password, oldUid, newRaw) {
+export async function replaceDraft(config, password, oldUid, newRaw, draftMessageId) {
+    return withTransientRetry("draftReplace", () => replaceDraftOnce(config, password, oldUid, newRaw, draftMessageId ?? null));
+}
+async function replaceDraftOnce(config, password, oldUid, newRaw, draftMessageId) {
     const client = createClient(config, password);
     const t0 = Date.now();
-    diag("draftReplace", "start", `oldUid=${oldUid} bytes=${newRaw.length}`);
+    diag("draftReplace", "start", `oldUid=${oldUid} bytes=${newRaw.length} draftMessageId=${draftMessageId ?? "none"}`);
     try {
         await client.connect();
         const folder = await resolveFolderName(client, "drafts");
         const lock = await client.getMailboxLock(folder);
         try {
+            // Resolve the live UID: fast-path the recorded UID, else relocate by the
+            // draft's own Message-ID, else accept that the prior draft is gone.
+            let resolvedUid = null;
+            let addressing = "created-fresh";
             const existing = await client.fetchOne(String(oldUid), { uid: true }, { uid: true });
-            if (!existing) {
-                throw new Error(`Draft UID ${oldUid} not found in ${folder}.`);
+            if (existing) {
+                resolvedUid = oldUid;
+                addressing = "uid-hit";
             }
+            else if (draftMessageId) {
+                const needle = `<${draftMessageId.replace(/^<|>$/g, "")}>`;
+                const uids = await client.search({ header: { "message-id": needle } }, { uid: true });
+                if (uids && uids.length > 0) {
+                    resolvedUid = uids[0];
+                    addressing = "message-id-relocate";
+                }
+            }
+            // Append the replacement first in every path — the atomicity invariant.
             const appended = await client.append(folder, newRaw, ["\\Draft"]);
             const newUid = appended && typeof appended.uid === "number" ? appended.uid : null;
-            diag("draftReplace", "appended", `folder=${folder} newUid=${newUid ?? "not-reported"}`);
-            const expunged = await client.messageDelete(String(oldUid), { uid: true });
-            diag("draftReplace", "expunged", `oldUid=${oldUid} newUid=${newUid ?? "not-reported"} expunge=${expunged} in ${Date.now() - t0}ms`);
-            return { folder, oldUid, newUid, expunged: !!expunged };
+            if (resolvedUid === null) {
+                // Create-on-absent recovery: distinct marker so it is not read as a
+                // normal replace. Nothing to expunge.
+                diag("draftReplace", "created-fresh", `folder=${folder} newUid=${newUid ?? "not-reported"} oldUid=${oldUid} draftMessageId=${draftMessageId ?? "none"} in ${Date.now() - t0}ms`);
+                return { folder, oldUid, newUid, expunged: false, created: true, addressing };
+            }
+            diag("draftReplace", "appended", `folder=${folder} newUid=${newUid ?? "not-reported"} addressing=${addressing} resolvedUid=${resolvedUid}`);
+            const expunged = await client.messageDelete(String(resolvedUid), { uid: true });
+            diag("draftReplace", "expunged", `resolvedUid=${resolvedUid} newUid=${newUid ?? "not-reported"} addressing=${addressing} expunge=${expunged} in ${Date.now() - t0}ms`);
+            return { folder, oldUid, newUid, expunged: !!expunged, created: false, addressing };
         }
         finally {
             lock.release();
@@ -986,10 +1192,18 @@ export async function replaceDraft(config, password, oldUid, newRaw) {
 }
 /**
  * Delete a stored draft addressed by Drafts-folder UID (used by the send path
- * after SMTP accepts the message). The UID's existence is confirmed first; an
- * absent UID throws rather than silently no-op'ing.
+ * after SMTP accepts the message). An absent UID is treated as success with
+ * nothing removed (`deleted:false`) — deletion's goal is already met, so a
+ * stale UID is not an error. A single transient transport drop is absorbed by
+ * the bounded retry.
+ *
+ * Message-ID relocation is deliberately not applied here: the send path
+ * addresses by UID only and carries no draft Message-ID to relocate by.
  */
 export async function deleteDraft(config, password, uid) {
+    return withTransientRetry("draftDelete", () => deleteDraftOnce(config, password, uid));
+}
+async function deleteDraftOnce(config, password, uid) {
     const client = createClient(config, password);
     const t0 = Date.now();
     diag("draftDelete", "start", `uid=${uid}`);
@@ -1000,7 +1214,8 @@ export async function deleteDraft(config, password, uid) {
         try {
             const existing = await client.fetchOne(String(uid), { uid: true }, { uid: true });
             if (!existing) {
-                throw new Error(`Draft UID ${uid} not found in ${folder}.`);
+                diag("draftDelete", "absent", `uid=${uid} folder=${folder} in ${Date.now() - t0}ms`);
+                return { folder, deleted: false };
             }
             const deleted = await client.messageDelete(String(uid), { uid: true });
             diag("draftDelete", "deleted", `uid=${uid} folder=${folder} deleted=${deleted} in ${Date.now() - t0}ms`);