@remit/imap-worker 0.0.49 → 0.0.51

package/package.json

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

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-delete.test.ts

@@ -205,6 +205,8 @@ interface Connection {
 	) => Promise<{ uidMap: Map<number, number> }>;
 	deleteMessages: (uids: number[]) => Promise<void>;
 	createMailbox: (path: string) => Promise<void>;
+	fetchMessages: (uids: number[]) => Promise<{ uid: number }[]>;
+	search: (criteria: unknown[]) => Promise<number[]>;
 }
 
 interface Harness {
@@ -217,6 +219,7 @@ interface Harness {
 	mailbox: { mailboxId: string; uidValidity: number; cursorState?: string };
 	mailboxError?: Error;
 	connection: Connection;
+	threadMessageUpdateError?: Error;
 	threadMessage: Record<string, unknown> | null;
 	allThreadMessages: { accountConfigId: string; threadMessageId: string }[];
 	getConnectionCount: number;
@@ -240,8 +243,23 @@ const buildConnection = (): Connection => ({
 	createMailbox: record(
 		"connection.createMailbox",
 	) as Connection["createMailbox"],
+	// The source box still holds the uid unless a case says otherwise, so the
+	// presence probe only reports "gone" where a test made it true.
+	fetchMessages: async (uids: number[]) => uids.map((uid) => ({ uid })),
+	search: async (...args: unknown[]) => {
+		h.calls.push({ method: "connection.search", args });
+		return [10];
+	},
 });
 
+const sourceNoLongerHoldsTheUid = (): void => {
+	h.connection.fetchMessages = async () => [];
+	h.connection.search = async (...args: unknown[]) => {
+		h.calls.push({ method: "connection.search", args });
+		return [];
+	};
+};
+
 const fresh = (): Harness => ({
 	calls: [],
 	account: { accountId: "acc-1", accountConfigId: "cfg-1" },
@@ -277,7 +295,10 @@ const deps = (): MessageDeleteDeps =>
 			threadMessage: {
 				findByMessageId: async () => h.threadMessage,
 				findAllByMessageId: async () => h.allThreadMessages,
-				update: record("threadMessage.update"),
+				update: async (...args: unknown[]) => {
+					h.calls.push({ method: "threadMessage.update", args });
+					if (h.threadMessageUpdateError) throw h.threadMessageUpdateError;
+				},
 				delete: record("threadMessage.delete"),
 			},
 			mailbox: {
@@ -440,10 +461,13 @@ describe("handleMessageDelete", () => {
 		);
 	});
 
-	it("cleans up locally and swallows the error when the message is already gone on IMAP", async () => {
+	// Regression on #212: a permanent delete the server has already applied must
+	// still reconcile the local rows, now that the text alone no longer decides.
+	it("cleans up locally and swallows the error when the message is confirmed gone on IMAP", async () => {
 		h.connection.deleteMessages = async () => {
 			throw new Error("NONEXISTENT uid");
 		};
+		sourceNoLongerHoldsTheUid();
 
 		await handleMessageDelete(permanentEvent, noopLog, deps());
 
@@ -451,6 +475,109 @@ describe("handleMessageDelete", () => {
 		assert.equal(called("threadMessage.delete").length, 2);
 	});
 
+	// Issue #845. The three cases below are the same bug from three directions:
+	// "not found" in an error string is never on its own a reason to destroy the
+	// only local record of live mail.
+
+	it("keeps the rows when a move-to-trash fails after the MOVE landed", async () => {
+		// The MOVE succeeded; the ThreadMessage write behind it did not. The
+		// message is sitting in Trash, and the NotFoundError names a local row,
+		// not a mail-server one.
+		h.threadMessageUpdateError = Object.assign(
+			new Error("Thread message not found"),
+			{ name: "NotFoundError" },
+		);
+		sourceNoLongerHoldsTheUid();
+
+		await assert.rejects(
+			handleMessageDelete(moveEvent, noopLog, deps()),
+			/not found/,
+		);
+
+		assert.equal(
+			called("message.delete").length,
+			0,
+			"the message is in Trash; deleting its row loses the only handle on it",
+		);
+		assert.equal(called("threadMessage.delete").length, 0);
+		assert.equal(
+			called("connection.search").length,
+			0,
+			"a move-to-trash never probes: absence from the source is its success signature",
+		);
+		assert.equal(
+			(called("message.update")[0]?.args[1] as { syncStatus?: string })
+				?.syncStatus,
+			"failed",
+		);
+	});
+
+	it("keeps the rows on a NONEXISTENT move-to-trash whose source still holds the uid", async () => {
+		h.connection.moveMessages = async () => {
+			throw new Error("NONEXISTENT: mailbox does not exist");
+		};
+
+		await assert.rejects(
+			handleMessageDelete(moveEvent, noopLog, deps()),
+			/NONEXISTENT/,
+		);
+
+		assert.equal(called("message.delete").length, 0);
+		assert.equal(called("threadMessage.delete").length, 0);
+		assert.equal(
+			(called("message.update")[0]?.args[1] as { syncStatus?: string })
+				?.syncStatus,
+			"failed",
+		);
+	});
+
+	it("keeps the rows when a permanent delete's source still holds the uid", async () => {
+		h.connection.deleteMessages = async () => {
+			throw new Error("NONEXISTENT uid");
+		};
+		// imapflow drops rows on back-to-back FETCHes (#408); the SEARCH is what
+		// the verdict rests on, and it still lists the uid.
+		h.connection.fetchMessages = async () => [];
+
+		await assert.rejects(
+			handleMessageDelete(permanentEvent, noopLog, deps()),
+			/NONEXISTENT/,
+		);
+
+		assert.equal(
+			called("connection.search").length,
+			1,
+			"the error text only selects a candidate; the source box decides",
+		);
+		assert.equal(called("message.delete").length, 0);
+		assert.equal(called("threadMessage.delete").length, 0);
+	});
+
+	it("keeps the rows and rethrows the original error when the probe cannot answer", async () => {
+		// The SELECT is what failed, so there is no open box left for the probe
+		// to ask. The IMAP error must still be the one that rejects, and the row
+		// must not be stranded mid-delete for the record to carry to the DLQ.
+		h.connection.openBox = async () => {
+			throw new Error("NONEXISTENT mailbox does not exist");
+		};
+		h.connection.fetchMessages = async () => {
+			throw new Error("No mailbox selected");
+		};
+
+		await assert.rejects(
+			handleMessageDelete(permanentEvent, noopLog, deps()),
+			/NONEXISTENT mailbox does not exist/,
+		);
+
+		assert.equal(called("message.delete").length, 0);
+		assert.equal(called("threadMessage.delete").length, 0);
+		assert.equal(
+			(called("message.update")[0]?.args[1] as { syncStatus?: string })
+				?.syncStatus,
+			"failed",
+		);
+	});
+
 	it("creates the trash mailbox and rethrows on TRYCREATE", async () => {
 		h.connection.moveMessages = async () => {
 			throw new Error("TRYCREATE: no such mailbox");

package/src/handlers/message-delete.ts

@@ -8,6 +8,7 @@ import type { Logger } from "@remit/logger-lambda";
 import {
 	guardConnectionCursor,
 	isCursorRebuildNeeded,
+	isMessageGoneFromOpenMailbox,
 	MailboxCursorPausedError,
 } from "@remit/mailbox-service";
 import { isAccountDeleted } from "../account-check.js";
@@ -359,14 +360,32 @@ export const handleMessageDelete = async (
 					const errorMessage =
 						error instanceof Error ? error.message : String(error);
 
-					// Message not found on IMAP - already deleted (idempotent)
-					if (
-						errorMessage.includes("not found") ||
-						errorMessage.includes("NONEXISTENT")
-					) {
+					// Reconcile a permanent delete the server already applied (#212).
+					// The error text only nominates a candidate — the source box
+					// decides, since a landed move-to-trash reports that same text from
+					// a LOCAL lookup (#845) — and a probe that cannot answer counts as
+					// not-confirmed, leaving the original error to the rethrow below.
+					const isGoneFromSource =
+						operation === "permanent_delete" &&
+						(errorMessage.includes("not found") ||
+							errorMessage.includes("NONEXISTENT")) &&
+						(await scope
+							.getConnection()
+							.then((connection) =>
+								isMessageGoneFromOpenMailbox(connection, uid),
+							)
+							.catch((probeError: unknown) => {
+								log.warn(
+									{ messageId, uid, mailboxPath, probeError },
+									"Could not confirm whether the message is gone; keeping local rows",
+								);
+								return false;
+							}));
+
+					if (isGoneFromSource) {
 						log.info(
 							{ messageId, uid },
-							"Message not found on IMAP, cleaning up local",
+							"Message confirmed gone from IMAP, cleaning up local",
 						);
 						// Clean up local entities. Multi-mailbox copies are handled by the
 						// helper so we don't leave orphan rows (see issue #212).

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":