@remit/imap-worker 0.0.53 → 0.0.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/imap-worker",
-  "version": "0.0.53",
+  "version": "0.0.55",
   "type": "module",
   "main": "dist/index.js",
   "exports": {

package/src/handlers/message-delete-terminal.ts

@@ -0,0 +1,119 @@
+import type { IMessageRepository } from "@remit/data-ports";
+import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
+import {
+	type IImapConnection,
+	isMessageGoneFromOpenMailbox,
+	reconcileStaleMessage,
+	type StaleMessageReconcileDeps,
+} from "@remit/mailbox-service";
+
+export interface MessageDeleteTerminalLogger {
+	info(obj: Record<string, unknown>, msg: string): void;
+	error(obj: Record<string, unknown>, msg: string): void;
+}
+
+export interface ResolveExhaustedMessageDeleteDeps
+	extends StaleMessageReconcileDeps {
+	messageService: Pick<IMessageRepository, "delete" | "update">;
+	log: MessageDeleteTerminalLogger;
+}
+
+export interface ResolveExhaustedMessageDeleteInput {
+	accountId: string;
+	accountConfigId: string;
+	messageId: string;
+	uid: number;
+	sourceMailboxPath: string;
+	getConnection: () => Promise<IImapConnection>;
+}
+
+export type MessageDeleteTerminalOutcome = "reconciled" | "broken";
+
+export interface ResolveExhaustedMessageDeleteResult {
+	outcome: MessageDeleteTerminalOutcome;
+}
+
+/**
+ * Resolve a MESSAGE_DELETE failure that has exhausted its redelivery budget
+ * into exactly one of two terminal outcomes, mirroring
+ * `resolveExhaustedMessageMoveFailure` for the same failure taxonomy (issue
+ * #655) — no third, softer outcome.
+ *
+ * 1. RECONCILED (expected) — the message no longer exists at the delete's
+ *    source on IMAP, confirmed by {@link isMessageGoneFromOpenMailbox} rather
+ *    than by a FETCH coming back empty. The move to Trash landed server-side,
+ *    or a foreign client moved or expunged the message; from here those are
+ *    indistinguishable and have the same answer. The stale rows are deleted via
+ *    {@link reconcileStaleMessage} and the caller resyncs the affected folders,
+ *    so whichever folder actually holds the message re-projects it with the
+ *    server's own UID. Metric only, no alarm — routine.
+ * 2. BROKEN — the message is still at the source, so the delete never took
+ *    effect, but it keeps failing: broken code or a broken account, not a
+ *    transient blip. The row's mailbox and uid are left exactly as they stand,
+ *    because reverting the optimistic move on this ambiguity is what PR #652
+ *    was pulled for.
+ *
+ *    `status` does settle, to `active`. It is not a claim about where the
+ *    message is — only that this row is no longer mid-mutation. Leaving it
+ *    `moving` makes `isPlacementUnsettled` true forever, and every later delete
+ *    of that message then waits on a mutation that has already terminated, so
+ *    the user is left with mail they cannot delete.
+ *
+ * A server that cannot be reached at exhaustion time never reaches either
+ * verdict: the probe throws and the record dead-letters with the row untouched.
+ * Absence is only ever concluded from an answer the server gave.
+ */
+export const resolveExhaustedMessageDeleteFailure = async (
+	deps: ResolveExhaustedMessageDeleteDeps,
+	input: ResolveExhaustedMessageDeleteInput,
+): Promise<ResolveExhaustedMessageDeleteResult> => {
+	const {
+		accountId,
+		accountConfigId,
+		messageId,
+		uid,
+		sourceMailboxPath,
+		getConnection,
+	} = input;
+
+	const connection = await getConnection();
+	await connection.openBox(sourceMailboxPath, true);
+
+	if (await isMessageGoneFromOpenMailbox(connection, uid)) {
+		const { threadMessagesDeleted } = await reconcileStaleMessage(
+			deps,
+			accountConfigId,
+			messageId,
+		);
+		deps.log.info(
+			{
+				metric: "message_delete_stale_row_reconciled",
+				accountId,
+				accountConfigId,
+				messageId,
+				uid,
+				sourceMailboxPath,
+				threadMessagesDeleted,
+			},
+			"Message no longer at its delete source after retry exhaustion (the delete landed server-side, or an external delete or move); stale row reconciled",
+		);
+		return { outcome: "reconciled" };
+	}
+
+	await deps.messageService.update(messageId, {
+		status: MessageStatus.active,
+		syncStatus: MessageSyncStatus.failed,
+	});
+	deps.log.error(
+		{
+			alert: "message_delete_failed",
+			accountId,
+			accountConfigId,
+			messageId,
+			uid,
+			sourceMailboxPath,
+		},
+		"Delete could not be pushed to IMAP after retry exhaustion; the message is still at its source — row settled out of `moving` and left in place for operator investigation",
+	);
+	return { outcome: "broken" };
+};

package/src/handlers/message-delete.test.ts

@@ -2,15 +2,50 @@ import assert from "node:assert";
 import { beforeEach, describe, it, mock } from "node:test";
 import type { ThreadMessageItem } from "@remit/data-ports";
 import type { Logger } from "@remit/logger-lambda";
+import { renderMetrics, resetMetrics } from "@remit/logger-lambda";
 import type { MessageDeleteEvent } from "../events.js";
 import {
 	buildThreadMessageTrashUpdate,
 	buildThreadMessageUndelete,
 	deleteAllThreadMessagesForMessage,
+	getMessageDeleteMaxAttempts,
 	handleMessageDelete,
+	MESSAGE_DELETE_MAX_ATTEMPTS,
 	type MessageDeleteDeps,
 } from "./message-delete.js";
 
+describe("getMessageDeleteMaxAttempts — env-derived threshold (#980)", () => {
+	it("parses the injected env var", () => {
+		assert.equal(
+			getMessageDeleteMaxAttempts({ MESSAGE_DELETE_MAX_ATTEMPTS: "3" }),
+			3,
+		);
+		assert.equal(
+			getMessageDeleteMaxAttempts({ MESSAGE_DELETE_MAX_ATTEMPTS: "5" }),
+			5,
+		);
+	});
+
+	it("defaults to the mailbox queue's own maxReceiveCount when unset", () => {
+		assert.equal(getMessageDeleteMaxAttempts({}), 3);
+	});
+
+	it("defaults on a non-numeric or non-positive value", () => {
+		assert.equal(
+			getMessageDeleteMaxAttempts({ MESSAGE_DELETE_MAX_ATTEMPTS: "nope" }),
+			3,
+		);
+		assert.equal(
+			getMessageDeleteMaxAttempts({ MESSAGE_DELETE_MAX_ATTEMPTS: "0" }),
+			3,
+		);
+	});
+
+	it("MESSAGE_DELETE_MAX_ATTEMPTS is a concrete, positive number at module load", () => {
+		assert.ok(MESSAGE_DELETE_MAX_ATTEMPTS > 0);
+	});
+});
+
 const sourceMailboxId = "source-mailbox-id-aaaaaaaaa";
 const trashMailboxId = "trash-mailbox-id-aaaaaaaaa";
 
@@ -260,6 +295,8 @@ interface Harness {
 	mailboxError?: Error;
 	connection: Connection;
 	threadMessageUpdateError?: Error;
+	messageRow: { messageIdHeader?: string } | undefined;
+	destinationSearchUids: number[];
 	threadMessage: Record<string, unknown> | null;
 	allThreadMessages: Record<string, unknown>[];
 	getConnectionCount: number;
@@ -274,6 +311,16 @@ const record =
 		h.calls.push({ method, args });
 	};
 
+const MESSAGE_ID_HEADER = "<trashed-message@example.com>";
+
+// The source-presence probe (`isMessageGoneFromOpenMailbox`) and the
+// destination probe both go through `connection.search`; only the criterion
+// form tells them apart.
+const isMessageIdSearch = (criteria: unknown): boolean =>
+	Array.isArray(criteria) &&
+	Array.isArray(criteria[0]) &&
+	criteria[0][0] === "HEADER";
+
 const buildConnection = (): Connection => ({
 	openBox: async () => ({ uidvalidity: 1 }),
 	moveMessages: async () => ({ uidMap: new Map([[10, 20]]) }),
@@ -288,7 +335,7 @@ const buildConnection = (): Connection => ({
 	fetchMessages: async (uids: number[]) => uids.map((uid) => ({ uid })),
 	search: async (...args: unknown[]) => {
 		h.calls.push({ method: "connection.search", args });
-		return [10];
+		return isMessageIdSearch(args[0]) ? h.destinationSearchUids : [10];
 	},
 });
 
@@ -296,7 +343,7 @@ const sourceNoLongerHoldsTheUid = (): void => {
 	h.connection.fetchMessages = async () => [];
 	h.connection.search = async (...args: unknown[]) => {
 		h.calls.push({ method: "connection.search", args });
-		return [];
+		return isMessageIdSearch(args[0]) ? h.destinationSearchUids : [];
 	};
 };
 
@@ -304,6 +351,8 @@ const fresh = (): Harness => ({
 	calls: [],
 	account: { accountId: "acc-1", accountConfigId: "cfg-1" },
 	mailbox: { mailboxId: "src-mbx", uidValidity: 1, cursorState: undefined },
+	messageRow: { messageIdHeader: MESSAGE_ID_HEADER },
+	destinationSearchUids: [],
 	connection: buildConnection(),
 	threadMessage: {
 		...baseThreadMessage,
@@ -328,6 +377,10 @@ const deps = (): MessageDeleteDeps =>
 				},
 			},
 			message: {
+				get: async (messageIds: string[]) => {
+					h.calls.push({ method: "message.get", args: [messageIds] });
+					return h.messageRow ? [h.messageRow] : [];
+				},
 				updateUid: record("message.updateUid"),
 				update: record("message.update"),
 				delete: record("message.delete"),
@@ -340,6 +393,7 @@ const deps = (): MessageDeleteDeps =>
 					if (h.threadMessageUpdateError) throw h.threadMessageUpdateError;
 				},
 				delete: record("threadMessage.delete"),
+				deleteMany: record("threadMessage.deleteMany"),
 			},
 			mailbox: {
 				get: async () => {
@@ -357,6 +411,7 @@ const deps = (): MessageDeleteDeps =>
 			_log: unknown,
 			cb: (credentials: unknown) => Promise<void>,
 		) => cb({}),
+		emitEvent: record("emitEvent"),
 		createConnectionScope: () => ({
 			getConnection: async () => {
 				h.getConnectionCount += 1;
@@ -395,13 +450,26 @@ const permanentEvent: MessageDeleteEvent = {
 const called = (method: string): Call[] =>
 	h.calls.filter((c) => c.method === method);
 
+// Label order in the rendered text is prom-client's, not ours.
+const imapFailures = async (operation: string): Promise<number> => {
+	const line = (await renderMetrics())
+		.split("\n")
+		.find(
+			(candidate) =>
+				candidate.startsWith("remit_imap_failures_total{") &&
+				candidate.includes(`operation="${operation}"`),
+		);
+	return line ? Number(line.slice(line.lastIndexOf(" ") + 1)) : 0;
+};
+
 describe("handleMessageDelete", () => {
 	beforeEach(() => {
 		h = fresh();
+		resetMetrics();
 	});
 
 	it("moves to trash, rewrites the uid, and flips the thread row to deleted", async () => {
-		await handleMessageDelete(moveEvent, noopLog, deps());
+		await handleMessageDelete(moveEvent, noopLog, 1, deps());
 
 		assert.deepEqual(called("message.updateUid")[0]?.args, [
 			"msg-1",
@@ -417,17 +485,308 @@ describe("handleMessageDelete", () => {
 		assert.equal(h.disconnectCount, 1);
 	});
 
-	it("marks the message failed when the MOVE returns no new uid", async () => {
-		h.connection.moveMessages = async () => ({ uidMap: new Map() });
+	// UIDPLUS is an extension: a server without it answers a perfectly
+	// successful MOVE with no COPYUID entry. An empty uidMap is therefore
+	// UNCONFIRMED, and the destination is asked by Message-ID before any
+	// verdict — the rule every sibling handler already carries. Issue #979.
+	describe("no COPYUID entry on the move to trash", () => {
+		it("settles the row on the probed uid when the message left the source and is at the destination (non-UIDPLUS server, genuine success)", async () => {
+			h.connection.moveMessages = async () => ({ uidMap: new Map() });
+			sourceNoLongerHoldsTheUid();
+			h.destinationSearchUids = [77];
 
-		await handleMessageDelete(moveEvent, noopLog, deps());
+			await handleMessageDelete(moveEvent, noopLog, 1, deps());
 
-		assert.equal(called("message.updateUid").length, 0);
-		assert.equal(
-			(called("message.update")[0]?.args[1] as { syncStatus?: string })
-				?.syncStatus,
-			"failed",
-		);
+			assert.deepEqual(called("message.updateUid")[0]?.args, [
+				"msg-1",
+				77,
+				"trash-mbx",
+			]);
+			assert.deepEqual(called("threadMessage.update")[0]?.args[2], {
+				uid: 77,
+				mailboxId: "trash-mbx",
+				isDeleted: true,
+			});
+			assert.equal(
+				called("message.update").length,
+				0,
+				"a settled move never marks the row failed",
+			);
+		});
+
+		it("probes the DESTINATION mailbox, read-only, by Message-ID", async () => {
+			h.connection.moveMessages = async () => ({ uidMap: new Map() });
+			sourceNoLongerHoldsTheUid();
+			h.destinationSearchUids = [77];
+			const opened: unknown[][] = [];
+			h.connection.openBox = (async (...args: unknown[]) => {
+				opened.push(args);
+				return { uidvalidity: 1 };
+			}) as Connection["openBox"];
+
+			await handleMessageDelete(moveEvent, noopLog, 1, deps());
+
+			assert.deepEqual(
+				opened,
+				[
+					["INBOX", false],
+					["INBOX", true],
+					["Trash", true],
+				],
+				"the source is re-asked read-only, then the destination is EXAMINEd — neither probe may SELECT a box writable",
+			);
+			assert.deepEqual(called("connection.search").at(-1)?.args[0], [
+				["HEADER", "Message-ID", MESSAGE_ID_HEADER],
+			]);
+		});
+
+		// Issue #980. Within the budget the row is marked unsettled and the
+		// event is re-thrown so the queue redelivers it, exactly as
+		// `handleMessageMove` does; nothing is reverted and nothing is deleted,
+		// because a MOVE that ran server-side but dropped before the tagged OK
+		// is indistinguishable from one that never ran (#655, PR #652).
+		it("throws to redeliver while the budget still has attempts left", async () => {
+			h.connection.moveMessages = async () => ({ uidMap: new Map() });
+			sourceNoLongerHoldsTheUid();
+			h.destinationSearchUids = [];
+
+			await assert.rejects(
+				handleMessageDelete(moveEvent, noopLog, 1, deps()),
+				/unconfirmed/,
+			);
+
+			assert.equal(called("message.updateUid").length, 0);
+			assert.equal(
+				called("message.delete").length,
+				0,
+				"an unconfirmed move must never delete the local row inside the budget",
+			);
+			assert.equal(
+				called("threadMessage.deleteMany").length,
+				0,
+				"an unconfirmed move must never delete the listing rows inside the budget",
+			);
+			assert.equal(
+				called("threadMessage.update").length,
+				0,
+				"an unconfirmed move must never revert the listing row to the source",
+			);
+			assert.equal(
+				(called("message.update")[0]?.args[1] as { syncStatus?: string })
+					?.syncStatus,
+				"failed",
+			);
+			assert.equal(h.disconnectCount, 1);
+		});
+
+		it("settles once at the ceiling: reconciles the stale rows and resyncs both folders", async () => {
+			h.connection.moveMessages = async () => ({ uidMap: new Map() });
+			sourceNoLongerHoldsTheUid();
+			h.destinationSearchUids = [];
+
+			await handleMessageDelete(moveEvent, noopLog, 3, deps());
+
+			assert.equal(
+				called("threadMessage.deleteMany").length,
+				1,
+				"the ceiling settles the row rather than leaving it claiming a uid the server does not have",
+			);
+			assert.equal(called("message.delete").length, 1);
+			assert.deepEqual(
+				called("emitEvent").map((c) => c.args[0]),
+				[
+					{ type: "SYNC_MESSAGES", accountId: "acc-1", mailboxId: "src-mbx" },
+					{ type: "SYNC_MESSAGES", accountId: "acc-1", mailboxId: "trash-mbx" },
+				],
+				"both folders re-project from IMAP so the message reappears where it actually is",
+			);
+			assert.equal(h.disconnectCount, 1);
+		});
+
+		// A message with no Message-ID header on a non-UIDPLUS server can never
+		// be confirmed at the destination, so redelivering it only burns the
+		// budget on an answer that cannot change.
+		it("settles on the first attempt when the row carries no Message-ID header", async () => {
+			h.connection.moveMessages = async () => ({ uidMap: new Map() });
+			sourceNoLongerHoldsTheUid();
+			h.messageRow = {};
+
+			await handleMessageDelete(moveEvent, noopLog, 1, deps());
+
+			assert.equal(
+				called("connection.search").filter((c) =>
+					JSON.stringify(c.args).includes("HEADER"),
+				).length,
+				0,
+			);
+			assert.equal(called("message.updateUid").length, 0);
+			assert.equal(
+				called("message.delete").length,
+				1,
+				"an unprobeable row settles instead of spending the whole budget",
+			);
+			assert.equal(called("emitEvent").length, 2);
+			assert.equal(
+				await imapFailures("MESSAGE_DELETE_TRASH_MOVE_UNCONFIRMED"),
+				1,
+			);
+		});
+
+		// The row this event names was already deleted, so there is nothing to
+		// settle and nothing to show. Re-throwing would loop a NotFoundError on
+		// the account's per-group FIFO and block every later mailbox event.
+		it("acks without touching the database when the local row is already gone", async () => {
+			h.connection.moveMessages = async () => ({ uidMap: new Map() });
+			sourceNoLongerHoldsTheUid();
+			h.messageRow = undefined;
+
+			await handleMessageDelete(moveEvent, noopLog, 1, deps());
+
+			assert.equal(called("message.update").length, 0);
+			assert.equal(called("message.delete").length, 0);
+			assert.equal(called("threadMessage.deleteMany").length, 0);
+			assert.equal(called("emitEvent").length, 0);
+		});
+
+		// `searchMailboxByMessageId` returns the LOWEST matching uid, and one
+		// Message-ID can have several server copies in one account while
+		// `deriveMessageId` gives them one local row. A source that still holds
+		// the uid proves the MOVE did not happen, so any hit at the destination
+		// is a different copy.
+		it("never takes a destination hit while the source still holds the uid (duplicate Message-ID)", async () => {
+			h.connection.moveMessages = async () => ({ uidMap: new Map() });
+			h.destinationSearchUids = [100];
+
+			await assert.rejects(
+				handleMessageDelete(moveEvent, noopLog, 1, deps()),
+				/unconfirmed/,
+			);
+
+			assert.equal(
+				called("message.updateUid").length,
+				0,
+				"an earlier copy's uid must never settle this row",
+			);
+			assert.equal(called("threadMessage.update").length, 0);
+			assert.equal(called("message.delete").length, 0);
+			assert.equal(
+				(called("message.update")[0]?.args[1] as { syncStatus?: string })
+					?.syncStatus,
+				"failed",
+			);
+		});
+
+		// A source that still holds the uid at the ceiling means the MOVE never
+		// took effect. Local state is left exactly as it stands — the row is the
+		// only record that this delete is still owed, and a revert races a MOVE
+		// that may yet have landed (#652, #655).
+		it("leaves a message still at its source untouched at the ceiling and never re-throws", async () => {
+			h.connection.moveMessages = async () => ({ uidMap: new Map() });
+			h.destinationSearchUids = [100];
+
+			await handleMessageDelete(moveEvent, noopLog, 3, deps());
+
+			assert.equal(called("message.delete").length, 0);
+			assert.equal(called("threadMessage.deleteMany").length, 0);
+			assert.equal(called("threadMessage.update").length, 0);
+			assert.equal(called("emitEvent").length, 0);
+
+			// The row's mailbox and uid stay put, but `status` must leave
+			// `moving`: `isPlacementUnsettled` reads exactly that value, so a row
+			// left mid-mutation makes every later delete of this message wait on
+			// a mutation that has already terminated.
+			assert.deepEqual(called("message.update").at(-1)?.args[1], {
+				status: "active",
+				syncStatus: "failed",
+			});
+			assert.equal(await imapFailures("MESSAGE_DELETE_EXHAUSTED"), 1);
+		});
+
+		// Issue #980, the failure the budget exists for: every redelivery
+		// re-MOVEs a uid the source no longer holds and throws identically. The
+		// ceiling lives in the error catch, so a throwing `moveMessages` settles
+		// there rather than running past the budget into the dead-letter queue.
+		describe("a re-MOVE that throws", () => {
+			const moveThrows = (): void => {
+				h.connection.moveMessages = async () => {
+					throw new Error(
+						"NO [TRYAGAIN] UID MOVE failed: no matching messages",
+					);
+				};
+			};
+
+			it("re-throws inside the budget so the queue redelivers", async () => {
+				moveThrows();
+
+				await assert.rejects(
+					handleMessageDelete(moveEvent, noopLog, 1, deps()),
+					/UID MOVE failed/,
+				);
+
+				assert.equal(called("message.delete").length, 0);
+				assert.equal(called("threadMessage.deleteMany").length, 0);
+				assert.equal(
+					(called("message.update")[0]?.args[1] as { syncStatus?: string })
+						?.syncStatus,
+					"failed",
+				);
+			});
+
+			it("settles at the ceiling instead of dead-lettering undiagnosed", async () => {
+				moveThrows();
+				sourceNoLongerHoldsTheUid();
+
+				await handleMessageDelete(moveEvent, noopLog, 3, deps());
+
+				assert.equal(
+					called("threadMessage.deleteMany").length,
+					1,
+					"the ceiling must diagnose the failure, not hand it to the DLQ",
+				);
+				assert.equal(called("message.delete").length, 1);
+				assert.equal(called("emitEvent").length, 2);
+			});
+
+			it("settles a still-present message at the ceiling out of `moving`", async () => {
+				moveThrows();
+
+				await handleMessageDelete(moveEvent, noopLog, 3, deps());
+
+				assert.deepEqual(called("message.update").at(-1)?.args[1], {
+					status: "active",
+					syncStatus: "failed",
+				});
+				assert.equal(await imapFailures("MESSAGE_DELETE_EXHAUSTED"), 1);
+			});
+		});
+
+		// A probe the server refused says nothing either way, so it counts as
+		// unconfirmed and spends an attempt. The budget is what makes that safe:
+		// without a ceiling the redeliveries would re-MOVE a uid the source no
+		// longer holds forever and head-of-line block the account's deletes.
+		it("treats an unanswerable probe as unconfirmed and spends an attempt", async () => {
+			h.connection.moveMessages = async () => ({ uidMap: new Map() });
+			h.connection.openBox = (async (_path: string, readOnly?: boolean) => {
+				if (readOnly) throw new Error("NO [SERVERBUG] EXAMINE failed");
+				return { uidvalidity: 1 };
+			}) as Connection["openBox"];
+
+			await assert.rejects(
+				handleMessageDelete(moveEvent, noopLog, 1, deps()),
+				/unconfirmed/,
+			);
+
+			assert.equal(called("message.updateUid").length, 0);
+			assert.equal(called("message.delete").length, 0);
+			assert.equal(called("threadMessage.deleteMany").length, 0);
+			assert.equal(called("threadMessage.update").length, 0);
+			assert.equal(
+				(called("message.update")[0]?.args[1] as { syncStatus?: string })
+					?.syncStatus,
+				"failed",
+			);
+			assert.equal(h.disconnectCount, 1);
+		});
 	});
 
 	// The queue handler `JSON.parse`s the body and casts it to WorkerEvent with
@@ -444,7 +803,7 @@ describe("handleMessageDelete", () => {
 				operation,
 			} as unknown as MessageDeleteEvent;
 
-			await handleMessageDelete(malformed, noopLog, deps());
+			await handleMessageDelete(malformed, noopLog, 1, deps());
 
 			assert.equal(
 				called("connection.deleteMessages").length,
@@ -481,7 +840,7 @@ describe("handleMessageDelete", () => {
 			destinationMailboxPath: undefined,
 		} as MessageDeleteEvent;
 
-		await handleMessageDelete(destinationless, noopLog, deps());
+		await handleMessageDelete(destinationless, noopLog, 1, deps());
 
 		assert.equal(called("connection.deleteMessages").length, 0);
 		assert.equal(called("message.delete").length, 0);
@@ -492,7 +851,7 @@ describe("handleMessageDelete", () => {
 	});
 
 	it("expunges on the server and removes every thread row before the message row", async () => {
-		await handleMessageDelete(permanentEvent, noopLog, deps());
+		await handleMessageDelete(permanentEvent, noopLog, 1, deps());
 
 		assert.deepEqual(called("connection.deleteMessages")[0]?.args, [[10]]);
 		assert.equal(called("threadMessage.delete").length, 2);
@@ -511,7 +870,7 @@ describe("handleMessageDelete", () => {
 		};
 		sourceNoLongerHoldsTheUid();
 
-		await handleMessageDelete(permanentEvent, noopLog, deps());
+		await handleMessageDelete(permanentEvent, noopLog, 1, deps());
 
 		assert.equal(called("message.delete").length, 1);
 		assert.equal(called("threadMessage.delete").length, 2);
@@ -532,7 +891,7 @@ describe("handleMessageDelete", () => {
 		sourceNoLongerHoldsTheUid();
 
 		await assert.rejects(
-			handleMessageDelete(moveEvent, noopLog, deps()),
+			handleMessageDelete(moveEvent, noopLog, 1, deps()),
 			/not found/,
 		);
 
@@ -560,7 +919,7 @@ describe("handleMessageDelete", () => {
 		};
 
 		await assert.rejects(
-			handleMessageDelete(moveEvent, noopLog, deps()),
+			handleMessageDelete(moveEvent, noopLog, 1, deps()),
 			/NONEXISTENT/,
 		);
 
@@ -582,7 +941,7 @@ describe("handleMessageDelete", () => {
 		h.connection.fetchMessages = async () => [];
 
 		await assert.rejects(
-			handleMessageDelete(permanentEvent, noopLog, deps()),
+			handleMessageDelete(permanentEvent, noopLog, 1, deps()),
 			/NONEXISTENT/,
 		);
 
@@ -607,7 +966,7 @@ describe("handleMessageDelete", () => {
 		};
 
 		await assert.rejects(
-			handleMessageDelete(permanentEvent, noopLog, deps()),
+			handleMessageDelete(permanentEvent, noopLog, 1, deps()),
 			/NONEXISTENT mailbox does not exist/,
 		);
 
@@ -628,7 +987,7 @@ describe("handleMessageDelete", () => {
 			throw new Error("TRYCREATE: no such mailbox");
 		};
 
-		await handleMessageDelete(moveEvent, noopLog, deps());
+		await handleMessageDelete(moveEvent, noopLog, 1, deps());
 
 		assert.equal(called("connection.createMailbox").length, 0);
 		assert.deepEqual(called("message.updateUid")[0]?.args, [
@@ -653,7 +1012,7 @@ describe("handleMessageDelete", () => {
 			schemaVersion: undefined,
 		} as unknown as MessageDeleteEvent;
 
-		await handleMessageDelete(unversioned, noopLog, deps());
+		await handleMessageDelete(unversioned, noopLog, 1, deps());
 
 		assert.equal(h.getConnectionCount, 0);
 		assert.equal(called("connection.deleteMessages").length, 0);
@@ -675,7 +1034,7 @@ describe("handleMessageDelete", () => {
 			schemaVersion: undefined,
 		} as unknown as MessageDeleteEvent;
 
-		await handleMessageDelete(unversioned, noopLog, deps());
+		await handleMessageDelete(unversioned, noopLog, 1, deps());
 
 		assert.deepEqual(
 			called("threadMessage.update").map((c) => c.args[1]),
@@ -694,7 +1053,7 @@ describe("handleMessageDelete", () => {
 			schemaVersion: undefined,
 		} as unknown as MessageDeleteEvent;
 
-		await handleMessageDelete(unversioned, noopLog, deps());
+		await handleMessageDelete(unversioned, noopLog, 1, deps());
 
 		assert.equal(called("connection.deleteMessages").length, 0);
 		assert.deepEqual(called("message.delete")[0]?.args, ["msg-1"]);
@@ -711,7 +1070,7 @@ describe("handleMessageDelete", () => {
 		};
 
 		await assert.rejects(
-			handleMessageDelete(moveEvent, noopLog, deps()),
+			handleMessageDelete(moveEvent, noopLog, 1, deps()),
 			/server exploded/,
 		);
 
@@ -725,7 +1084,7 @@ describe("handleMessageDelete", () => {
 	it("pauses quietly when openBox trips a UIDVALIDITY mismatch", async () => {
 		h.connection.openBox = async () => ({ uidvalidity: 999 });
 
-		await handleMessageDelete(moveEvent, noopLog, deps());
+		await handleMessageDelete(moveEvent, noopLog, 1, deps());
 
 		assert.equal(
 			(called("mailbox.update")[0]?.args[2] as { cursorState?: string })
@@ -742,7 +1101,7 @@ describe("handleMessageDelete", () => {
 			cursorState: "rebuilding",
 		};
 
-		await handleMessageDelete(moveEvent, noopLog, deps());
+		await handleMessageDelete(moveEvent, noopLog, 1, deps());
 
 		assert.equal(h.getConnectionCount, 0);
 	});
@@ -752,7 +1111,7 @@ describe("handleMessageDelete", () => {
 			name: "NotFoundError",
 		});
 
-		await handleMessageDelete(moveEvent, noopLog, deps());
+		await handleMessageDelete(moveEvent, noopLog, 1, deps());
 
 		assert.equal(h.getConnectionCount, 0);
 		assert.equal(called("message.updateUid").length, 0);
@@ -766,7 +1125,7 @@ describe("handleMessageDelete", () => {
 			deletedAt: Date.now(),
 		};
 
-		await handleMessageDelete(moveEvent, noopLog, deps());
+		await handleMessageDelete(moveEvent, noopLog, 1, deps());
 
 		assert.equal(h.getConnectionCount, 0);
 	});
@@ -775,7 +1134,7 @@ describe("handleMessageDelete", () => {
 		h.account = null;
 
 		await assert.rejects(
-			handleMessageDelete(moveEvent, noopLog, deps()),
+			handleMessageDelete(moveEvent, noopLog, 1, deps()),
 			/not found/,
 		);
 	});

package/src/handlers/message-delete.ts

@@ -1,23 +1,50 @@
 import { getClient } from "@remit/backend/client";
 import type {
+	IMessageRepository,
 	IThreadMessageRepository,
 	ThreadMessageItem,
 } from "@remit/data-ports";
 import { isCurrentSchemaVersion } from "@remit/data-ports/mutation-events";
 import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
 import type { Logger } from "@remit/logger-lambda";
+import { recordImapFailure } from "@remit/logger-lambda";
 import {
 	guardConnectionCursor,
+	type IImapConnection,
 	isCursorRebuildNeeded,
 	isMessageGoneFromOpenMailbox,
 	MailboxCursorPausedError,
 } from "@remit/mailbox-service";
 import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
+import { emitEvent } from "../emit.js";
 import type { MessageDeleteEvent } from "../events.js";
 import { isNotFoundError } from "../is-not-found.js";
 import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
 import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+import { resolveExhaustedMessageDeleteFailure } from "./message-delete-terminal.js";
+import { emitMoveResync, searchMailboxByMessageId } from "./message-move.js";
+
+/**
+ * Fallback when `MESSAGE_DELETE_MAX_ATTEMPTS` is unset (local dev, unit tests).
+ * Matches the `maxReceiveCount` the redrive policy of the queue `emit.ts`
+ * routes MESSAGE_DELETE onto uses (`remit-message-mgmt`,
+ * `deploy/vps/queues.json`), same pattern as `MESSAGE_MOVE_MAX_ATTEMPTS`.
+ */
+const DEFAULT_MESSAGE_DELETE_MAX_ATTEMPTS = 3;
+
+export const getMessageDeleteMaxAttempts = (
+	processEnv: NodeJS.ProcessEnv = process.env,
+): number => {
+	const raw = processEnv.MESSAGE_DELETE_MAX_ATTEMPTS;
+	if (!raw) return DEFAULT_MESSAGE_DELETE_MAX_ATTEMPTS;
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isFinite(parsed) && parsed > 0
+		? parsed
+		: DEFAULT_MESSAGE_DELETE_MAX_ATTEMPTS;
+};
+
+export const MESSAGE_DELETE_MAX_ATTEMPTS = getMessageDeleteMaxAttempts();
 
 /**
  * Delete every ThreadMessage row that points at this messageId.
@@ -122,11 +149,69 @@ export const buildThreadMessageUndelete = (
 	composites: currentComposites(threadMessage),
 });
 
+/**
+ * Settle a move to Trash the server left unconfirmed, by asking it two
+ * read-only questions instead of one. Both handles wrap the SAME connection but
+ * are scoped to their own mailbox: a `guardConnectionCursor` wrap binds its
+ * checks to the ONE mailbox snapshot it was built with, so the destination must
+ * never be opened through the source's guard.
+ *
+ * The source is asked first, and a source that still holds the uid ends it: the
+ * MOVE did not happen, so nothing at the destination can be this message.
+ * Skipping that question is not safe, because `searchMailboxByMessageId`
+ * returns the LOWEST matching uid rather than the one that just arrived, and
+ * one Message-ID can have several server copies in one account (a sieve
+ * `fileinto` + `keep`, a multi-label store, a resend) while
+ * `deriveMessageId` is folder-independent and gives them one local row. An
+ * ungated probe can hand back an earlier copy's uid, and Empty Trash then
+ * expunges by that uid. It also closes the second half of #912: an empty
+ * `uidMap` can mean the MOVE matched nothing at all.
+ *
+ * A row with no `messageIdHeader`, and a row that is already deleted, have
+ * nothing to probe with; they are distinct verdicts because no redelivery can
+ * change either answer.
+ */
+export type TrashMoveConfirmation =
+	| { outcome: "confirmed"; uid: number }
+	| { outcome: "still-at-source" }
+	| { outcome: "row-gone" }
+	| { outcome: "unprobeable" }
+	| { outcome: "unconfirmed" };
+
+const confirmTrashMoveUid = async (
+	sourceConnection: IImapConnection,
+	destinationConnection: IImapConnection,
+	messageService: Pick<IMessageRepository, "get">,
+	messageId: string,
+	sourceMailboxPath: string,
+	destinationMailboxPath: string,
+	uid: number,
+): Promise<TrashMoveConfirmation> => {
+	await sourceConnection.openBox(sourceMailboxPath, true);
+	if (!(await isMessageGoneFromOpenMailbox(sourceConnection, uid))) {
+		return { outcome: "still-at-source" };
+	}
+
+	const [message] = await messageService.get([messageId]);
+	if (!message) return { outcome: "row-gone" };
+	if (!message.messageIdHeader) return { outcome: "unprobeable" };
+
+	const probedUid = await searchMailboxByMessageId(
+		destinationConnection,
+		destinationMailboxPath,
+		message.messageIdHeader,
+	);
+	return probedUid === null
+		? { outcome: "unconfirmed" }
+		: { outcome: "confirmed", uid: probedUid };
+};
+
 export interface MessageDeleteDeps {
 	getClient: typeof getClient;
 	buildLifecycleDeps: typeof buildLifecycleDeps;
 	withOAuthLifecycle: typeof withOAuthLifecycle;
 	createConnectionScope: typeof createConnectionScopeWithCredentials;
+	emitEvent: typeof emitEvent;
 }
 
 const defaultDeps: MessageDeleteDeps = {
@@ -134,15 +219,22 @@ const defaultDeps: MessageDeleteDeps = {
 	buildLifecycleDeps,
 	withOAuthLifecycle,
 	createConnectionScope: createConnectionScopeWithCredentials,
+	emitEvent,
 };
 
 /**
  * Handle MESSAGE_DELETE events.
  * Either moves to Trash (IMAP MOVE) or permanently deletes (IMAP DELETE).
+ *
+ * A failing delete retries on redelivery until `receiveCount` reaches
+ * {@link MESSAGE_DELETE_MAX_ATTEMPTS}, at which point
+ * {@link resolveExhaustedMessageDeleteFailure} asks IMAP where the message
+ * actually is and settles the row into one terminal outcome (issue #980).
  */
 export const handleMessageDelete = async (
 	event: MessageDeleteEvent,
 	log: Logger,
+	receiveCount = 1,
 	deps: MessageDeleteDeps = defaultDeps,
 ): Promise<void> => {
 	const {
@@ -150,6 +242,7 @@ export const handleMessageDelete = async (
 		buildLifecycleDeps,
 		withOAuthLifecycle,
 		createConnectionScope: createConnectionScopeWithCredentials,
+		emitEvent,
 	} = deps;
 
 	const {
@@ -246,6 +339,80 @@ export const handleMessageDelete = async (
 		}
 	};
 
+	const settleExhaustedDelete = async (
+		accountConfigId: string,
+		getConnection: () => Promise<IImapConnection>,
+	): Promise<void> => {
+		const { outcome } = await resolveExhaustedMessageDeleteFailure(
+			{ messageService, threadMessageService, log },
+			{
+				accountId,
+				accountConfigId,
+				messageId,
+				uid,
+				sourceMailboxPath: mailboxPath,
+				getConnection,
+			},
+		);
+
+		if (outcome === "broken") {
+			recordImapFailure("MESSAGE_DELETE_EXHAUSTED", "other");
+			return;
+		}
+
+		if (destinationMailboxId) {
+			await emitMoveResync(emitEvent, {
+				accountId,
+				sourceMailboxId: mailboxId,
+				destinationMailboxId,
+			});
+		}
+	};
+
+	/**
+	 * Decide what an unconfirmed move to Trash does with this delivery. The
+	 * settle itself is `resolveExhaustedMessageDeleteFailure`, reached through
+	 * the attempt budget in the catch below — the two verdicts handled here are
+	 * the ones a redelivery could never answer.
+	 */
+	const settleUnconfirmedTrashMove = async (
+		confirmation: Exclude<TrashMoveConfirmation, { outcome: "confirmed" }>,
+		accountConfigId: string,
+		getConnection: () => Promise<IImapConnection>,
+	): Promise<void> => {
+		const context = {
+			accountId,
+			accountConfigId,
+			messageId,
+			uid,
+			mailboxPath,
+			receiveCount,
+			confirmation: confirmation.outcome,
+		};
+
+		if (confirmation.outcome === "row-gone") {
+			log.warn(
+				context,
+				"Move to trash unconfirmed and the local row is already gone; nothing left to settle",
+			);
+			return;
+		}
+
+		if (confirmation.outcome === "unprobeable") {
+			recordImapFailure("MESSAGE_DELETE_TRASH_MOVE_UNCONFIRMED", "other");
+			log.info(
+				context,
+				"Move to trash carries no Message-ID header to probe the destination with; settling on the source's answer alone",
+			);
+			await settleExhaustedDelete(accountConfigId, getConnection);
+			return;
+		}
+
+		throw new Error(
+			`Move to trash unconfirmed for message ${messageId} (attempt ${receiveCount}/${MESSAGE_DELETE_MAX_ATTEMPTS})`,
+		);
+	};
+
 	if (!isCurrentSchemaVersion(event.schemaVersion)) {
 		await abandonDelete(
 			"Refused to delete: event was minted under an unknown contract",
@@ -324,15 +491,50 @@ export const handleMessageDelete = async (
 							"Refused to delete: move to trash carries no destination mailbox",
 							"message_delete_missing_destination",
 						);
-					} else if (operation === "move_to_trash" && destinationMailboxPath) {
+					} else if (
+						operation === "move_to_trash" &&
+						destinationMailboxPath &&
+						destinationMailboxId
+					) {
 						// Move to Trash
 						const result = await connection.moveMessages(
 							[uid],
 							destinationMailboxPath,
 						);
-						const newUid = result.uidMap.get(uid);
 
-						if (newUid && destinationMailboxId) {
+						// UIDPLUS is an extension. A server without it answers a
+						// perfectly successful MOVE with no COPYUID entry, so an empty
+						// map is UNCONFIRMED, never evidence the move failed: the server
+						// is asked before any verdict, exactly as `handleMessageMove` and
+						// `attemptMove` do (issues #979, #665). A probe the server refused
+						// says nothing either way and counts as unconfirmed.
+						const copyUid = result.uidMap.get(uid);
+						const confirmation: TrashMoveConfirmation = copyUid
+							? { outcome: "confirmed", uid: copyUid }
+							: await confirmTrashMoveUid(
+									connection,
+									rawConnection,
+									messageService,
+									messageId,
+									mailboxPath,
+									destinationMailboxPath,
+									uid,
+								).catch((probeError: unknown) => {
+									log.warn(
+										{
+											messageId,
+											uid,
+											mailboxPath,
+											destinationMailboxPath,
+											probeError,
+										},
+										"Could not confirm the move to trash; keeping local rows",
+									);
+									return { outcome: "unconfirmed" } as const;
+								});
+
+						if (confirmation.outcome === "confirmed") {
+							const newUid = confirmation.uid;
 							// Update message with new UID in Trash
 							await messageService.updateUid(
 								messageId,
@@ -360,15 +562,14 @@ export const handleMessageDelete = async (
 							}
 
 							log.info({ messageId, newUid }, "Message moved to trash");
-						} else {
-							log.error(
-								{ messageId, uid },
-								"Failed to get new UID after move to trash",
-							);
-							await messageService.update(messageId, {
-								syncStatus: MessageSyncStatus.failed,
-							});
+							return;
 						}
+
+						await settleUnconfirmedTrashMove(
+							confirmation,
+							account.accountConfigId,
+							scope.getConnection,
+						);
 					} else {
 						// Permanent delete — reached only by `operation === "permanent_delete"`.
 						await connection.deleteMessages([uid]);
@@ -455,11 +656,28 @@ export const handleMessageDelete = async (
 						return;
 					}
 
-					// Mark as failed for other errors
-					await messageService.update(messageId, {
-						syncStatus: MessageSyncStatus.failed,
-					});
-					throw error;
+					if (receiveCount < MESSAGE_DELETE_MAX_ATTEMPTS) {
+						// Transient failure — connections drop. No alarm; redelivery
+						// retries, and `failed` marks the row unsettled meanwhile. It is
+						// not a terminal signal: only the resolver below settles anything.
+						await messageService.update(messageId, {
+							syncStatus: MessageSyncStatus.failed,
+						});
+						throw error;
+					}
+
+					// Budget exhausted. Settling here is what keeps a throwing
+					// `moveMessages` inside the ceiling: re-MOVEing a uid the source no
+					// longer holds fails identically on every redelivery, which is the
+					// failure this budget exists for.
+					await settleExhaustedDelete(
+						account.accountConfigId,
+						scope.getConnection,
+					);
+					log.error(
+						{ accountId, messageId, uid, mailboxPath, error: errorMessage },
+						"Delete retry exhausted; settled into a terminal outcome",
+					);
 				})
 				.finally(() => scope.disconnect());
 		},

package/src/processor.ts

@@ -38,7 +38,7 @@ export const processEvent = async (
 		case "MAILBOX_DELETE":
 			return processMailboxManagement(event, log);
 		case "MESSAGE_DELETE":
-			return handleMessageDelete(event, log);
+			return handleMessageDelete(event, log, receiveCount);
 		case "MESSAGE_MOVE":
 			return handleMessageMove(event, log, receiveCount);
 		case "PLACEMENT_MOVE_PUSH":