@remit/imap-worker 0.0.66 → 0.0.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/imap-worker",
-  "version": "0.0.66",
+  "version": "0.0.68",
   "type": "module",
   "main": "dist/index.js",
   "exports": {
@@ -25,6 +25,7 @@
     "dev": "node --import tsx src/e2e-processor-shim.ts"
   },
   "devDependencies": {
+    "@remit/drizzle-service": "*",
     "@remit/queue-sidecar": "*",
     "@remit/storage-service": "*",
     "aws-sdk-client-mock": "*",

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

@@ -8,7 +8,7 @@ import {
 	reconcileStaleMessage,
 	type StaleMessageReconcileDeps,
 } from "@remit/mailbox-service";
-import { buildThreadMessageMoveRevert } from "./thread-message-rows.js";
+import { restoreSourcePlacement } from "./restore-source-placement.js";
 
 export interface MessageDeleteTerminalLogger {
 	info(obj: Record<string, unknown>, msg: string): void;
@@ -125,25 +125,12 @@ export const resolveExhaustedMessageDeleteFailure = async (
 		"Delete could not be pushed to IMAP after retry exhaustion; the message is still at its source — row moved back to the source folder",
 	);
 
-	await deps.messageService.updateUid(messageId, uid, sourceMailboxId);
-
-	const threadMessages = await deps.threadMessageService.findAllByMessageId(
+	await restoreSourcePlacement(deps, {
 		accountConfigId,
 		messageId,
-	);
-	for (const threadMessage of threadMessages) {
-		const args = buildThreadMessageMoveRevert(
-			threadMessage,
-			uid,
-			sourceMailboxId,
-		);
-		await deps.threadMessageService.update(
-			threadMessage.accountConfigId,
-			threadMessage.threadMessageId,
-			args.set,
-			{ composites: args.composites },
-		);
-	}
+		sourceMailboxId,
+		uid,
+	});
 
 	return { outcome: "broken" };
 };

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

@@ -303,6 +303,10 @@ interface Harness {
 	allThreadMessages: Record<string, unknown>[];
 	getConnectionCount: number;
 	disconnectCount: number;
+	// Rejections handed to `getConnection`, one per call, oldest first. A
+	// dropped connection is how the guarded openBox gets skipped on a delivery
+	// that still goes on to settle the row.
+	connectionErrors: Error[];
 }
 
 let h: Harness;
@@ -367,6 +371,7 @@ const fresh = (): Harness => ({
 	],
 	getConnectionCount: 0,
 	disconnectCount: 0,
+	connectionErrors: [],
 });
 
 const deps = (): MessageDeleteDeps =>
