@remit/imap-worker 0.0.48 → 0.0.50

package/package.json

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

package/src/handlers/append-sent-message.test.ts

@@ -66,6 +66,7 @@ const fresh = (): Harness => ({
 		references: ["parent@example.com"],
 		inReplyTo: "parent@example.com",
 		sentAt: 1700000000000,
+		appendedUid: 0,
 	},
 	sentMailbox: { mailboxId: "sent-mbx", fullPath: "INBOX/Sent" },
 	append: async (path, raw, flags) => {
@@ -125,6 +126,9 @@ const event: AppendSentMessageEvent = {
 const called = (method: string): Call[] =>
 	h.calls.filter((c) => c.method === method);
 
+const patches = (): unknown[] =>
+	called("outboxMessage.update").map((c) => c.args[2]);
+
 type BackendClient = Awaited<ReturnType<AppendSentMessageDeps["getClient"]>>;
 
 const depsWithFailingDelete = (): AppendSentMessageDeps => {
@@ -146,6 +150,25 @@ const depsWithFailingDelete = (): AppendSentMessageDeps => {
 	};
 };
 
+const depsWithFailingUpdate = (): AppendSentMessageDeps => {
+	const base = deps();
+	return {
+		...base,
+		getClient: async (): Promise<BackendClient> => {
+			const client = await base.getClient();
+			return {
+				...client,
+				outboxMessage: {
+					...client.outboxMessage,
+					update: async (): Promise<never> => {
+						throw new Error("storage down");
+					},
+				},
+			};
+		},
+	};
+};
+
 describe("handleAppendSentMessage", () => {
 	beforeEach(() => {
 		h = fresh();
@@ -296,12 +319,10 @@ describe("handleAppendSentMessage", () => {
 
 		// The copy is in Sent, so the message is findable — settling it as unfiled
 		// would say the opposite.
-		assert.equal(called("outboxMessage.update").length, 0);
+		assert.deepEqual(patches(), [{ appendedUid: 55 }]);
 	});
 
 	it("stops redelivering a landed APPEND at the budget instead of filing another copy", async () => {
-		// A redelivery starts from the top and appends again, so retrying past the
-		// budget files one copy per attempt in the user's Sent folder (#830).
 		await handleAppendSentMessage(
 			event,
 			noopLog,
@@ -310,6 +331,119 @@ describe("handleAppendSentMessage", () => {
 		);
 
 		assert.equal(called("connection.append").length, 1);
-		assert.equal(called("outboxMessage.update").length, 0);
+		assert.deepEqual(patches(), [{ appendedUid: 55 }]);
+	});
+
+	it("records the uid the APPEND produced before it deletes the row", async () => {
+		await handleAppendSentMessage(event, noopLog, 1, deps());
+
+		// Order is the whole of it: a uid written after the delete is a uid a
+		// redelivery never sees, and the redelivery is what files the second copy.
+		const order = h.calls.map((c) => c.method);
+		assert.deepEqual(patches(), [{ appendedUid: 55 }]);
+		assert.ok(
+			order.indexOf("outboxMessage.update") <
+				order.indexOf("outboxMessage.delete"),
+		);
+	});
+
+	it("records a copy the server filed but named no uid for", async () => {
+		// UIDPLUS is an extension. Without it the APPEND succeeds and reports
+		// nothing, and "filed" still has to be told apart from "not filed".
+		h.append = async () => ({ uid: 0, uidValidity: 0 });
+
+		await handleAppendSentMessage(event, noopLog, 1, deps());
+
+		assert.deepEqual(patches(), [{ appendedUid: -1 }]);
+		assert.equal(called("outboxMessage.delete").length, 1);
+	});
+
+	it("files nothing a second time when a redelivery finds a recorded uid (#858)", async () => {
+		h.outbox = { ...h.outbox, appendedUid: 55 };
+
+		await handleAppendSentMessage(event, noopLog, 1, deps());
+
+		// The copy is already in the user's Sent folder. All this redelivery owes
+		// is the delete the last attempt could not make.
+		assert.equal(called("connection.append").length, 0);
+		assert.equal(h.disconnectCount, 0);
+		assert.deepEqual(called("outboxMessage.delete")[0]?.args, [
+			"cfg-1",
+			"out-1",
+		]);
+		assert.deepEqual(called("outboxAttachment.discardAll")[0]?.args, [
+			"cfg-1",
+			"acc-1",
+			"out-1",
+		]);
+	});
+
+	it("retries the delete a redelivery owes while the queue has attempts left", async () => {
+		h.outbox = { ...h.outbox, appendedUid: 55 };
+
+		await assert.rejects(
+			handleAppendSentMessage(event, noopLog, 1, depsWithFailingDelete()),
+			/storage down/,
+		);
+
+		assert.equal(called("connection.append").length, 0);
+		assert.deepEqual(patches(), []);
+	});
+
+	it("keeps the row when the uid cannot be recorded", async () => {
+		await assert.rejects(
+			handleAppendSentMessage(event, noopLog, 1, depsWithFailingUpdate()),
+			/storage down/,
+		);
+
+		// The other half of "written before the delete, never after". A row
+		// deleted without its uid is a row a redelivery reads as never filed.
+		assert.equal(called("outboxMessage.delete").length, 0);
+		assert.equal(called("outboxAttachment.discardAll").length, 0);
+	});
+
+	it("acks an event whose outbox row is already gone", async () => {
+		// Its own last attempt deleted it, or the boot repair dropped it. Throwing
+		// the same NotFoundError on every redelivery only dead-letters the record.
+		const notFound = Object.assign(new Error("gone"), {
+			name: "NotFoundError",
+		});
+		const base = deps();
+		const failing: AppendSentMessageDeps = {
+			...base,
+			getClient: async (): Promise<BackendClient> => {
+				const client = await base.getClient();
+				return {
+					...client,
+					outboxMessage: {
+						...client.outboxMessage,
+						get: async () => {
+							throw notFound;
+						},
+					},
+				} as BackendClient;
+			},
+		};
+
+		await handleAppendSentMessage(event, noopLog, 1, failing);
+
+		assert.equal(called("connection.append").length, 0);
+		assert.deepEqual(patches(), []);
+	});
+
+	it("gives up on that delete at the budget rather than dead-lettering it", async () => {
+		h.outbox = { ...h.outbox, appendedUid: 55 };
+
+		await handleAppendSentMessage(
+			event,
+			noopLog,
+			APPEND_SENT_MAX_ATTEMPTS,
+			depsWithFailingDelete(),
+		);
+
+		// The row stays `sent` and hidden, which the boot-time repair drops on the
+		// strength of the same recorded uid. Settling it as unfiled would tell the
+		// user a message sitting in Sent was never filed.
+		assert.deepEqual(patches(), []);
 	});
 });

package/src/handlers/append-sent-message.ts

@@ -1,4 +1,9 @@
 import { getClient } from "@remit/backend/client";
+import {
+	APPENDED_UID_NONE,
+	APPENDED_UID_UNREPORTED,
+	isSentCopyFiled,
+} from "@remit/data-ports";
 import { OutboxMessageStatus } from "@remit/domain-enums";
 import type { Logger } from "@remit/logger-lambda";
 import {
@@ -8,6 +13,7 @@ import {
 import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import type { AppendSentMessageEvent } 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";
 
@@ -17,6 +23,9 @@ const UNFILED_NO_SENT_MAILBOX =
 const UNFILED_SIGNED_OUT =
 	"Sent, but not filed: this account has to be signed in again before a copy can be stored in Sent.";
 
+const ROW_SURVIVED_ITS_DELETE =
+	"Sent message was filed but its outbox row survived its delete and stays hidden until the boot-time repair";
+
 const unfiledAppendRefused = (fullPath: string, error: unknown): string =>
 	`Sent, but not filed: the mail server refused to store a copy in ${fullPath} (${error instanceof Error ? error.message : String(error)}).`;
 
@@ -90,10 +99,23 @@ export const handleAppendSentMessage = async (
 		return;
 	}
 
-	const outbox = await outboxMessageService.get(
-		account.accountConfigId,
-		outboxMessageId,
-	);
+	// A row this event names can be gone by the time the event is redelivered:
+	// its own last attempt deleted it, or the boot repair dropped it on the
+	// strength of a recorded uid. Either way the work is done, and re-throwing
+	// the same NotFoundError on every redelivery only dead-letters it.
+	const outbox = await outboxMessageService
+		.get(account.accountConfigId, outboxMessageId)
+		.catch((error: unknown) => {
+			if (isNotFoundError(error)) return null;
+			throw error;
+		});
+	if (!outbox) {
+		log.warn(
+			{ accountId, outboxMessageId },
+			"Skipping APPEND_SENT_MESSAGE: the outbox row is already gone",
+		);
+		return;
+	}
 	if (outbox.status !== OutboxMessageStatus.sent) {
 		log.info(
 			{ outboxMessageId, status: outbox.status },
@@ -121,13 +143,58 @@ export const handleAppendSentMessage = async (
 		);
 	};
 
+	// The copy is in Sent, so the row is a leftover and deleting it is all that
+	// is left to do. Both steps are idempotent against a row that is already
+	// gone, so nothing here needs to know how far the last attempt got.
+	//
+	// Files first, row second, the same order outbox-queue.ts discards a draft
+	// in. Nothing but this row points at those objects: a row that outlives its
+	// files is hidden and the boot repair drops it, while files that outlive
+	// their row name a message nothing can reach and are vouched for forever.
+	const dropOutboxRow = async (): Promise<void> => {
+		await outboxAttachmentService.discardAll(
+			account.accountConfigId,
+			accountId,
+			outboxMessageId,
+		);
+		await outboxMessageService.delete(account.accountConfigId, outboxMessageId);
+		log.info(
+			{ outboxMessageId },
+			"Deleted outbox row after successful APPEND to Sent",
+		);
+	};
+
+	// Everything this recovers from happened after the copy reached Sent, so
+	// re-appending is off the table and the delete is the only step left to
+	// retry. Below the redrive budget that retry is worth having; at it the
+	// record would dead-letter, so the row is left at `sent` for the repair.
+	const retryDropWithinBudget = (error: unknown): void => {
+		if (receiveCount < APPEND_SENT_MAX_ATTEMPTS) throw error;
+		log.error({ accountId, outboxMessageId, error }, ROW_SURVIVED_ITS_DELETE);
+	};
+
+	// A redelivery of an event whose APPEND already landed. The copy is in the
+	// user's Sent folder and the only step still owed is the delete that failed
+	// last time; starting from the top would file a second copy of a message the
+	// user sent once (#858). Ahead of the Sent-mailbox lookup on purpose — a
+	// message that is already filed does not need one, and an account that lost
+	// its Sent appointment in between must not settle as unfiled.
+	if (isSentCopyFiled(outbox)) {
+		log.info(
+			{ outboxMessageId, appendedUid: outbox.appendedUid },
+			"Sent copy was already filed by an earlier attempt, skipping the APPEND",
+		);
+		await dropOutboxRow().catch(retryDropWithinBudget);
+		return;
+	}
+
 	const sentMailbox = await mailboxSpecialUseService.findSentMailbox(accountId);
 	if (!sentMailbox) {
 		await settleUnfiled(UNFILED_NO_SENT_MAILBOX);
 		return;
 	}
 
-	let appended = false;
+	let appendedUid = APPENDED_UID_NONE;
 
 	const failure = await withOAuthLifecycle(
 		buildLifecycleDeps(secrets, accountService),
@@ -157,33 +224,25 @@ export const handleAppendSentMessage = async (
 						"Appended sent message to Sent mailbox",
 					);
 
-					appended = true;
+					// A server without UIDPLUS files the copy and names no uid for
+					// it, which is still a filed copy and has to read as one.
+					appendedUid = result.uid > 0 ? result.uid : APPENDED_UID_UNREPORTED;
 				})
 				.finally(() => scope.disconnect());
 
-			// The message now lives in the IMAP Sent folder. Drop the outbox row so
-			// the user does not see it twice in the UI (Outbox + Sent). Issue #178.
-			//
-			// The row goes first, and nothing that can fail may come before it. The
-			// APPEND above has already happened; anything between it and this delete
-			// that throws leaves the row for the job to retry, and the retry appends
-			// a second copy to the user's Sent folder. A storage error is not worth
-			// a duplicate message — the attachment objects that outlive their row
-			// are exactly what the sweep collects, so losing this delete costs a
-			// sweep and nothing else.
-			await outboxMessageService.delete(
+			// The idempotency key, and the only reason a redelivery is safe. It is
+			// written before the delete and never after it: from here on every step
+			// can fail and be retried without the user gaining a second copy, and
+			// the one window that still can is this single row update.
+			await outboxMessageService.update(
 				account.accountConfigId,
 				outboxMessageId,
+				{ appendedUid },
 			);
-			await outboxAttachmentService.discardAll(
-				account.accountConfigId,
-				accountId,
-				outboxMessageId,
-			);
-			log.info(
-				{ outboxMessageId },
-				"Deleted outbox row after successful APPEND to Sent",
-			);
+
+			// The message now lives in the IMAP Sent folder. Drop the outbox row so
+			// the user does not see it twice in the UI (Outbox + Sent). Issue #178.
+			await dropOutboxRow();
 		},
 	).then(
 		() => null,
@@ -193,9 +252,9 @@ export const handleAppendSentMessage = async (
 			// attempt to pick up. At the budget the record would dead-letter, and a
 			// dead-lettered APPEND is exactly how a delivered message goes missing.
 			//
-			// The budget binds whether or not the APPEND landed. A redelivery
-			// starts from the top and appends again, so an unbudgeted retry files
-			// one copy per attempt in the user's Sent folder.
+			// The budget still binds after a landed APPEND, though no longer to
+			// hold off a duplicate: the recorded uid does that, and the retries
+			// the budget allows re-drive the delete alone.
 			if (receiveCount < APPEND_SENT_MAX_ATTEMPTS) throw error;
 			return error;
 		},
@@ -204,12 +263,12 @@ export const handleAppendSentMessage = async (
 	// The APPEND landed: the copy is in Sent whatever failed after it, so there
 	// is nothing to settle as unfiled. A row that outlives its delete holds
 	// `sent`, which every view hides, until the migrator's boot-time stranded-row
-	// repair settles it — the next container start, not sooner (#824).
-	if (appended) {
+	// repair drops it — the next container start, not sooner (#824).
+	if (isSentCopyFiled({ appendedUid })) {
 		if (failure) {
 			log.error(
 				{ accountId, outboxMessageId, reason: String(failure) },
-				"Sent message was filed but its outbox row survived its delete and stays hidden until the boot-time repair",
+				ROW_SURVIVED_ITS_DELETE,
 			);
 		}
 		return;

package/src/handlers/flag-push.ts

@@ -39,10 +39,10 @@ export const FLAG_PUSH_MAX_ATTEMPTS = getFlagPushMaxAttempts();
 /**
  * How long a marker may sit deferred behind a move before it is dropped
  * outright. A move that settles takes seconds to low minutes; one stuck past
- * this window has almost certainly already exhausted its own retries with no
- * terminal resolver of its own for a regular move (unlike flag-push and
- * placement-move), so deferring further would cycle one SQS round trip per
- * sync tick forever instead of surfacing the stall.
+ * this window has almost certainly already exhausted its own retries and been
+ * resolved as broken by its own terminal resolver, so deferring further would
+ * cycle one SQS round trip per sync tick forever instead of surfacing the
+ * stall.
  */
 const DEFAULT_FLAG_PUSH_DEFER_MAX_MS = 10 * 60 * 1000;
 

package/src/handlers/message-move-terminal.test.ts

@@ -0,0 +1,222 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type {
+	IMessageRepository,
+	IThreadMessageRepository,
+} from "@remit/data-ports";
+import type { IImapConnection } from "@remit/mailbox-service";
+import {
+	type MessageMoveTerminalLogger,
+	type ResolveExhaustedMessageMoveDeps,
+	resolveExhaustedMessageMoveFailure,
+} from "./message-move-terminal.js";
+
+interface LogEntry {
+	obj: Record<string, unknown>;
+	msg: string;
+}
+
+const buildLogger = (): {
+	log: MessageMoveTerminalLogger;
+	infos: LogEntry[];
+	errors: LogEntry[];
+} => {
+	const infos: LogEntry[] = [];
+	const errors: LogEntry[] = [];
+	return {
+		log: {
+			info: (obj, msg) => infos.push({ obj, msg }),
+			error: (obj, msg) => errors.push({ obj, msg }),
+		},
+		infos,
+		errors,
+	};
+};
+
+const buildConnection = (
+	present: Set<number>,
+	fetchDrops: Set<number> = new Set(),
+): IImapConnection =>
+	({
+		openBox: async () => ({}) as never,
+		fetchMessages: async (uids: number[]) =>
+			uids
+				.filter((uid) => present.has(uid) && !fetchDrops.has(uid))
+				.map((uid) => ({ uid }) as unknown as never),
+		search: async (criteria: unknown[]) => {
+			const [, value] = (criteria as Array<[string, string]>)[0];
+			const uid = Number(value);
+			return present.has(uid) ? [uid] : [];
+		},
+	}) as unknown as IImapConnection;
+
+interface MessageRow {
+	messageId: string;
+	mailboxId: string;
+	uid: number;
+	status: string;
+	syncStatus: string;
+	originalMailboxId: string;
+	originalUid: number;
+}
+
+/**
+ * The move's pending state IS the Message row, so these fakes hold real rows
+ * and the assertions read the rows back — a resolver that reverted the
+ * optimistic move (PR #652's defect) would show up here as a changed row, not
+ * as an uncalled mock.
+ */
+const buildRepositories = (row: MessageRow) => {
+	const messages = new Map<string, MessageRow>([[row.messageId, row]]);
+	const threadMessages = new Map<
+		string,
+		{ accountConfigId: string; threadMessageId: string }
+	>([
+		[
+			`tm-${row.messageId}`,
+			{ accountConfigId: "cfg-1", threadMessageId: `tm-${row.messageId}` },
+		],
+	]);
+
+	return {
+		messages,
+		threadMessages,
+		messageService: {
+			delete: async (messageId: string) => {
+				messages.delete(messageId);
+			},
+			update: async (messageId: string, input: Partial<MessageRow>) => {
+				const current = messages.get(messageId);
+				if (current) messages.set(messageId, { ...current, ...input });
+			},
+		} as unknown as Pick<IMessageRepository, "delete">,
+		threadMessageService: {
+			findAllByMessageId: async () => [...threadMessages.values()],
+			deleteMany: async (
+				keys: Array<{ accountConfigId: string; threadMessageId: string }>,
+			) => {
+				for (const key of keys) threadMessages.delete(key.threadMessageId);
+			},
+		} as unknown as Pick<
+			IThreadMessageRepository,
+			"findAllByMessageId" | "deleteMany"
+		>,
+	};
+};
+
+const pendingMoveRow = (): MessageRow => ({
+	messageId: "msg-1",
+	mailboxId: "mbx-archive",
+	uid: 101,
+	status: "moving",
+	syncStatus: "failed",
+	originalMailboxId: "mbx-inbox",
+	originalUid: 101,
+});
+
+const input = {
+	accountId: "acc-1",
+	accountConfigId: "cfg-1",
+	messageId: "msg-1",
+	uid: 101,
+	sourceMailboxPath: "INBOX",
+};
+
+describe("resolveExhaustedMessageMoveFailure — the two terminal outcomes (issue #655)", () => {
+	it("RECONCILED: the message is gone from the move's source — stale row reconciled, no alarm", async () => {
+		const repos = buildRepositories(pendingMoveRow());
+		const { log, infos, errors } = buildLogger();
+		const deps: ResolveExhaustedMessageMoveDeps = {
+			messageService: repos.messageService,
+			threadMessageService: repos.threadMessageService,
+			log,
+		};
+
+		const result = await resolveExhaustedMessageMoveFailure(deps, {
+			...input,
+			getConnection: async () => buildConnection(new Set()),
+		});
+
+		assert.equal(result.outcome, "reconciled");
+		assert.equal(
+			repos.messages.get("msg-1"),
+			undefined,
+			"the stale Message row is deleted so a resync can re-project it",
+		);
+		assert.equal(repos.threadMessages.size, 0);
+		assert.equal(errors.length, 0, "no alarm for the expected/routine outcome");
+		assert.ok(
+			infos.some((e) => e.obj.metric === "message_move_stale_row_reconciled"),
+		);
+	});
+
+	it("BROKEN: the message is still at the source — the row is left EXACTLY as it stands, alarm logged, never re-thrown", async () => {
+		const repos = buildRepositories(pendingMoveRow());
+		const { log, errors } = buildLogger();
+		const deps: ResolveExhaustedMessageMoveDeps = {
+			messageService: repos.messageService,
+			threadMessageService: repos.threadMessageService,
+			log,
+		};
+
+		const result = await resolveExhaustedMessageMoveFailure(deps, {
+			...input,
+			getConnection: async () => buildConnection(new Set([101])),
+		});
+
+		assert.equal(result.outcome, "broken");
+		assert.deepEqual(
+			repos.messages.get("msg-1"),
+			pendingMoveRow(),
+			"a move that never reached the server is never reverted locally (PR #652)",
+		);
+		assert.equal(repos.threadMessages.size, 1);
+		assert.ok(errors.some((e) => e.obj.alert === "message_move_failed"));
+	});
+
+	it("BROKEN: an empty FETCH the SEARCH contradicts never counts as gone", async () => {
+		const repos = buildRepositories(pendingMoveRow());
+		const { log } = buildLogger();
+		const deps: ResolveExhaustedMessageMoveDeps = {
+			messageService: repos.messageService,
+			threadMessageService: repos.threadMessageService,
+			log,
+		};
+
+		const result = await resolveExhaustedMessageMoveFailure(deps, {
+			...input,
+			getConnection: async () =>
+				buildConnection(new Set([101]), new Set([101])),
+		});
+
+		assert.equal(result.outcome, "broken");
+		assert.deepEqual(repos.messages.get("msg-1"), pendingMoveRow());
+	});
+
+	it("an unreachable server reaches no verdict at all — the probe propagates and the row is untouched", async () => {
+		const repos = buildRepositories(pendingMoveRow());
+		const { log } = buildLogger();
+		const deps: ResolveExhaustedMessageMoveDeps = {
+			messageService: repos.messageService,
+			threadMessageService: repos.threadMessageService,
+			log,
+		};
+
+		await assert.rejects(
+			() =>
+				resolveExhaustedMessageMoveFailure(deps, {
+					...input,
+					getConnection: async () => {
+						throw new Error("ECONNRESET");
+					},
+				}),
+			/ECONNRESET/,
+		);
+
+		assert.deepEqual(
+			repos.messages.get("msg-1"),
+			pendingMoveRow(),
+			"absence is only ever concluded from an answer the server gave",
+		);
+	});
+});

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

@@ -0,0 +1,122 @@
+import {
+	type IImapConnection,
+	isMessageGoneFromOpenMailbox,
+	reconcileStaleMessage,
+	type StaleMessageReconcileDeps,
+} from "@remit/mailbox-service";
+
+export interface MessageMoveTerminalLogger {
+	info(obj: Record<string, unknown>, msg: string): void;
+	error(obj: Record<string, unknown>, msg: string): void;
+}
+
+export interface ResolveExhaustedMessageMoveDeps
+	extends StaleMessageReconcileDeps {
+	log: MessageMoveTerminalLogger;
+}
+
+export interface ResolveExhaustedMessageMoveInput {
+	accountId: string;
+	accountConfigId: string;
+	messageId: string;
+	uid: number;
+	sourceMailboxPath: string;
+	getConnection: () => Promise<IImapConnection>;
+}
+
+export type MessageMoveTerminalOutcome = "reconciled" | "broken";
+
+export interface ResolveExhaustedMessageMoveResult {
+	outcome: MessageMoveTerminalOutcome;
+}
+
+/**
+ * Resolve a MESSAGE_MOVE failure that has exhausted the message queue's
+ * redelivery budget into exactly one of two terminal outcomes, mirroring
+ * `resolveExhaustedPlacementMoveFailure` and `resolveExhaustedFlagPushFailure`
+ * for the same failure taxonomy (issue #655) — no third, softer outcome.
+ *
+ * The move's pending state is the Message row itself (`status: moving`,
+ * `originalMailboxId`/`originalUid`, `mailboxId` already pointing at the
+ * destination), not a separate marker, so the outcomes act on that row.
+ *
+ * 1. RECONCILED (expected) — the message no longer exists at the move's source
+ *    on IMAP, confirmed by {@link isMessageGoneFromOpenMailbox} rather than by
+ *    a FETCH coming back empty. Either the MOVE did execute server-side and
+ *    the connection dropped before the tagged OK was read, or a foreign client
+ *    moved or expunged the message; from here those are indistinguishable and
+ *    have the same answer. The stale Message/ThreadMessage rows are deleted
+ *    via {@link reconcileStaleMessage} and the caller resyncs both 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 move never took
+ *    effect, but it keeps failing: broken code or a broken account, not a
+ *    transient blip. Local state is left exactly as it stands. Reverting the
+ *    optimistic move here is what PR #652 was pulled for: the local row is the
+ *    only record that this move is still owed, and a revert races a MOVE that
+ *    may yet have landed. Logged with an `alert`-shaped entry for an operator
+ *    alarm; never re-thrown (terminal — the caller acks either way, since
+ *    retrying a permanently-broken move can never succeed).
+ *
+ * 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.
+ *
+ * An operator reading `message_move_failed` should know one case where the
+ * message is not actually at the source: a message another client expunged
+ * mid-session can answer an empty FETCH while the server still lists its UID
+ * in SEARCH, until it is allowed to send the untagged EXPUNGE. That message
+ * lands in BROKEN, and BROKEN is terminal — the row stays pending and the
+ * alert stands until someone clears it. The reverse mistake discards the row
+ * for live mail, so the cost is paid deliberately.
+ */
+export const resolveExhaustedMessageMoveFailure = async (
+	deps: ResolveExhaustedMessageMoveDeps,
+	input: ResolveExhaustedMessageMoveInput,
+): Promise<ResolveExhaustedMessageMoveResult> => {
+	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_move_stale_row_reconciled",
+				accountId,
+				accountConfigId,
+				messageId,
+				uid,
+				sourceMailboxPath,
+				threadMessagesDeleted,
+			},
+			"Message no longer at its move source after retry exhaustion (move landed server-side, or an external delete or move); stale row reconciled",
+		);
+		return { outcome: "reconciled" };
+	}
+
+	deps.log.error(
+		{
+			alert: "message_move_failed",
+			accountId,
+			accountConfigId,
+			messageId,
+			uid,
+			sourceMailboxPath,
+		},
+		"Message move could not be pushed to IMAP after retry exhaustion; message still exists at its source — local state left pending for operator investigation",
+	);
+	return { outcome: "broken" };
+};

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

@@ -7,7 +7,9 @@ import type { MessageMoveEvent } from "../events.js";
 import {
 	buildThreadMessageMoveUpdate,
 	emitMoveResync,
+	getMessageMoveMaxAttempts,
 	handleMessageMove,
+	MESSAGE_MOVE_MAX_ATTEMPTS,
 	moveThenResync,
 } from "./message-move.js";
 
@@ -185,7 +187,39 @@ describe("moveThenResync (#1031)", () => {
 	});
 });
 
-describe("handleMessageMove — deleted mailbox is terminal (#287/#289)", () => {
+describe("getMessageMoveMaxAttempts — env-derived threshold (#655)", () => {
+	it("parses the injected env var", () => {
+		assert.equal(
+			getMessageMoveMaxAttempts({ MESSAGE_MOVE_MAX_ATTEMPTS: "3" }),
+			3,
+		);
+		assert.equal(
+			getMessageMoveMaxAttempts({ MESSAGE_MOVE_MAX_ATTEMPTS: "5" }),
+			5,
+		);
+	});
+
+	it("defaults to the message queue's own maxReceiveCount when unset", () => {
+		assert.equal(getMessageMoveMaxAttempts({}), 3);
+	});
+
+	it("defaults on a non-numeric or non-positive value", () => {
+		assert.equal(
+			getMessageMoveMaxAttempts({ MESSAGE_MOVE_MAX_ATTEMPTS: "nope" }),
+			3,
+		);
+		assert.equal(
+			getMessageMoveMaxAttempts({ MESSAGE_MOVE_MAX_ATTEMPTS: "0" }),
+			3,
+		);
+	});
+
+	it("MESSAGE_MOVE_MAX_ATTEMPTS is a concrete, positive number at module load", () => {
+		assert.ok(MESSAGE_MOVE_MAX_ATTEMPTS > 0);
+	});
+});
+
+describe("handleMessageMove — the move's own pending state gates every attempt", () => {
 	const acctId = "mm-acc-zzz";
 
 	const cappedAccount = (): AccountItem =>
@@ -219,13 +253,25 @@ describe("handleMessageMove — deleted mailbox is terminal (#287/#289)", () =>
 		timestamp: 1700000000000,
 	} as MessageMoveEvent;
 
+	const pendingRow = () => ({
+		messageId: "mm-msg-zzz",
+		mailboxId: "mm-dst-zzz",
+		uid: 10,
+		status: "moving",
+		syncStatus: "pending",
+	});
+
 	// The client is supplied by injection (`setClient`), so these tests register
 	// the repositories they then mock rather than reaching a composition.
 	before(() => {
 		setClient({
 			account: { get: async () => undefined },
 			mailbox: { get: async () => undefined },
-			message: { updateUid: async () => undefined },
+			message: {
+				get: async () => [],
+				update: async () => undefined,
+				updateUid: async () => undefined,
+			},
 			secrets: { decrypt: async () => undefined },
 		} as unknown as RemitClient);
 	});
@@ -236,6 +282,7 @@ describe("handleMessageMove — deleted mailbox is terminal (#287/#289)", () =>
 		const client = await getClient();
 		mock.method(client.account, "get", async () => cappedAccount());
 		mock.method(client.secrets, "decrypt", async () => "fake-password");
+		mock.method(client.message, "get", async () => [pendingRow()]);
 		mock.method(client.mailbox, "get", async () => {
 			throw Object.assign(new Error("Mailbox not found: mm-src-zzz"), {
 				name: "NotFoundError",
@@ -252,4 +299,44 @@ describe("handleMessageMove — deleted mailbox is terminal (#287/#289)", () =>
 			"a deleted mailbox never reaches the IMAP move",
 		);
 	});
+
+	// Without this gate a redelivery of an already-confirmed move re-runs the
+	// MOVE against a UID the source no longer holds, and on exhaustion the
+	// terminal resolver reads the source's honest "gone" as grounds to delete a
+	// row that is correct and settled.
+	it("acks without connecting when the move already settled", async () => {
+		const client = await getClient();
+		mock.method(client.account, "get", async () => cappedAccount());
+		mock.method(client.secrets, "decrypt", async () => "fake-password");
+		mock.method(client.message, "get", async () => [
+			{ ...pendingRow(), uid: 4711, status: "active", syncStatus: "synced" },
+		]);
+		const mailboxGet = mock.method(client.mailbox, "get", async () => {
+			throw new Error("a settled move must never resolve a mailbox");
+		});
+		const update = mock.method(client.message, "update", async () => {});
+
+		await handleMessageMove(event, silentLogger, MESSAGE_MOVE_MAX_ATTEMPTS);
+
+		assert.equal(mailboxGet.mock.calls.length, 0);
+		assert.equal(
+			update.mock.calls.length,
+			0,
+			"a settled row is never written again",
+		);
+	});
+
+	it("acks without connecting when the message row is already gone", async () => {
+		const client = await getClient();
+		mock.method(client.account, "get", async () => cappedAccount());
+		mock.method(client.secrets, "decrypt", async () => "fake-password");
+		mock.method(client.message, "get", async () => []);
+		const mailboxGet = mock.method(client.mailbox, "get", async () => {
+			throw new Error("a missing row must never resolve a mailbox");
+		});
+
+		await handleMessageMove(event, silentLogger, MESSAGE_MOVE_MAX_ATTEMPTS);
+
+		assert.equal(mailboxGet.mock.calls.length, 0);
+	});
 });

package/src/handlers/message-move.ts

@@ -1,10 +1,13 @@
 import { getClient } from "@remit/backend/client";
 import type { ThreadMessageItem } from "@remit/data-ports";
-import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
+import { MessageSyncStatus } from "@remit/domain-enums";
 import type { Logger } from "@remit/logger-lambda";
+import { recordImapFailure } from "@remit/logger-lambda";
 import {
 	guardConnectionCursor,
+	type IImapConnection,
 	isCursorRebuildNeeded,
+	isPlacementUnsettled,
 	MailboxCursorPausedError,
 } from "@remit/mailbox-service";
 import { isAccountDeleted } from "../account-check.js";
@@ -14,6 +17,28 @@ import type { MessageMoveEvent, SyncMessagesEvent } 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 { resolveExhaustedMessageMoveFailure } from "./message-move-terminal.js";
+
+/**
+ * Fallback when `MESSAGE_MOVE_MAX_ATTEMPTS` is unset (local dev, unit tests).
+ * Matches the `maxReceiveCount` the message queue's redrive policy uses
+ * (`remit-messages.fifo`, `deploy/vps/queues.json`), same pattern as
+ * `FLAG_PUSH_MAX_ATTEMPTS` and `PLACEMENT_MOVE_MAX_ATTEMPTS`.
+ */
+const DEFAULT_MESSAGE_MOVE_MAX_ATTEMPTS = 3;
+
+export const getMessageMoveMaxAttempts = (
+	processEnv: NodeJS.ProcessEnv = process.env,
+): number => {
+	const raw = processEnv.MESSAGE_MOVE_MAX_ATTEMPTS;
+	if (!raw) return DEFAULT_MESSAGE_MOVE_MAX_ATTEMPTS;
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isFinite(parsed) && parsed > 0
+		? parsed
+		: DEFAULT_MESSAGE_MOVE_MAX_ATTEMPTS;
+};
+
+export const MESSAGE_MOVE_MAX_ATTEMPTS = getMessageMoveMaxAttempts();
 
 type EmitSyncMessages = (
 	event: Omit<SyncMessagesEvent, "eventId" | "timestamp">,
@@ -41,6 +66,23 @@ export const emitMoveResync = async (
 	);
 };
 
+/**
+ * SEARCH a mailbox for a message by its RFC822 Message-ID header. Read-only
+ * (EXAMINE, not SELECT) — this is a verification probe, never a write.
+ * Returns the first matching UID, or `null` if nothing matched.
+ */
+export const searchMailboxByMessageId = async (
+	connection: IImapConnection,
+	mailboxPath: string,
+	messageIdHeader: string,
+): Promise<number | null> => {
+	await connection.openBox(mailboxPath, true);
+	const uids = await connection.search([
+		`HEADER Message-ID "${messageIdHeader}"`,
+	]);
+	return uids[0] ?? null;
+};
+
 /**
  * Resync the affected folders only once the IMAP move has resolved. A move that
  * fails (or is retried) must not refresh counts off a move that didn't happen,
@@ -97,10 +139,18 @@ export const buildThreadMessageMoveUpdate = (
 /**
  * Handle MESSAGE_MOVE events.
  * Executes IMAP MOVE command and updates local state with new UID.
+ *
+ * A failing move retries on SQS redelivery until `receiveCount` reaches
+ * {@link MESSAGE_MOVE_MAX_ATTEMPTS}, at which point
+ * {@link resolveExhaustedMessageMoveFailure} asks IMAP where the message
+ * actually is and settles the row into one terminal outcome (issue #655).
+ * Before that, `syncStatus: failed` marked every attempt and nothing ever
+ * settled the row, so an exhausted move sat `moving`/`failed` forever.
  */
 export const handleMessageMove = async (
 	event: MessageMoveEvent,
 	log: Logger,
+	receiveCount = 1,
 ): Promise<void> => {
 	const {
 		account: accountService,
@@ -140,6 +190,32 @@ export const handleMessageMove = async (
 		return;
 	}
 
+	const [message] = await messageService.get([messageId]);
+
+	// The message row is already gone — some other reconciliation path deleted
+	// it. The move is moot; ack without touching IMAP.
+	if (!message) {
+		log.warn(
+			{ accountId, messageId },
+			"Skipping MESSAGE_MOVE: message row no longer exists",
+		);
+		return;
+	}
+
+	// This move already settled — `updateUid` cleared `status: moving` once the
+	// server confirmed it. A redelivery reaching here would MOVE a UID the
+	// source no longer holds, fail, and on exhaustion read the source's honest
+	// "gone" as grounds to reconcile away a row that is correct. There is no
+	// marker to find missing (unlike FLAG_PUSH and PLACEMENT_MOVE_PUSH), so the
+	// row's own pending marker is what stands in for one.
+	if (!isPlacementUnsettled(message)) {
+		log.info(
+			{ accountId, messageId, uid: message.uid, status: message.status },
+			"Skipping MESSAGE_MOVE: the move already settled against confirmed IMAP state",
+		);
+		return;
+	}
+
 	await withOAuthLifecycle(
 		buildLifecycleDeps(secrets, accountService),
 		account,
@@ -200,56 +276,65 @@ export const handleMessageMove = async (
 								destinationMailboxPath,
 							);
 
-							// Get new UID from COPYUID response
-							const newUid = result.uidMap.get(uid);
+							// Get new UID from COPYUID response. A server without UIDPLUS
+							// answers a perfectly successful MOVE with no COPYUID entry,
+							// so an empty map is UNCONFIRMED, never evidence the message
+							// is gone: the destination is asked by Message-ID before any
+							// verdict, exactly as `attemptMove` does. Marking the row
+							// `failed` and returning (the behaviour issue #655 opens on)
+							// left it `moving`/`failed` with no DLQ entry and no metric,
+							// because a handler that returns never redelivers.
+							const newUid =
+								result.uidMap.get(uid) ??
+								(message.messageIdHeader
+									? await searchMailboxByMessageId(
+											rawConnection,
+											destinationMailboxPath,
+											message.messageIdHeader,
+										)
+									: null);
 
-							if (newUid) {
-								// Update message with new UID
-								await messageService.updateUid(
-									messageId,
-									newUid,
-									destinationMailboxId,
+							if (!newUid) {
+								throw new Error(
+									`Message move unconfirmed (no COPYUID entry, not found at ${destinationMailboxPath}) — retrying`,
 								);
+							}
 
-								// Update ThreadMessage UID and mailboxId
-								const threadMessage =
-									await threadMessageService.findByMessageId(
-										account.accountConfigId,
-										messageId,
-									);
-								if (threadMessage) {
-									const args = buildThreadMessageMoveUpdate(
-										threadMessage,
-										newUid,
-										destinationMailboxId,
-									);
-									await threadMessageService.update(
-										threadMessage.accountConfigId,
-										threadMessage.threadMessageId,
-										args.set,
-										{ composites: args.composites },
-									);
-								}
-
-								log.info(
-									{
-										messageId,
-										oldUid: uid,
-										newUid,
-										destination: destinationMailboxPath,
-									},
-									"Message moved successfully",
+							// Update message with new UID
+							await messageService.updateUid(
+								messageId,
+								newUid,
+								destinationMailboxId,
+							);
+
+							// Update ThreadMessage UID and mailboxId
+							const threadMessage = await threadMessageService.findByMessageId(
+								account.accountConfigId,
+								messageId,
+							);
+							if (threadMessage) {
+								const args = buildThreadMessageMoveUpdate(
+									threadMessage,
+									newUid,
+									destinationMailboxId,
 								);
-							} else {
-								// Message may have been deleted on server
-								log.error(
-									{ messageId, uid },
-									"Message not found in COPYUID response - may have been deleted",
+								await threadMessageService.update(
+									threadMessage.accountConfigId,
+									threadMessage.threadMessageId,
+									args.set,
+									{ composites: args.composites },
 								);
-								await messageService.update(messageId, {
-									syncStatus: MessageSyncStatus.failed,
-								});
 							}
+
+							log.info(
+								{
+									messageId,
+									oldUid: uid,
+									newUid,
+									destination: destinationMailboxPath,
+								},
+								"Message moved successfully",
+							);
 						},
 						() =>
 							emitMoveResync(emitEvent, {
@@ -284,31 +369,59 @@ export const handleMessageMove = async (
 						);
 						const connection = await scope.getConnection();
 						await connection.createMailbox(destinationMailboxPath);
-						// Re-throw to let the event be retried
+						// Re-throw to let the event be retried against the folder just
+						// created. Kept unconditional past the attempt budget: the
+						// destination now exists, so the record is worth redriving from
+						// the DLQ, and the terminal resolver has nothing to settle — it
+						// would find the message exactly where it started.
 						throw error;
 					}
 
-					// Handle message not found on IMAP - already moved/deleted (idempotent)
-					if (
-						errorMessage.includes("not found") ||
-						errorMessage.includes("NONEXISTENT")
-					) {
-						log.info(
-							{ messageId, uid },
-							"Message not found on IMAP, updating local state as synced",
-						);
+					if (receiveCount < MESSAGE_MOVE_MAX_ATTEMPTS) {
+						// Transient move failure — expected (connections drop). No
+						// alarm; queue redelivery retries, and `failed` marks the row
+						// as unsettled meanwhile. It is not a terminal signal: only the
+						// resolver below settles anything.
 						await messageService.update(messageId, {
-							status: MessageStatus.active,
-							syncStatus: MessageSyncStatus.synced,
+							syncStatus: MessageSyncStatus.failed,
+						});
+						throw error;
+					}
+
+					// Redelivery budget exhausted: resolve into exactly one of the two
+					// terminal outcomes instead of dead-lettering with no diagnosis,
+					// and never by inferring the server's state from our own failures.
+					const { outcome } = await resolveExhaustedMessageMoveFailure(
+						{ messageService, threadMessageService, log },
+						{
+							accountId,
+							accountConfigId: account.accountConfigId,
+							messageId,
+							uid,
+							sourceMailboxPath,
+							getConnection: scope.getConnection,
+						},
+					);
+
+					if (outcome === "reconciled") {
+						// Whichever folder the message actually sits in re-projects it
+						// with the server's own UID.
+						await emitMoveResync(emitEvent, {
+							accountId,
+							sourceMailboxId,
+							destinationMailboxId,
 						});
 						return;
 					}
 
-					// Mark as failed for other errors
-					await messageService.update(messageId, {
-						syncStatus: MessageSyncStatus.failed,
-					});
-					throw error;
+					// Terminal and never re-thrown, so the handler-outcome series
+					// records this record as a success. Counted here or it is invisible.
+					recordImapFailure("MESSAGE_MOVE_EXHAUSTED", "other");
+					log.error(
+						{ error: errorMessage },
+						"Message move retry exhausted; message still exists at its source",
+					);
+					// Terminal — never re-thrown, so the caller acks either way.
 				})
 				.finally(() => scope.disconnect());
 		},

package/src/handlers/placement-move-push.ts

@@ -20,6 +20,7 @@ import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
 import {
 	buildThreadMessageMoveUpdate,
 	emitMoveResync,
+	searchMailboxByMessageId,
 } from "./message-move.js";
 
 /**
@@ -48,23 +49,6 @@ interface MoveOutcome {
 	newUid?: number;
 }
 
-/**
- * SEARCH a mailbox for a message by its RFC822 Message-ID header. Read-only
- * (EXAMINE, not SELECT) — this is a verification probe, never a write.
- * Returns the first matching UID, or `null` if nothing matched.
- */
-const searchMailboxByMessageId = async (
-	connection: IImapConnection,
-	mailboxPath: string,
-	messageIdHeader: string,
-): Promise<number | null> => {
-	await connection.openBox(mailboxPath, true);
-	const uids = await connection.search([
-		`HEADER Message-ID "${messageIdHeader}"`,
-	]);
-	return uids[0] ?? null;
-};
-
 /**
  * Attempt the IMAP MOVE.
  *

package/src/processor.ts

@@ -18,12 +18,11 @@ export const processEvent = async (
 	log: Logger,
 	/**
 	 * SQS's own delivery count for the record carrying this event (1 on first
-	 * delivery). Read by SYNC_MESSAGE_BODY, PLACEMENT_MOVE_PUSH, FLAG_PUSH and
-	 * APPEND_SENT_MESSAGE — each knows from it when this is the last attempt
-	 * before the queue's
-	 * own redrive policy would DLQ the record, so it can resolve
-	 * retry exhaustion into a terminal outcome (issue #1270) instead of
-	 * dead-lettering blindly.
+	 * delivery). Read by SYNC_MESSAGE_BODY, PLACEMENT_MOVE_PUSH, FLAG_PUSH,
+	 * APPEND_SENT_MESSAGE and MESSAGE_MOVE — each knows from it when this is
+	 * the last attempt before the queue's own redrive policy would DLQ the
+	 * record, so it can resolve retry exhaustion into a terminal outcome
+	 * (issue #1270) instead of dead-lettering blindly.
 	 */
 	receiveCount = 1,
 ): Promise<void> => {
@@ -41,7 +40,7 @@ export const processEvent = async (
 		case "MESSAGE_DELETE":
 			return handleMessageDelete(event, log);
 		case "MESSAGE_MOVE":
-			return handleMessageMove(event, log);
+			return handleMessageMove(event, log, receiveCount);
 		case "PLACEMENT_MOVE_PUSH":
 			return handlePlacementMovePush(event, log, receiveCount);
 		case "FLAG_PUSH":