@@ -417,6 +422,8 @@ const deps = (): MessageDeleteDeps =>
 		createConnectionScope: () => ({
 			getConnection: async () => {
 				h.getConnectionCount += 1;
+				const failure = h.connectionErrors.shift();
+				if (failure) throw failure;
 				return h.connection;
 			},
 			disconnect: async () => {
@@ -1178,6 +1185,41 @@ describe("handleMessageDelete", () => {
 		assert.equal(called("message.updateUid").length, 0);
 	});
 
+	// The terminal resolver opens the source itself, and since #1005 its answer
+	// WRITES a placement. A folder deleted and recreated renumbers every uid, so
+	// an unguarded probe finds whatever now sits at this one, reads it as "still
+	// at source", and binds the row to a stranger the next permanent delete
+	// expunges. The dropped connection is what makes it reachable: it skips the
+	// guarded openBox on the very delivery that goes on to settle.
+	it("never settles an exhausted delete off a probe that skipped the cursor guard", async () => {
+		h.connectionErrors = [new Error("ECONNRESET")];
+		h.connection.openBox = async () => ({ uidvalidity: 999 });
+
+		await handleMessageDelete(
+			moveEvent,
+			noopLog,
+			MESSAGE_DELETE_MAX_ATTEMPTS,
+			deps(),
+		);
+
+		assert.equal(
+			called("message.updateUid").length,
+			0,
+			"a renumbered folder answers for a different message; nothing settles off it",
+		);
+		assert.equal(
+			called("message.delete").length,
+			0,
+			"and nothing is reconciled away off it either",
+		);
+		assert.equal(
+			(called("mailbox.update")[0]?.args[2] as { cursorState?: string })
+				?.cursorState,
+			"cursor_invalid",
+			"the probe trips the mailbox into a rebuild instead",
+		);
+	});
+
 	it("skips without opening a connection when the cursor is rebuilding", async () => {
 		h.mailbox = {
 			mailboxId: "src-mbx",

package/src/handlers/message-delete.ts

@@ -259,7 +259,7 @@ export const handleMessageDelete = async (
 		accountConfigId: string,
 		getConnection: () => Promise<IImapConnection>,
 	): Promise<void> => {
-		const { outcome } = await resolveExhaustedMessageDeleteFailure(
+		const settled = await resolveExhaustedMessageDeleteFailure(
 			{ messageService, threadMessageService, log },
 			{
 				accountId,
@@ -270,9 +270,25 @@ export const handleMessageDelete = async (
 				sourceMailboxPath: mailboxPath,
 				getConnection,
 			},
-		);
+		).catch((settleError: unknown) => {
+			// The guarded probe found a mailbox whose UIDVALIDITY has moved. Every
+			// stored uid for this folder now names something else, so there is
+			// nothing here that may be settled off them, and the pause is the
+			// routine skip `guardMailboxCursor` documents, not a fault to re-throw
+			// out of the caller's catch.
+			if (settleError instanceof MailboxCursorPausedError) {
+				log.info(
+					{ accountId, messageId, mailboxId, cursorState: settleError.state },
+					"Mailbox cursor not normal; leaving the exhausted delete for the cursor rebuild",
+				);
+				return null;
+			}
+			throw settleError;
+		});
 
-		if (outcome === "broken") {
+		if (!settled) return;
+
+		if (settled.outcome === "broken") {
 			recordImapFailure("MESSAGE_DELETE_EXHAUSTED", "other");
 		}
 
@@ -380,6 +396,21 @@ export const handleMessageDelete = async (
 
 			const scope = createConnectionScopeWithCredentials(account, credentials);
 
+			// The terminal resolver opens the source itself, and its answer now
+			// WRITES a placement, so it has to reach IMAP through the same
+			// UIDVALIDITY choke point every other outbound operation does. An
+			// unguarded probe on a folder that was deleted and recreated finds
+			// whatever the server has renumbered onto this uid, reads it as "still
+			// at source", and binds the row to a stranger the next permanent delete
+			// would expunge.
+			const getGuardedConnection = async (): Promise<IImapConnection> =>
+				guardConnectionCursor(
+					await scope.getConnection(),
+					{ mailboxService },
+					accountId,
+					mailbox,
+				);
+
 			await scope
 				.getConnection()
 				.then(async (rawConnection) => {
@@ -490,7 +521,7 @@ export const handleMessageDelete = async (
 						await settleUnconfirmedTrashMove(
 							confirmation,
 							account.accountConfigId,
-							scope.getConnection,
+							getGuardedConnection,
 						);
 					} else {
 						// Permanent delete — reached only by `operation === "permanent_delete"`.
@@ -594,7 +625,7 @@ export const handleMessageDelete = async (
 					// failure this budget exists for.
 					await settleExhaustedDelete(
 						account.accountConfigId,
-						scope.getConnection,
+						getGuardedConnection,
 					);
 					log.error(
 						{ accountId, messageId, uid, mailboxPath, error: errorMessage },

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

@@ -4,7 +4,10 @@ import type {
 	IMessageRepository,
 	IThreadMessageRepository,
 } from "@remit/data-ports";
-import type { IImapConnection } from "@remit/mailbox-service";
+import {
+	type IImapConnection,
+	placementBindingOf,
+} from "@remit/mailbox-service";
 import {
 	type MessageMoveTerminalLogger,
 	type ResolveExhaustedMessageMoveDeps,
@@ -60,21 +63,33 @@ interface MessageRow {
 	originalUid: number;
 }
 
+interface ThreadRow {
+	accountConfigId: string;
+	threadMessageId: string;
+	mailboxId: string;
+	uid: number;
+	isDeleted: boolean;
+}
+
 /**
  * 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.
+ * and the assertions read the rows back — a resolver that settled the row on
+ * anything but the server's own answer shows up here as a changed row, not as
+ * an uncalled mock. `updateUid` writes what the repository writes: the settled
+ * pair AND the `active`/`synced` that clears `moving`.
  */
 const buildRepositories = (row: MessageRow) => {
 	const messages = new Map<string, MessageRow>([[row.messageId, row]]);
-	const threadMessages = new Map<
-		string,
-		{ accountConfigId: string; threadMessageId: string }
-	>([
+	const threadMessages = new Map<string, ThreadRow>([
 		[
 			`tm-${row.messageId}`,
-			{ accountConfigId: "cfg-1", threadMessageId: `tm-${row.messageId}` },
+			{
+				accountConfigId: "cfg-1",
+				threadMessageId: `tm-${row.messageId}`,
+				mailboxId: row.mailboxId,
+				uid: row.uid,
+				isDeleted: false,
+			},
 		],
 	]);
 
@@ -89,7 +104,22 @@ const buildRepositories = (row: MessageRow) => {
 				const current = messages.get(messageId);
 				if (current) messages.set(messageId, { ...current, ...input });
 			},
-		} as unknown as Pick<IMessageRepository, "delete">,
+			updateUid: async (
+				messageId: string,
+				newUid: number,
+				newMailboxId: string,
+			) => {
+				const current = messages.get(messageId);
+				if (current)
+					messages.set(messageId, {
+						...current,
+						uid: newUid,
+						mailboxId: newMailboxId,
+						status: "active",
+						syncStatus: "synced",
+					});
+			},
+		} as unknown as Pick<IMessageRepository, "delete" | "updateUid">,
 		threadMessageService: {
 			findAllByMessageId: async () => [...threadMessages.values()],
 			deleteMany: async (
@@ -97,9 +127,18 @@ const buildRepositories = (row: MessageRow) => {
 			) => {
 				for (const key of keys) threadMessages.delete(key.threadMessageId);
 			},
+			update: async (
+				_accountConfigId: string,
+				threadMessageId: string,
+				set: Partial<ThreadRow>,
+			) => {
+				const current = threadMessages.get(threadMessageId);
+				if (current)
+					threadMessages.set(threadMessageId, { ...current, ...set });
+			},
 		} as unknown as Pick<
 			IThreadMessageRepository,
-			"findAllByMessageId" | "deleteMany"
+			"findAllByMessageId" | "deleteMany" | "update"
 		>,
 	};
 };
@@ -118,6 +157,7 @@ const input = {
 	accountId: "acc-1",
 	accountConfigId: "cfg-1",
 	messageId: "msg-1",
+	sourceMailboxId: "mbx-inbox",
 	uid: 101,
 	sourceMailboxPath: "INBOX",
 };
@@ -150,7 +190,7 @@ describe("resolveExhaustedMessageMoveFailure — the two terminal outcomes (issu
 		);
 	});
 
-	it("BROKEN: the message is still at the source — the row is left EXACTLY as it stands, alarm logged, never re-thrown", async () => {
+	it("BROKEN: the message is still at the source — the row is put back on the pair the server confirmed, alarm logged, never re-thrown", async () => {
 		const repos = buildRepositories(pendingMoveRow());
 		const { log, errors } = buildLogger();
 		const deps: ResolveExhaustedMessageMoveDeps = {
@@ -165,15 +205,46 @@ describe("resolveExhaustedMessageMoveFailure — the two terminal outcomes (issu
 		});
 
 		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.messages.get("msg-1")?.mailboxId, "mbx-inbox");
+		assert.equal(repos.messages.get("msg-1")?.uid, 101);
+		assert.equal(
+			repos.threadMessages.get("tm-msg-1")?.mailboxId,
+			"mbx-inbox",
+			"the listing row follows the message back to the folder it never left",
 		);
-		assert.equal(repos.threadMessages.size, 1);
 		assert.ok(errors.some((e) => e.obj.alert === "message_move_failed"));
 	});
 
+	// Issue #1005: only `updateUid` clears `moving`, so a give-up that returned
+	// without calling it left the row naming the destination with the source's
+	// uid — a pair `bindsForeignUid` refuses, which made the message
+	// undeletable and unmovable for good.
+	it("BROKEN: the settled row is no longer refused by the placement guard (#1005)", async () => {
+		const repos = buildRepositories(pendingMoveRow());
+		const { log } = buildLogger();
+		const deps: ResolveExhaustedMessageMoveDeps = {
+			messageService: repos.messageService,
+			threadMessageService: repos.threadMessageService,
+			log,
+		};
+
+		assert.equal(
+			placementBindingOf(pendingMoveRow() as never),
+			"abandoned",
+			"the row starts in the state the delete route refuses as unverified",
+		);
+
+		await resolveExhaustedMessageMoveFailure(deps, {
+			...input,
+			getConnection: async () => buildConnection(new Set([101])),
+		});
+
+		const settled = repos.messages.get("msg-1");
+		assert.ok(settled);
+		assert.equal(placementBindingOf(settled as never), "consistent");
+		assert.equal(settled.status, "active");
+	});
+
 	it("BROKEN: an empty FETCH the SEARCH contradicts never counts as gone", async () => {
 		const repos = buildRepositories(pendingMoveRow());
 		const { log } = buildLogger();
@@ -190,7 +261,93 @@ describe("resolveExhaustedMessageMoveFailure — the two terminal outcomes (issu
 		});
 
 		assert.equal(result.outcome, "broken");
-		assert.deepEqual(repos.messages.get("msg-1"), pendingMoveRow());
+		assert.equal(
+			repos.messages.get("msg-1")?.mailboxId,
+			"mbx-inbox",
+			"a message the SEARCH still lists is at the source, and the row says so",
+		);
+	});
+
+	// The resolver's contract is that it is never re-thrown, so the caller can
+	// ack the record and emit its resync. A row another path deleted while the
+	// probe was in flight has nothing left to restore, and the same NotFound
+	// wraps an ElectroDB composites miss on the listing row.
+	it("BROKEN: a row deleted underneath the probe settles instead of throwing", async () => {
+		const repos = buildRepositories(pendingMoveRow());
+		const notFound = Object.assign(new Error("Message not found: msg-1"), {
+			name: "NotFoundError",
+		});
+		const { log } = buildLogger();
+		const deps: ResolveExhaustedMessageMoveDeps = {
+			messageService: {
+				...repos.messageService,
+				updateUid: async () => {
+					throw notFound;
+				},
+			} as unknown as ResolveExhaustedMessageMoveDeps["messageService"],
+			threadMessageService: repos.threadMessageService,
+			log,
+		};
+
+		const result = await resolveExhaustedMessageMoveFailure(deps, {
+			...input,
+			getConnection: async () => buildConnection(new Set([101])),
+		});
+
+		assert.equal(result.outcome, "broken");
+	});
+
+	it("BROKEN: a listing row whose composites moved on does not fail the settle", async () => {
+		const repos = buildRepositories(pendingMoveRow());
+		const { log } = buildLogger();
+		const deps: ResolveExhaustedMessageMoveDeps = {
+			messageService: repos.messageService,
+			threadMessageService: {
+				...repos.threadMessageService,
+				update: async () => {
+					throw Object.assign(new Error("Thread message not found"), {
+						name: "NotFoundError",
+					});
+				},
+			} as unknown as ResolveExhaustedMessageMoveDeps["threadMessageService"],
+			log,
+		};
+
+		const result = await resolveExhaustedMessageMoveFailure(deps, {
+			...input,
+			getConnection: async () => buildConnection(new Set([101])),
+		});
+
+		assert.equal(result.outcome, "broken");
+		assert.equal(
+			repos.messages.get("msg-1")?.mailboxId,
+			"mbx-inbox",
+			"the Message row still lands on the pair the server confirmed",
+		);
+	});
+
+	it("a repository fault that is not a missing row still propagates", async () => {
+		const repos = buildRepositories(pendingMoveRow());
+		const { log } = buildLogger();
+		const deps: ResolveExhaustedMessageMoveDeps = {
+			messageService: {
+				...repos.messageService,
+				updateUid: async () => {
+					throw new Error("ProvisionedThroughputExceeded");
+				},
+			} as unknown as ResolveExhaustedMessageMoveDeps["messageService"],
+			threadMessageService: repos.threadMessageService,
+			log,
+		};
+
+		await assert.rejects(
+			() =>
+				resolveExhaustedMessageMoveFailure(deps, {
+					...input,
+					getConnection: async () => buildConnection(new Set([101])),
+				}),
+			/ProvisionedThroughputExceeded/,
+		);
 	});
 
 	it("an unreachable server reaches no verdict at all — the probe propagates and the row is untouched", async () => {

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

@@ -1,9 +1,14 @@
+import type {
+	IMessageRepository,
+	IThreadMessageRepository,
+} from "@remit/data-ports";
 import {
 	type IImapConnection,
 	isMessageGoneFromOpenMailbox,
 	reconcileStaleMessage,
 	type StaleMessageReconcileDeps,
 } from "@remit/mailbox-service";
+import { restoreSourcePlacement } from "./restore-source-placement.js";
 
 export interface MessageMoveTerminalLogger {
 	info(obj: Record<string, unknown>, msg: string): void;
@@ -12,6 +17,11 @@ export interface MessageMoveTerminalLogger {
 
 export interface ResolveExhaustedMessageMoveDeps
 	extends StaleMessageReconcileDeps {
+	messageService: Pick<IMessageRepository, "delete" | "updateUid">;
+	threadMessageService: Pick<
+		IThreadMessageRepository,
+		"findAllByMessageId" | "deleteMany" | "update"
+	>;
 	log: MessageMoveTerminalLogger;
 }
 
@@ -19,6 +29,7 @@ export interface ResolveExhaustedMessageMoveInput {
 	accountId: string;
 	accountConfigId: string;
 	messageId: string;
+	sourceMailboxId: string;
 	uid: number;
 	sourceMailboxPath: string;
 	getConnection: () => Promise<IImapConnection>;
@@ -51,12 +62,21 @@ export interface ResolveExhaustedMessageMoveResult {
  *    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).
+ *    transient blip. The row is put back where the server has just said the
+ *    message is, as `resolveExhaustedMessageDeleteFailure` does (#1098). 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).
+ *
+ *    Leaving the row `moving` is what this replaces. BROKEN is terminal, so
+ *    nothing was ever going to come back and settle it, and only `updateUid`
+ *    clears `moving` — the row kept a `mailboxId` naming the destination and a
+ *    `uid` belonging to the source, which `bindsForeignUid` refuses to act on,
+ *    leaving the message undeletable and unmovable for good (issue #1005).
+ *    Restoring the pair is not the revert-on-ambiguity PR #652 was pulled for:
+ *    the presence probe above has just answered, so this writes a placement the
+ *    server confirmed, and a MOVE that lands after all is re-projected by the
+ *    resync the caller runs.
  *
  * 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.
@@ -66,9 +86,10 @@ export interface ResolveExhaustedMessageMoveResult {
  * 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.
+ * lands in BROKEN, and BROKEN is terminal — the row is bound to a source the
+ * message has already left 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,
@@ -78,6 +99,7 @@ export const resolveExhaustedMessageMoveFailure = async (
 		accountId,
 		accountConfigId,
 		messageId,
+		sourceMailboxId,
 		uid,
 		sourceMailboxPath,
 		getConnection,
@@ -114,9 +136,18 @@ export const resolveExhaustedMessageMoveFailure = async (
 			accountConfigId,
 			messageId,
 			uid,
+			sourceMailboxId,
 			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",
+		"Message move could not be pushed to IMAP after retry exhaustion; the message is still at its source — row moved back to the source folder",
 	);
+
+	await restoreSourcePlacement(deps, {
+		accountConfigId,
+		messageId,
+		sourceMailboxId,
+		uid,
+	});
+
 	return { outcome: "broken" };
 };

package/src/handlers/message-move.ts

@@ -257,6 +257,21 @@ export const handleMessageMove = async (
 
 			const scope = createConnectionScopeWithCredentials(account, credentials);
 
+			// The terminal resolver opens the source itself, and its answer now
+			// WRITES a placement, so it has to reach IMAP through the same
+			// UIDVALIDITY choke point every other outbound operation does. An
+			// unguarded probe on a folder that was deleted and recreated finds
+			// whatever the server has renumbered onto this uid, reads it as "still
+			// at source", and binds the row to a stranger the next permanent delete
+			// would expunge.
+			const getGuardedConnection = async (): Promise<IImapConnection> =>
+				guardConnectionCursor(
+					await scope.getConnection(),
+					{ mailboxService },
+					accountId,
+					mailbox,
+				);
+
 			await scope
 				.getConnection()
 				.then((rawConnection) => {
@@ -395,36 +410,62 @@ export const handleMessageMove = async (
 					// 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(
+					const settled = await resolveExhaustedMessageMoveFailure(
 						{ messageService, threadMessageService, log },
 						{
 							accountId,
 							accountConfigId: account.accountConfigId,
 							messageId,
+							sourceMailboxId,
 							uid,
 							sourceMailboxPath,
-							getConnection: scope.getConnection,
+							getConnection: getGuardedConnection,
 						},
-					);
+					).catch((settleError: unknown) => {
+						// The guarded probe found a mailbox whose UIDVALIDITY has moved.
+						// Every stored uid for this folder now names something else, so
+						// there is nothing here that may be settled off them, and the
+						// pause is the routine skip `guardMailboxCursor` documents, not
+						// a fault to re-throw out of this catch.
+						if (settleError instanceof MailboxCursorPausedError) {
+							log.info(
+								{
+									accountId,
+									messageId,
+									mailboxId: sourceMailboxId,
+									cursorState: settleError.state,
+								},
+								"Mailbox cursor not normal; leaving the exhausted move for the cursor rebuild",
+							);
+							return null;
+						}
+						throw settleError;
+					});
 
-					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;
+					if (!settled) return;
+
+					if (settled.outcome === "broken") {
+						// 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 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",
-					);
+					// Both verdicts end in a row the server has contradicted, so this
+					// move reconciles rather than waits (R2). RECONCILED, the local rows
+					// are gone and whichever folder actually holds the message
+					// re-projects it with the server's own UID. BROKEN, the row has just
+					// been put back at the source the server confirmed, and the resync
+					// is what carries any drift either folder has picked up since.
+					await emitMoveResync(emitEvent, {
+						accountId,
+						sourceMailboxId,
+						destinationMailboxId,
+					});
 					// Terminal — never re-thrown, so the caller acks either way.
 				})
 				.finally(() => scope.disconnect());

package/src/handlers/restore-source-placement.ts

@@ -0,0 +1,89 @@
+import type {
+	IMessageRepository,
+	IThreadMessageRepository,
+} from "@remit/data-ports";
+import { isNotFoundError } from "../is-not-found.js";
+import { buildThreadMessageMoveRevert } from "./thread-message-rows.js";
+
+export interface RestoreSourcePlacementDeps {
+	messageService: Pick<IMessageRepository, "updateUid">;
+	threadMessageService: Pick<
+		IThreadMessageRepository,
+		"findAllByMessageId" | "update"
+	>;
+}
+
+export interface RestoreSourcePlacementInput {
+	accountConfigId: string;
+	messageId: string;
+	sourceMailboxId: string;
+	uid: number;
+}
+
+/**
+ * Put a row back on the source pair a presence probe has just confirmed, and
+ * hand its listing rows back with it.
+ *
+ * Only `updateUid` clears `status: moving`, so a give-up that writes
+ * `syncStatus: failed` and returns leaves the row naming the destination with
+ * the source's uid — the pair `bindsForeignUid` calls a lie and
+ * `MessagePlacementUnsettledError` refuses to act on. Nothing routine repairs
+ * it (sync does not touch `status`, and the cursor rebuild's `updateUid` runs
+ * only on a UIDVALIDITY change), so the message is undeletable and unmovable
+ * for good (issue #1005).
+ *
+ * The caller must have evidence, not an inference: this writes a placement, and
+ * a placement written on a guess binds live mail to a uid that names somebody
+ * else's message. Every caller reaches here from
+ * {@link isMessageGoneFromOpenMailbox} answering that the message is STILL at
+ * `sourceMailboxId`/`uid`, which makes this the server's own answer rather than
+ * a revert on ambiguity (what PR #652 was pulled for).
+ *
+ * A row another path deleted while the probe was in flight has nothing left to
+ * restore, and a thread row whose composites have moved on is being rewritten
+ * by that other path anyway. Both surface as `NotFoundError` — ElectroDB wraps
+ * the conditional-check miss as one — and both are settled states here, not
+ * faults. Throwing on them would escape the caller's `.catch()` and cost the
+ * record its ack and its resync, which is the contract the terminal resolvers
+ * state: never re-thrown.
+ */
+export const restoreSourcePlacement = async (
+	deps: RestoreSourcePlacementDeps,
+	input: RestoreSourcePlacementInput,
+): Promise<void> => {
+	const { accountConfigId, messageId, sourceMailboxId, uid } = input;
+
+	const skipNotFound = (error: unknown): void => {
+		if (isNotFoundError(error)) return;
+		throw error;
+	};
+
+	const messageRestored = await deps.messageService
+		.updateUid(messageId, uid, sourceMailboxId)
+		.then(() => true)
+		.catch((error: unknown) => {
+			skipNotFound(error);
+			return false;
+		});
+	if (!messageRestored) return;
+
+	const threadMessages = await deps.threadMessageService.findAllByMessageId(
+		accountConfigId,
+		messageId,
+	);
+	for (const threadMessage of threadMessages) {
+		const args = buildThreadMessageMoveRevert(
+			threadMessage,
+			uid,
+			sourceMailboxId,
+		);
+		await deps.threadMessageService
+			.update(
+				threadMessage.accountConfigId,
+				threadMessage.threadMessageId,
+				args.set,
+				{ composites: args.composites },
+			)
+			.catch(skipNotFound);
+	}
+};

package/src/with-oauth-lifecycle-deps.sqlite.test.ts

@@ -0,0 +1,138 @@
+/**
+ * What the account row holds after the lifecycle has written to it.
+ *
+ * The deps builder is the half that talks to the store, so it is tested against
+ * the real repository over the shipped SQLite schema rather than a stand-in
+ * that would only agree with itself: whether a stored reason survives, and
+ * whether one that no longer applies is gone, is decided by the repository's
+ * update semantics, where an absent field means "leave it alone".
+ */
+
+import assert from "node:assert/strict";
+import { after, before, describe, it } from "node:test";
+import type { AccountItem } from "@remit/data-ports";
+import { AccountAuthType, ConnectionState } from "@remit/domain-enums";
+import { AccountRepo } from "@remit/drizzle-service";
+import { createShippedSqliteDb } from "@remit/drizzle-service/test-sqlite";
+import { RefreshTokenError } from "@remit/mail-oauth-service";
+import { MailConnectionError } from "@remit/mailbox-service/types";
+import type { SecretsService } from "@remit/secrets-service";
+import {
+	type OAuthLifecycleDeps,
+	withOAuthLifecycle,
+} from "./with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "./with-oauth-lifecycle-deps.js";
+
+const silentLogger = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	debug: () => {},
+	trace: () => {},
+	fatal: () => {},
+	child: () => silentLogger,
+} as never;
+
+const secrets = {
+	decrypt: async () => "decrypted",
+	encrypt: async () => ({}) as never,
+} as unknown as SecretsService;
+
+/**
+ * The real deps, with only credential resolution stubbed — minting a token is
+ * a call to Microsoft and not what these tests are about. `updateConnectionState`
+ * is the one under test and stays exactly as the handlers build it.
+ */
+const deps = (): OAuthLifecycleDeps => ({
+	...buildLifecycleDeps(secrets, repo),
+	resolveCredentials: async () => ({
+		status: "resolved",
+		credentials: { kind: "accessToken", accessToken: "access-token" },
+	}),
+});
+
+const STALE_SYNC_ERROR = "Mailbox does not exist: [NONEXISTENT]";
+const REFUSAL =
+	"IMAP authentication failed: LOGIN failed. User is authenticated but not connected.";
+
+let repo: AccountRepo;
+let close: () => void;
+
+const account = async (): Promise<AccountItem> =>
+	repo.create({
+		accountConfigId: "cfg-1",
+		username: "matthijs@example.com",
+		email: "matthijs@example.com",
+		authType: AccountAuthType.OauthMicrosoft,
+		oauthRefreshTokenHash: "encrypted-refresh-token",
+		imapHost: "outlook.office365.com",
+		imapPort: 993,
+		imapTls: true,
+		imapStartTls: false,
+		isActive: true,
+		connectionState: ConnectionState.Authenticated,
+	});
+
+before(() => {
+	const db = createShippedSqliteDb();
+	close = db.close;
+	repo = new AccountRepo(db.db);
+});
+
+after(() => {
+	close();
+});
+
+describe("the reason an account card reads back", () => {
+	it("keeps the refusal the mail server gave", async () => {
+		const created = await account();
+
+		await withOAuthLifecycle(deps(), created, silentLogger, async () => {
+			throw new MailConnectionError("auth", REFUSAL);
+		});
+
+		const stored = await repo.get(created.accountId);
+		assert.equal(stored.connectionState, ConnectionState.ReauthRequired);
+		assert.equal(stored.lastError, REFUSAL);
+	});
+
+	it("drops a reason the account has moved on from", async () => {
+		const created = await account();
+		// What a failed sync leaves behind (sync-mailboxes.ts): a folder that went
+		// away, nothing to do with signing in.
+		await repo.update(created.accountId, { lastError: STALE_SYNC_ERROR });
+
+		// Hours later the refresh token is revoked. Re-authenticating is now the
+		// whole story, and the mailbox that went missing is not it.
+		await withOAuthLifecycle(
+			deps(),
+			await repo.get(created.accountId),
+			silentLogger,
+			async () => {
+				throw new RefreshTokenError({
+					kind: "reauth-required",
+					code: "invalid_grant",
+				});
+			},
+		);
+
+		const stored = await repo.get(created.accountId);
+		assert.equal(stored.connectionState, ConnectionState.ReauthRequired);
+		assert.equal(
+			stored.lastError,
+			undefined,
+			"a stale sync error beside a Reconnect button reads as the reason for it",
+		);
+	});
+
+	it("stores a chatty refusal at a length a card can hold", async () => {
+		const created = await account();
+
+		await withOAuthLifecycle(deps(), created, silentLogger, async () => {
+			throw new MailConnectionError("auth", "x".repeat(4000));
+		});
+
+		const stored = await repo.get(created.accountId);
+		assert.equal(stored.lastError?.length, 500);
+	});
+});

package/src/with-oauth-lifecycle-deps.ts

@@ -53,10 +53,19 @@ export const buildLifecycleDeps = (
 			oauthTokenUpdatedAt: updatedAt,
 		});
 	},
+	// A state flip with no reason of its own removes the stored one. Left in
+	// place it would describe a failure the account has moved on from — the
+	// mailbox a sync could not find, still on the card beside a Reconnect
+	// button, after the token was revoked hours later.
 	updateConnectionState: async (
 		accountId: string,
 		state: ConnectionStateValue,
+		lastError?: string,
 	) => {
-		await accountService.update(accountId, { connectionState: state });
+		await accountService.update(
+			accountId,
+			{ connectionState: state, lastError },
+			lastError === undefined ? ["lastError"] : undefined,
+		);
 	},
 });

package/src/with-oauth-lifecycle.test.ts

@@ -1,8 +1,9 @@
 import assert from "node:assert/strict";
-import { describe, it } from "node:test";
+import { describe, it, mock } from "node:test";
 import type { AccountItem } from "@remit/data-ports";
 import { AccountAuthType, ConnectionState } from "@remit/domain-enums";
 import { RefreshTokenError } from "@remit/mail-oauth-service";
+import { ImapFlowConnection } from "@remit/mailbox-service/imapflow-connection";
 import {
 	MailConnectionError,
 	type MailCredentials,
@@ -41,11 +42,19 @@ const buildAccount = (overrides: Partial<AccountItem> = {}): AccountItem =>
 	}) as unknown as AccountItem;
 
 interface Recorded {
-	stateUpdates: Array<{ accountId: string; state: ConnectionStateValue }>;
+	stateUpdates: Array<{
+		accountId: string;
+		state: ConnectionStateValue;
+		lastError?: string;
+	}>;
 	resolveCalls: number;
 	workCalls: number;
 }
 
+/** What Microsoft says to a mailbox whose tenant has IMAP switched off. */
+const REFUSAL =
+	"LOGIN failed. User is authenticated but not connected. SmtpClientAuthentication is disabled for the Tenant.";
+
 const passwordCreds: MailCredentials = {
 	kind: "password",
 	password: "secret",
@@ -68,8 +77,8 @@ const buildDeps = (
 		},
 		tokenService: { getAccessToken: async () => ({}) as never },
 		persistRotatedToken: async () => {},
-		updateConnectionState: async (accountId, state) => {
-			recorded.stateUpdates.push({ accountId, state });
+		updateConnectionState: async (accountId, state, lastError) => {
+			recorded.stateUpdates.push({ accountId, state, lastError });
 		},
 		resolveCredentials:
 			options.resolveCredentials ??
@@ -124,9 +133,12 @@ describe("withOAuthLifecycle", () => {
 			"work must not run after resolve fails",
 		);
 		assert.equal(recorded.stateUpdates.length, 1);
+		// A revoked token has nothing to add: re-authenticating is the whole of
+		// what the account needs, and the card says so on its own.
 		assert.deepEqual(recorded.stateUpdates[0], {
 			accountId: "acc-1",
 			state: ConnectionState.ReauthRequired,
+			lastError: undefined,
 		});
 	});
 
@@ -142,7 +154,48 @@ describe("withOAuthLifecycle", () => {
 		assert.deepEqual(recorded.stateUpdates[0], {
 			accountId: "acc-1",
 			state: ConnectionState.ReauthRequired,
+			lastError: "auth failed",
+		});
+	});
+
+	it("keeps what the server said when it refused, so the card can repeat it", async () => {
+		const { deps, recorded } = buildDeps();
+		const account = buildAccount({ authType: AccountAuthType.OauthMicrosoft });
+
+		// The error an Exchange mailbox with IMAP switched off hands back, built
+		// the way imapflow builds it and classified by the code that ships.
+		const connection = new ImapFlowConnection({
+			host: "outlook.office365.com",
+			port: 993,
+			user: "matthijs@example.com",
+			credentials: { kind: "accessToken", accessToken: "access-token" },
+			tls: true,
+		});
+		mock.method(
+			connection as unknown as { attemptConnect: () => Promise<void> },
+			"attemptConnect",
+			async () => {
+				throw Object.assign(new Error("Command failed"), {
+					authenticationFailed: true,
+					serverResponseCode: "AUTHENTICATIONFAILED",
+					responseText: REFUSAL,
+				});
+			},
+		);
+
+		await withOAuthLifecycle(deps, account, silentLogger, async () => {
+			await connection.connect();
 		});
+
+		assert.equal(recorded.stateUpdates.length, 1);
+		assert.equal(
+			recorded.stateUpdates[0].state,
+			ConnectionState.ReauthRequired,
+		);
+		assert.ok(
+			recorded.stateUpdates[0].lastError?.includes(REFUSAL),
+			`the refusal must survive to the account row, got: ${recorded.stateUpdates[0].lastError}`,
+		);
 	});
 
 	it("on MailConnectionError auth for password account: rethrows (batch item failure, no state flip)", async () => {
@@ -221,7 +274,11 @@ describe("withOAuthLifecycle", () => {
 
 		assert.equal(recorded.workCalls, 0, "no IMAP traffic without a credential");
 		assert.deepEqual(recorded.stateUpdates, [
-			{ accountId: "acc-1", state: ConnectionState.CredentialsMissing },
+			{
+				accountId: "acc-1",
+				state: ConnectionState.CredentialsMissing,
+				lastError: undefined,
+			},
 		]);
 	});
 
@@ -236,7 +293,11 @@ describe("withOAuthLifecycle", () => {
 
 		assert.equal(recorded.workCalls, 0, "no IMAP traffic without a credential");
 		assert.deepEqual(recorded.stateUpdates, [
-			{ accountId: "acc-1", state: ConnectionState.ReauthRequired },
+			{
+				accountId: "acc-1",
+				state: ConnectionState.ReauthRequired,
+				lastError: undefined,
+			},
 		]);
 	});
 

package/src/with-oauth-lifecycle.ts

@@ -16,6 +16,10 @@
  *  - On a terminal auth failure (RefreshTokenError reauth-required, or
  *    MailConnectionError auth), flip the account to reauth_required and return
  *    WITHOUT rethrowing — this ACKs the SQS message so it is not retried.
+ *    An IMAP refusal is stored with it, because not every refusal a mail server
+ *    hands back is one re-authenticating clears: "SmtpClientAuthentication is
+ *    disabled" needs a tenant setting changed, and an account card that only
+ *    ever says "Re-authentication required" sends the user around a loop.
  *  - On transient / config / network errors, rethrow so SQS retries with
  *    backoff (let-it-crash).
  *
@@ -42,12 +46,17 @@ export type { ConnectionStateValue };
 
 export interface OAuthLifecycleDeps extends AccountCredentialsDeps {
 	/**
-	 * Persist the account's connectionState. Called when a terminal auth
-	 * failure is detected so the account is fenced off until the user re-auths.
+	 * Persist the account's connectionState, and with it the sentence the
+	 * account card shows for the failure. `lastError` carries the server's own
+	 * words when the failure came with any; it is absent when nothing was said,
+	 * as for a credential that was never stored or a token simply revoked, and
+	 * the stored reason is then cleared rather than left to describe an older
+	 * failure the account has moved on from.
 	 */
 	updateConnectionState: (
 		accountId: string,
 		state: ConnectionStateValue,
+		lastError?: string,
 	) => Promise<void>;
 	/**
 	 * Resolve credentials for the account. Defaults to
@@ -131,12 +140,14 @@ export const withOAuthLifecycle = async (
 				{
 					accountId: account.accountId,
 					errorKind: err.kind,
+					error: err.message,
 				},
 				"IMAP auth rejected; marking account reauth_required",
 			);
 			await deps.updateConnectionState(
 				account.accountId,
 				ConnectionState.ReauthRequired,
+				err.message,
 			);
 			return; // ACK — do not retry
 		}