@remit/imap-worker 0.0.20 → 0.0.21

package/package.json

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

package/src/handlers/empty-trash.test.ts

@@ -36,6 +36,7 @@ interface Harness {
 		deletedAt?: number;
 	} | null;
 	mailbox: { mailboxId: string; uidValidity: number; cursorState?: string };
+	mailboxError?: Error;
 	connection: Connection;
 	localMessages: { messageId: string }[];
 	threadMessage: { accountConfigId: string; threadMessageId: string } | null;
@@ -88,7 +89,10 @@ const deps = (): EmptyTrashDeps =>
 				delete: record("threadMessage.delete"),
 			},
 			mailbox: {
-				get: async () => h.mailbox,
+				get: async () => {
+					if (h.mailboxError) throw h.mailboxError;
+					return h.mailbox;
+				},
 				update: record("mailbox.update"),
 			},
 			secrets: {},
@@ -191,6 +195,17 @@ describe("handleEmptyTrash", () => {
 		assert.equal(called("message.delete").length, 0);
 	});
 
+	it("acks terminally without connecting when the Trash mailbox was deleted", async () => {
+		h.mailboxError = Object.assign(new Error("Mailbox not found: trash-mbx"), {
+			name: "NotFoundError",
+		});
+
+		await handleEmptyTrash(event, noopLog, deps());
+
+		assert.equal(h.getConnectionCount, 0);
+		assert.equal(called("message.delete").length, 0);
+	});
+
 	it("pauses quietly when openBox trips a UIDVALIDITY mismatch", async () => {
 		h.connection.openBox = async () => ({ uidvalidity: 999 });
 

package/src/handlers/empty-trash.ts

@@ -8,6 +8,7 @@ import {
 import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import type { EmptyTrashEvent } 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";
 
@@ -70,7 +71,24 @@ export const handleEmptyTrash = async (
 		account,
 		log,
 		async (credentials) => {
-			const mailbox = await mailboxService.get(accountId, trashMailboxId);
+			// The Trash folder can be deleted between enqueue and this sync, leaving a
+			// queued event pointing at a gone row. The lookup then throws
+			// NotFoundError forever, and on the account's per-group FIFO that head
+			// message stalls the whole pipeline (issues #287, #289, #290). A deleted
+			// Trash makes the empty moot: ack with a WARN.
+			const mailbox = await mailboxService
+				.get(accountId, trashMailboxId)
+				.catch((error: unknown) => {
+					if (isNotFoundError(error)) return null;
+					throw error;
+				});
+			if (!mailbox) {
+				log.warn(
+					{ accountId, mailboxId: trashMailboxId },
+					"Skipping EMPTY_TRASH: mailbox no longer exists (deleted)",
+				);
+				return;
+			}
 
 			// Cheap frugal skip (epic #1281 invariant 6): a mailbox already known
 			// paused never even opens a connection. Optimization only — the

package/src/handlers/flag-push.test.ts

@@ -1,6 +1,27 @@
 import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import { FLAG_PUSH_MAX_ATTEMPTS, getFlagPushMaxAttempts } from "./flag-push.js";
+import { afterEach, describe, it, mock } from "node:test";
+import { getClient } from "@remit/backend/client";
+import type { Logger } from "@remit/logger-lambda";
+import type { FlagPushEvent } from "../events.js";
+import {
+	FLAG_PUSH_MAX_ATTEMPTS,
+	getFlagPushMaxAttempts,
+	handleFlagPush,
+} from "./flag-push.js";
+
+const silentLogger = (() => {
+	const noop = () => {};
+	const log = {
+		info: noop,
+		warn: noop,
+		error: noop,
+		debug: noop,
+		fatal: noop,
+		trace: noop,
+		child: () => log,
+	} as unknown as Logger;
+	return log;
+})();
 
 describe("getFlagPushMaxAttempts — env-derived threshold (mirrors #1270's getBodySyncMaxAttempts / #1289's getPlacementMoveMaxAttempts)", () => {
 	it("parses the CDK-injected env var", () => {
@@ -23,3 +44,55 @@ describe("getFlagPushMaxAttempts — env-derived threshold (mirrors #1270's getB
 		assert.ok(FLAG_PUSH_MAX_ATTEMPTS > 0);
 	});
 });
+
+describe("handleFlagPush — deleted mailbox is terminal (#287/#289)", () => {
+	const accountId = "fp-acc-zzz";
+	const messageId = "fp-msg-zzz";
+	const flagName = "\\Seen";
+
+	const event: FlagPushEvent = {
+		type: "FLAG_PUSH",
+		accountId,
+		accountConfigId: "fp-cfg-zzz",
+		messageId,
+		flagName,
+	} as FlagPushEvent;
+
+	afterEach(() => mock.restoreAll());
+
+	it("drops the orphaned marker and acks without pushing when the mailbox is gone", async () => {
+		const client = await getClient();
+		mock.method(client.account, "get", async () => ({
+			accountId,
+			accountConfigId: "fp-cfg-zzz",
+		}));
+		mock.method(client.message, "get", async () => [
+			{ messageId, mailboxId: "gone-mbx", uid: 42 },
+		]);
+		mock.method(client.mailbox, "get", async () => {
+			throw Object.assign(new Error("Mailbox not found: gone-mbx"), {
+				name: "NotFoundError",
+			});
+		});
+		mock.method(client.flagPush, "find", async () => ({
+			operation: "add",
+			state: "pending",
+		}));
+		mock.method(client.flagPush, "updateState", async () => {});
+		const deleteMarker = mock.method(client.flagPush, "delete", async () => {});
+
+		// Must resolve, not reject — a deleted folder is an expected terminal
+		// outcome, not a fault to retry on the account's per-group FIFO.
+		await handleFlagPush(event, silentLogger, 1);
+
+		assert.equal(
+			deleteMarker.mock.calls.length,
+			1,
+			"the orphaned marker is dropped",
+		);
+		assert.deepEqual(deleteMarker.mock.calls[0].arguments, [
+			messageId,
+			flagName,
+		]);
+	});
+});

package/src/handlers/flag-push.ts

@@ -10,6 +10,7 @@ import {
 import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import type { FlagPushEvent } 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";
 
@@ -113,7 +114,25 @@ export const handleFlagPush = async (
 	// died mid-flight already left it here).
 	await markerService.updateState(messageId, flagName, "processing");
 
-	const mailbox = await mailboxService.get(accountId, message.mailboxId);
+	// The folder can be deleted between enqueue and this push, leaving a marker
+	// pointing at a gone row. The lookup then throws NotFoundError forever, and
+	// on the account's per-group FIFO that head message stalls the whole pipeline
+	// (issues #287, #289, #290). The push is moot — drop the orphaned marker (as
+	// the message-gone branch above already does) and ack with a WARN.
+	const mailbox = await mailboxService
+		.get(accountId, message.mailboxId)
+		.catch((error: unknown) => {
+			if (isNotFoundError(error)) return null;
+			throw error;
+		});
+	if (!mailbox) {
+		await markerService.delete(messageId, flagName);
+		log.warn(
+			{ messageId, flagName, accountId, mailboxId: message.mailboxId },
+			"Skipping FLAG_PUSH: mailbox no longer exists (deleted); marker dropped",
+		);
+		return;
+	}
 
 	// Cheap frugal skip (epic #1281 invariant 6): a mailbox already known
 	// paused never even borrows a connection. Optimization only — the

package/src/handlers/mailbox-management.test.ts

@@ -51,11 +51,17 @@ interface Harness {
 		deletedAt?: number;
 	} | null;
 	connection: Connection;
+	mailboxUpdateError?: Error;
 	disconnectCount: number;
 }
 
 let h: Harness;
 
+const notFoundError = (): Error =>
+	Object.assign(new Error("Mailbox not found: mbx-1"), {
+		name: "NotFoundError",
+	});
+
 const record =
 	(method: string) =>
 	async (...args: unknown[]) => {
@@ -96,7 +102,10 @@ const deps = (): MailboxManagementDeps =>
 				},
 			},
 			mailbox: {
-				update: record("mailbox.update"),
+				update: async (...args: unknown[]) => {
+					h.calls.push({ method: "mailbox.update", args });
+					if (h.mailboxUpdateError) throw h.mailboxUpdateError;
+				},
 				delete: record("mailbox.delete"),
 			},
 			secrets: {},
@@ -207,6 +216,16 @@ describe("processMailboxManagement — MAILBOX_CREATE", () => {
 		assert.equal(h.disconnectCount, 1);
 	});
 
+	it("acks terminally without rethrowing when the mailbox row was deleted mid-create (#289)", async () => {
+		// The status write-back throws NotFoundError because the row is gone; the
+		// create is moot and must not poison the account's FIFO.
+		h.mailboxUpdateError = notFoundError();
+
+		await processMailboxManagement(createEvent, noopLog, deps());
+
+		assert.equal(h.disconnectCount, 1, "the scope is still disconnected");
+	});
+
 	it("returns early without connecting when the account is soft-deleted", async () => {
 		h.account = {
 			accountId: "acc-1",
@@ -258,6 +277,17 @@ describe("processMailboxManagement — MAILBOX_RENAME", () => {
 		assert.equal(called("mailbox.update").length, 0);
 	});
 
+	it("acks terminally without rethrowing when the rollback write finds the row gone", async () => {
+		h.connection.renameMailbox = async () => {
+			throw new Error("server exploded");
+		};
+		h.mailboxUpdateError = notFoundError();
+
+		await processMailboxManagement(renameEvent, noopLog, deps());
+
+		assert.equal(h.disconnectCount, 1, "the scope is still disconnected");
+	});
+
 	it("rolls the local path back and rethrows on any other rename error", async () => {
 		h.connection.renameMailbox = async () => {
 			throw new Error("server exploded");
@@ -321,4 +351,15 @@ describe("processMailboxManagement — MAILBOX_DELETE", () => {
 
 		assert.deepEqual(lastUpdate(), { syncStatus: "failed" });
 	});
+
+	it("acks terminally without rethrowing when the rollback write finds the row gone", async () => {
+		h.connection.deleteMailbox = async () => {
+			throw new Error("server exploded");
+		};
+		h.mailboxUpdateError = notFoundError();
+
+		await processMailboxManagement(deleteEvent, noopLog, deps());
+
+		assert.equal(h.disconnectCount, 1, "the scope is still disconnected");
+	});
 });

package/src/handlers/mailbox-management.ts

@@ -10,6 +10,7 @@ import type {
 	MailboxManagementEvent,
 	MailboxRenameEvent,
 } 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";
 
@@ -27,6 +28,21 @@ const defaultDeps: MailboxManagementDeps = {
 	createConnectionScope: createConnectionScopeWithCredentials,
 };
 
+/**
+ * Pinned invariant for the whole-chain terminal guards below.
+ *
+ * Each handler wraps its `MailboxManagementService.sync*` chain in a try/catch
+ * that treats a NotFoundError as terminal (ack with a WARN, issue #289). That
+ * is only sound because `syncCreate` / `syncRename` / `syncDelete` — and their
+ * error-recovery branches here — touch nothing but the single target mailbox
+ * row via `mailboxService.get/update/delete(accountId, mailboxId)`. So the only
+ * row a NotFoundError can refer to is that target, and its absence can only mean
+ * the user deleted the folder mid-sync — never an unrelated missing entity that
+ * should have been retried. If a sync method ever reads or writes a second
+ * entity, narrow these catches (match the mailboxId / re-check existence) before
+ * a NotFoundError from elsewhere is silently acked.
+ */
+
 /**
  * Handle MAILBOX_CREATE event
  */
@@ -72,39 +88,65 @@ const handleCreate = async (
 				log,
 			);
 
-			await managementService
-				.syncCreate(accountId, mailboxId, path, scope.getConnection, subscribe)
-				.then((result) => {
-					if (result.success) {
-						log.info({ accountId, mailboxId, path }, "Mailbox created on IMAP");
-					} else {
-						log.error(
-							{ accountId, mailboxId, path, error: result.error },
-							"Failed to create mailbox on IMAP",
-						);
-					}
-				})
-				.catch(async (error) => {
-					// Check if mailbox already exists (idempotent)
-					if (
-						error instanceof Error &&
-						error.message.includes("already exists")
-					) {
-						log.info(
-							{ accountId, mailboxId, path },
-							"Mailbox already exists, marking as synced",
-						);
-						await mailboxService.update(accountId, mailboxId, {
-							syncStatus: MailboxSyncStatus.synced,
-						});
-					} else {
-						await mailboxService.update(accountId, mailboxId, {
-							syncStatus: MailboxSyncStatus.failed,
-						});
-						throw error;
-					}
-				})
-				.finally(() => scope.disconnect());
+			try {
+				await managementService
+					.syncCreate(
+						accountId,
+						mailboxId,
+						path,
+						scope.getConnection,
+						subscribe,
+					)
+					.then((result) => {
+						if (result.success) {
+							log.info(
+								{ accountId, mailboxId, path },
+								"Mailbox created on IMAP",
+							);
+						} else {
+							log.error(
+								{ accountId, mailboxId, path, error: result.error },
+								"Failed to create mailbox on IMAP",
+							);
+						}
+					})
+					.catch(async (error) => {
+						// Check if mailbox already exists (idempotent)
+						if (
+							error instanceof Error &&
+							error.message.includes("already exists")
+						) {
+							log.info(
+								{ accountId, mailboxId, path },
+								"Mailbox already exists, marking as synced",
+							);
+							await mailboxService.update(accountId, mailboxId, {
+								syncStatus: MailboxSyncStatus.synced,
+							});
+						} else {
+							await mailboxService.update(accountId, mailboxId, {
+								syncStatus: MailboxSyncStatus.failed,
+							});
+							throw error;
+						}
+					})
+					.finally(() => scope.disconnect());
+			} catch (error) {
+				// The mailbox row was deleted between enqueue and this sync — the
+				// create-then-status-write throws NotFoundError, which can never
+				// succeed on retry and would poison the account's per-group FIFO
+				// forever (issue #289, same class as #287/#290). A folder the user
+				// deleted is an expected terminal outcome: ack with a WARN. Real
+				// IMAP/infra failures carry other errors and still propagate.
+				if (isNotFoundError(error)) {
+					log.warn(
+						{ accountId, mailboxId, path, eventId: event.eventId },
+						"Skipping MAILBOX_CREATE: mailbox no longer exists (deleted)",
+					);
+					return;
+				}
+				throw error;
+			}
 		},
 	);
 };
@@ -157,40 +199,61 @@ const handleRename = async (
 				log,
 			);
 
-			await managementService
-				.syncRename(accountId, mailboxId, oldPath, newPath, scope.getConnection)
-				.then((result) => {
-					if (result.success) {
-						log.info(
-							{ accountId, mailboxId, oldPath, newPath },
-							"Mailbox renamed on IMAP",
-						);
-					} else {
-						log.error(
-							{ accountId, mailboxId, oldPath, newPath, error: result.error },
-							"Failed to rename mailbox on IMAP",
-						);
-					}
-				})
-				.catch(async (error) => {
-					// If source not found, delete local mailbox
-					if (error instanceof Error && error.message.includes("not found")) {
-						log.info(
-							{ accountId, mailboxId, oldPath },
-							"Source mailbox not found, deleting local",
-						);
-						await mailboxService.delete(accountId, mailboxId);
-					} else {
-						// Rollback local rename by restoring old path
-						await mailboxService.update(accountId, mailboxId, {
-							fullPath: oldPath,
-							oldPath: undefined,
-							syncStatus: MailboxSyncStatus.failed,
-						});
-						throw error;
-					}
-				})
-				.finally(() => scope.disconnect());
+			try {
+				await managementService
+					.syncRename(
+						accountId,
+						mailboxId,
+						oldPath,
+						newPath,
+						scope.getConnection,
+					)
+					.then((result) => {
+						if (result.success) {
+							log.info(
+								{ accountId, mailboxId, oldPath, newPath },
+								"Mailbox renamed on IMAP",
+							);
+						} else {
+							log.error(
+								{ accountId, mailboxId, oldPath, newPath, error: result.error },
+								"Failed to rename mailbox on IMAP",
+							);
+						}
+					})
+					.catch(async (error) => {
+						// If source not found, delete local mailbox
+						if (error instanceof Error && error.message.includes("not found")) {
+							log.info(
+								{ accountId, mailboxId, oldPath },
+								"Source mailbox not found, deleting local",
+							);
+							await mailboxService.delete(accountId, mailboxId);
+						} else {
+							// Rollback local rename by restoring old path
+							await mailboxService.update(accountId, mailboxId, {
+								fullPath: oldPath,
+								oldPath: undefined,
+								syncStatus: MailboxSyncStatus.failed,
+							});
+							throw error;
+						}
+					})
+					.finally(() => scope.disconnect());
+			} catch (error) {
+				// The mailbox row was deleted between enqueue and this sync — the
+				// status write-back throws NotFoundError, unretryable and would poison
+				// the account's per-group FIFO forever (issue #289 class). Ack with a
+				// WARN; real IMAP/infra failures carry other errors and still propagate.
+				if (isNotFoundError(error)) {
+					log.warn(
+						{ accountId, mailboxId, oldPath, newPath, eventId: event.eventId },
+						"Skipping MAILBOX_RENAME: mailbox no longer exists (deleted)",
+					);
+					return;
+				}
+				throw error;
+			}
 		},
 	);
 };
@@ -240,48 +303,67 @@ const handleDelete = async (
 				log,
 			);
 
-			await managementService
-				.syncDelete(accountId, mailboxId, path, scope.getConnection)
-				.then((result) => {
-					if (result.success) {
-						log.info({ accountId, mailboxId, path }, "Mailbox deleted on IMAP");
-					} else {
-						log.error(
-							{ accountId, mailboxId, path, error: result.error },
-							"Failed to delete mailbox on IMAP",
-						);
-					}
-				})
-				.catch(async (error) => {
-					// If mailbox not found, it's already deleted (idempotent)
-					if (error instanceof Error && error.message.includes("not found")) {
-						log.info(
-							{ accountId, mailboxId, path },
-							"Mailbox not found on IMAP, deleting local",
-						);
-						await mailboxService.delete(accountId, mailboxId);
-					} else if (
-						error instanceof Error &&
-						error.message.includes("Cannot delete INBOX")
-					) {
-						// Restore the mailbox
-						await mailboxService.update(accountId, mailboxId, {
-							syncStatus: MailboxSyncStatus.synced,
-						});
-						log.error(
-							{ accountId, mailboxId, path },
-							"Cannot delete INBOX, restoring mailbox",
-						);
-						// Don't rethrow - this is an expected error
-					} else {
-						// Restore the mailbox on other errors
-						await mailboxService.update(accountId, mailboxId, {
-							syncStatus: MailboxSyncStatus.failed,
-						});
-						throw error;
-					}
-				})
-				.finally(() => scope.disconnect());
+			try {
+				await managementService
+					.syncDelete(accountId, mailboxId, path, scope.getConnection)
+					.then((result) => {
+						if (result.success) {
+							log.info(
+								{ accountId, mailboxId, path },
+								"Mailbox deleted on IMAP",
+							);
+						} else {
+							log.error(
+								{ accountId, mailboxId, path, error: result.error },
+								"Failed to delete mailbox on IMAP",
+							);
+						}
+					})
+					.catch(async (error) => {
+						// If mailbox not found, it's already deleted (idempotent)
+						if (error instanceof Error && error.message.includes("not found")) {
+							log.info(
+								{ accountId, mailboxId, path },
+								"Mailbox not found on IMAP, deleting local",
+							);
+							await mailboxService.delete(accountId, mailboxId);
+						} else if (
+							error instanceof Error &&
+							error.message.includes("Cannot delete INBOX")
+						) {
+							// Restore the mailbox
+							await mailboxService.update(accountId, mailboxId, {
+								syncStatus: MailboxSyncStatus.synced,
+							});
+							log.error(
+								{ accountId, mailboxId, path },
+								"Cannot delete INBOX, restoring mailbox",
+							);
+							// Don't rethrow - this is an expected error
+						} else {
+							// Restore the mailbox on other errors
+							await mailboxService.update(accountId, mailboxId, {
+								syncStatus: MailboxSyncStatus.failed,
+							});
+							throw error;
+						}
+					})
+					.finally(() => scope.disconnect());
+			} catch (error) {
+				// The mailbox row was already deleted (a duplicate/racing delete) — the
+				// error-recovery status write throws NotFoundError, unretryable and
+				// would poison the account's per-group FIFO forever (issue #289 class).
+				// The delete has effectively happened: ack with a WARN. Real IMAP/infra
+				// failures carry other errors and still propagate.
+				if (isNotFoundError(error)) {
+					log.warn(
+						{ accountId, mailboxId, path, eventId: event.eventId },
+						"Skipping MAILBOX_DELETE: mailbox no longer exists (deleted)",
+					);
+					return;
+				}
+				throw error;
+			}
 		},
 	);
 };

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

@@ -39,6 +39,7 @@ interface Harness {
 		deletedAt?: number;
 	} | null;
 	mailbox: { mailboxId: string; uidValidity: number; cursorState?: string };
+	mailboxError?: Error;
 	connection: Connection;
 	getConnectionCount: number;
 	disconnectCount: number;
@@ -46,6 +47,11 @@ interface Harness {
 
 let h: Harness;
 
+const notFoundError = (): Error =>
+	Object.assign(new Error("Mailbox not found: src-mbx"), {
+		name: "NotFoundError",
+	});
+
 const record =
 	(method: string) =>
 	async (...args: unknown[]) => {
@@ -94,7 +100,10 @@ const deps = (): MessageCopyDeps =>
 				update: record("threadMessage.update"),
 			},
 			mailbox: {
-				get: async () => h.mailbox,
+				get: async () => {
+					if (h.mailboxError) throw h.mailboxError;
+					return h.mailbox;
+				},
 				update: record("mailbox.update"),
 			},
 			secrets: {},
@@ -189,6 +198,16 @@ describe("handleMessageCopy", () => {
 		);
 	});
 
+	it("acks terminally without connecting when the source mailbox was deleted", async () => {
+		h.mailboxError = notFoundError();
+
+		await handleMessageCopy(event, noopLog, deps());
+
+		assert.equal(h.getConnectionCount, 0);
+		assert.equal(called("message.updateUid").length, 0);
+		assert.equal(called("message.update").length, 0);
+	});
+
 	it("skips the copy without opening a connection when the cursor is rebuilding", async () => {
 		h.mailbox = {
 			mailboxId: "src-mbx",

package/src/handlers/message-copy.ts

@@ -9,6 +9,7 @@ import {
 import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import type { MessageCopyEvent } 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";
 
@@ -87,7 +88,24 @@ export const handleMessageCopy = async (
 		account,
 		log,
 		async (credentials) => {
-			const mailbox = await mailboxService.get(accountId, sourceMailboxId);
+			// The source folder can be deleted between enqueue and this sync, leaving
+			// a queued event pointing at a gone row. The lookup then throws
+			// NotFoundError forever, and on the account's per-group FIFO that head
+			// message stalls the whole pipeline (issues #287, #289, #290). A deleted
+			// source mailbox makes the copy moot: ack with a WARN.
+			const mailbox = await mailboxService
+				.get(accountId, sourceMailboxId)
+				.catch((error: unknown) => {
+					if (isNotFoundError(error)) return null;
+					throw error;
+				});
+			if (!mailbox) {
+				log.warn(
+					{ accountId, sourceMessageId, mailboxId: sourceMailboxId },
+					"Skipping MESSAGE_COPY: source mailbox no longer exists (deleted)",
+				);
+				return;
+			}
 
 			// Cheap frugal skip (epic #1281 invariant 6): a mailbox already known
 			// paused never even opens a connection. Optimization only — the

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

@@ -215,6 +215,7 @@ interface Harness {
 		deletedAt?: number;
 	} | null;
 	mailbox: { mailboxId: string; uidValidity: number; cursorState?: string };
+	mailboxError?: Error;
 	connection: Connection;
 	threadMessage: Record<string, unknown> | null;
 	allThreadMessages: { accountConfigId: string; threadMessageId: string }[];
@@ -280,7 +281,10 @@ const deps = (): MessageDeleteDeps =>
 				delete: record("threadMessage.delete"),
 			},
 			mailbox: {
-				get: async () => h.mailbox,
+				get: async () => {
+					if (h.mailboxError) throw h.mailboxError;
+					return h.mailbox;
+				},
 				update: record("mailbox.update"),
 			},
 			secrets: {},
@@ -442,6 +446,18 @@ describe("handleMessageDelete", () => {
 		assert.equal(h.getConnectionCount, 0);
 	});
 
+	it("acks terminally without connecting when the mailbox was deleted", async () => {
+		h.mailboxError = Object.assign(new Error("Mailbox not found: src-mbx"), {
+			name: "NotFoundError",
+		});
+
+		await handleMessageDelete(moveEvent, noopLog, deps());
+
+		assert.equal(h.getConnectionCount, 0);
+		assert.equal(called("message.updateUid").length, 0);
+		assert.equal(called("message.delete").length, 0);
+	});
+
 	it("returns early without connecting when the account is soft-deleted", async () => {
 		h.account = {
 			accountId: "acc-1",

package/src/handlers/message-delete.ts

@@ -13,6 +13,7 @@ import {
 import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import type { MessageDeleteEvent } from "../events.js";
+import { isNotFoundError } from "../is-not-found.js";
 import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
 import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
 
@@ -151,7 +152,24 @@ export const handleMessageDelete = async (
 		account,
 		log,
 		async (credentials) => {
-			const mailbox = await mailboxService.get(accountId, mailboxId);
+			// The folder can be deleted between enqueue and this sync, leaving a
+			// queued event pointing at a gone row. The lookup then throws
+			// NotFoundError forever, and on the account's per-group FIFO that head
+			// message stalls the whole pipeline (issues #287, #289, #290). A deleted
+			// mailbox makes the delete moot: ack with a WARN.
+			const mailbox = await mailboxService
+				.get(accountId, mailboxId)
+				.catch((error: unknown) => {
+					if (isNotFoundError(error)) return null;
+					throw error;
+				});
+			if (!mailbox) {
+				log.warn(
+					{ accountId, messageId, mailboxId },
+					"Skipping MESSAGE_DELETE: mailbox no longer exists (deleted)",
+				);
+				return;
+			}
 
 			// Cheap frugal skip (epic #1281 invariant 6): a mailbox already known
 			// paused never even opens a connection. Optimization only — the

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

@@ -1,12 +1,30 @@
 import assert from "node:assert";
-import { describe, it, mock } from "node:test";
-import type { ThreadMessageItem } from "@remit/data-ports";
+import { afterEach, describe, it, mock } from "node:test";
+import { getClient } from "@remit/backend/client";
+import type { AccountItem, ThreadMessageItem } from "@remit/data-ports";
+import type { Logger } from "@remit/logger-lambda";
+import type { MessageMoveEvent } from "../events.js";
 import {
 	buildThreadMessageMoveUpdate,
 	emitMoveResync,
+	handleMessageMove,
 	moveThenResync,
 } from "./message-move.js";
 
+const silentLogger = (() => {
+	const noop = () => {};
+	const log = {
+		info: noop,
+		warn: noop,
+		error: noop,
+		debug: noop,
+		fatal: noop,
+		trace: noop,
+		child: () => log,
+	} as unknown as Logger;
+	return log;
+})();
+
 const sourceMailboxId = "source-mailbox-id-aaaaaaaaa";
 const destinationMailboxId = "destination-mailbox-aaaaa";
 
@@ -166,3 +184,61 @@ describe("moveThenResync (#1031)", () => {
 		assert.equal(resync.mock.calls.length, 0);
 	});
 });
+
+describe("handleMessageMove — deleted mailbox is terminal (#287/#289)", () => {
+	const acctId = "mm-acc-zzz";
+
+	const cappedAccount = (): AccountItem =>
+		({
+			accountId: acctId,
+			accountConfigId: "mm-cfg-zzz",
+			connectionState: "authenticated",
+			username: "mm@imap.example.com",
+			imapHost: "imap.example.com",
+			imapPort: 993,
+			imapTls: true,
+			passwordHash: JSON.stringify({
+				encryptedDek: "",
+				encryptedData: "",
+				iv: "",
+				authTag: "",
+			}),
+		}) as unknown as AccountItem;
+
+	const event: MessageMoveEvent = {
+		type: "MESSAGE_MOVE",
+		accountId: acctId,
+		accountConfigId: "mm-cfg-zzz",
+		messageId: "mm-msg-zzz",
+		sourceMailboxId: "mm-src-zzz",
+		sourceMailboxPath: "INBOX",
+		destinationMailboxId: "mm-dst-zzz",
+		destinationMailboxPath: "Archive",
+		uid: 10,
+		eventId: "mm-evt-zzz",
+		timestamp: 1700000000000,
+	} as MessageMoveEvent;
+
+	afterEach(() => mock.restoreAll());
+
+	it("acks without connecting when the source mailbox was deleted", async () => {
+		const client = await getClient();
+		mock.method(client.account, "get", async () => cappedAccount());
+		mock.method(client.secrets, "decrypt", async () => "fake-password");
+		mock.method(client.mailbox, "get", async () => {
+			throw Object.assign(new Error("Mailbox not found: mm-src-zzz"), {
+				name: "NotFoundError",
+			});
+		});
+		const updateUid = mock.method(client.message, "updateUid", async () => {});
+
+		// Must resolve, not reject — a deleted source folder makes the move moot.
+		await handleMessageMove(event, silentLogger);
+
+		assert.equal(
+			updateUid.mock.calls.length,
+			0,
+			"a deleted mailbox never reaches the IMAP move",
+		);
+	});
+});

package/src/handlers/message-move.ts

@@ -11,6 +11,7 @@ import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import { emitEvent } from "../emit.js";
 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";
 
@@ -144,7 +145,24 @@ export const handleMessageMove = async (
 		account,
 		log,
 		async (credentials) => {
-			const mailbox = await mailboxService.get(accountId, sourceMailboxId);
+			// The source folder can be deleted between enqueue and this sync, leaving
+			// a queued event pointing at a gone row. The lookup then throws
+			// NotFoundError forever, and on the account's per-group FIFO that head
+			// message stalls the whole pipeline (issues #287, #289, #290). A deleted
+			// source mailbox makes the move moot: ack with a WARN.
+			const mailbox = await mailboxService
+				.get(accountId, sourceMailboxId)
+				.catch((error: unknown) => {
+					if (isNotFoundError(error)) return null;
+					throw error;
+				});
+			if (!mailbox) {
+				log.warn(
+					{ accountId, messageId, mailboxId: sourceMailboxId },
+					"Skipping MESSAGE_MOVE: source mailbox no longer exists (deleted)",
+				);
+				return;
+			}
 
 			// Cheap frugal skip (epic #1281 invariant 6): a mailbox already known
 			// paused never even opens a connection. Optimization only — the

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

@@ -1,12 +1,30 @@
 import assert from "node:assert/strict";
-import { describe, it } from "node:test";
+import { afterEach, describe, it, mock } from "node:test";
+import { getClient } from "@remit/backend/client";
+import type { Logger } from "@remit/logger-lambda";
 import type { IImapConnection } from "@remit/mailbox-service";
+import type { PlacementMovePushEvent } from "../events.js";
 import {
 	attemptMove,
 	getPlacementMoveMaxAttempts,
+	handlePlacementMovePush,
 	PLACEMENT_MOVE_MAX_ATTEMPTS,
 } from "./placement-move-push.js";
 
+const silentLogger = (() => {
+	const noop = () => {};
+	const log = {
+		info: noop,
+		warn: noop,
+		error: noop,
+		debug: noop,
+		fatal: noop,
+		trace: noop,
+		child: () => log,
+	} as unknown as Logger;
+	return log;
+})();
+
 const buildConnection = (opts: {
 	uidMap?: Map<number, number>;
 	moveError?: Error;
@@ -262,3 +280,54 @@ describe("getPlacementMoveMaxAttempts — env-derived threshold (mirrors #1270's
 		assert.ok(PLACEMENT_MOVE_MAX_ATTEMPTS > 0);
 	});
 });
+
+describe("handlePlacementMovePush — deleted mailbox is terminal (#287/#289)", () => {
+	const accountId = "pm-acc-zzz";
+	const messageId = "pm-msg-zzz";
+	const destinationMailboxId = "pm-dest-zzz";
+
+	const event: PlacementMovePushEvent = {
+		type: "PLACEMENT_MOVE_PUSH",
+		accountId,
+		accountConfigId: "pm-cfg-zzz",
+		messageId,
+		eventId: "pm-evt-zzz",
+		timestamp: 1700000000000,
+	};
+
+	afterEach(() => mock.restoreAll());
+
+	it("drops the marker and acks without pushing when a mailbox is gone", async () => {
+		const client = await getClient();
+		mock.method(client.account, "get", async () => ({
+			accountId,
+			accountConfigId: "pm-cfg-zzz",
+		}));
+		mock.method(client.message, "get", async () => ({
+			messageId,
+			mailboxId: destinationMailboxId,
+		}));
+		mock.method(client.mailbox, "get", async () => {
+			throw Object.assign(new Error("Mailbox not found: pm-src-zzz"), {
+				name: "NotFoundError",
+			});
+		});
+		mock.method(client.placementMove, "find", async () => ({
+			sourceMailboxId: "pm-src-zzz",
+			destinationMailboxId,
+		}));
+		mock.method(client.placementMove, "updateState", async () => {});
+		const deleteMarker = mock.method(
+			client.placementMove,
+			"delete",
+			async () => {},
+		);
+
+		// Must resolve, not reject — a deleted folder is an expected terminal
+		// outcome, not a fault to retry on the account's per-group FIFO.
+		await handlePlacementMovePush(event, silentLogger, 1);
+
+		assert.equal(deleteMarker.mock.calls.length, 1, "the marker is dropped");
+		assert.deepEqual(deleteMarker.mock.calls[0].arguments, [messageId]);
+	});
+});

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

@@ -14,6 +14,7 @@ import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import { emitEvent } from "../emit.js";
 import type { PlacementMovePushEvent } 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 {
@@ -227,14 +228,32 @@ export const handlePlacementMovePush = async (
 	// died mid-flight already left it here).
 	await markerService.updateState(messageId, "processing");
 
-	const sourceMailbox = await mailboxService.get(
-		accountId,
-		marker.sourceMailboxId,
-	);
-	const destinationMailbox = await mailboxService.get(
-		accountId,
-		marker.destinationMailboxId,
-	);
+	// Either folder can be deleted between enqueue and this push, leaving a
+	// marker pointing at a gone row. The lookup then throws NotFoundError forever,
+	// and on the account's per-group FIFO that head message stalls the whole
+	// pipeline (issues #287, #289, #290). The move is moot — drop the marker (as
+	// the superseded branch above does) and ack with a WARN.
+	const mailboxes = await Promise.all([
+		mailboxService.get(accountId, marker.sourceMailboxId),
+		mailboxService.get(accountId, marker.destinationMailboxId),
+	]).catch((error: unknown) => {
+		if (isNotFoundError(error)) return null;
+		throw error;
+	});
+	if (!mailboxes) {
+		await markerService.delete(messageId);
+		log.warn(
+			{
+				messageId,
+				accountId,
+				sourceMailboxId: marker.sourceMailboxId,
+				destinationMailboxId: marker.destinationMailboxId,
+			},
+			"Skipping PLACEMENT_MOVE_PUSH: a mailbox no longer exists (deleted); marker dropped",
+		);
+		return;
+	}
+	const [sourceMailbox, destinationMailbox] = mailboxes;
 
 	// Cheap frugal skip (epic #1281 invariant 6): either mailbox already known
 	// paused never even borrows a connection. Optimization only — the

package/src/handlers/sync-message-body.test.ts

@@ -302,6 +302,54 @@ describe("syncMessageBody — DLQ propagation (integrated, #1270)", () => {
 		);
 	});
 
+	test("deleted mailbox: acks-and-skips without ever calling BodySyncService.syncBodies (#287/#289)", async () => {
+		// A SYNC_MESSAGE_BODY trigger outlived the folder it targeted. The mailbox
+		// lookup throws NotFoundError, which would poison the account's per-group
+		// body FIFO forever; the handler must resolve it terminally instead.
+		mockClient(SSMClient)
+			.on(GetParameterCommand)
+			.resolves({ Parameter: { Value: "true" } });
+
+		mock.method((await getClient()).account, "get", async () =>
+			cappedAccount(),
+		);
+		mock.method((await getClient()).mailbox, "get", async () => {
+			throw Object.assign(new Error(`Mailbox not found: ${mailboxId}`), {
+				name: "NotFoundError",
+			});
+		});
+		mock.method(
+			(await getClient()).secrets,
+			"decrypt",
+			async () => "fake-password",
+		);
+		const syncBodies = mock.method(
+			BodySyncService.prototype,
+			"syncBodies",
+			async () => {
+				throw new Error("must not be called for a deleted mailbox");
+			},
+		);
+
+		const event: SyncMessageBodyEvent = {
+			...baseEvent,
+			accountId,
+			mailboxId,
+			messageIds: ["msg-1"],
+			messages: [{ messageId: "msg-1", uid: 101 }],
+		};
+
+		// Must resolve, not reject — a deleted folder is an expected terminal
+		// outcome, not a fault to retry/DLQ.
+		await syncMessageBody(event, silentLogger, 1);
+
+		assert.equal(
+			syncBodies.mock.calls.length,
+			0,
+			"a deleted mailbox must never reach the body fetch",
+		);
+	});
+
 	test("cursor_invalid: acks-and-skips without ever calling BodySyncService.syncBodies (#1272)", async () => {
 		// The cheap pre-check (isCursorRebuildNeeded, run before borrowing any
 		// connection — frugal, epic #1281 invariant 6) catches an already-paused

package/src/handlers/sync-message-body.ts

@@ -19,6 +19,7 @@ import {
 	createConnectionScopeWithCredentials,
 } from "../connection-scope.js";
 import type { SyncMessageBodyEvent } 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 { workerVersion } from "../worker-version.js";
@@ -184,7 +185,25 @@ export const syncMessageBody = async (
 		account,
 		log,
 		async (credentials) => {
-			const mailbox = await mailboxService.get(accountId, mailboxId);
+			// A SYNC_MESSAGE_BODY trigger can outlive the mailbox it targets: deleting
+			// a folder that held mail leaves already-queued body events pointing at a
+			// row that is now gone, and the lookup then throws NotFoundError forever.
+			// Since the body queue carries MessageGroupId=accountId, that head message
+			// stalls the account's whole body pipeline (issues #287, #289, #290). A
+			// deleted folder is an expected terminal outcome: ack with a WARN.
+			const mailbox = await mailboxService
+				.get(accountId, mailboxId)
+				.catch((error: unknown) => {
+					if (isNotFoundError(error)) return null;
+					throw error;
+				});
+			if (!mailbox) {
+				log.warn(
+					{ accountId, mailboxId, eventId: event.eventId },
+					"Skipping SYNC_MESSAGE_BODY: mailbox no longer exists (deleted)",
+				);
+				return;
+			}
 
 			// Cheap frugal skip (epic #1281 invariant 6): a mailbox already known
 			// paused never even borrows a connection. This is an optimization only

package/src/handlers/sync-messages.ts

@@ -32,6 +32,7 @@ import type {
 	SyncMessageBodyEvent,
 	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 { workerVersion } from "../worker-version.js";
@@ -104,7 +105,7 @@ export const syncMessages = async (
 	// other errors and still propagate to be retried.
 	let account: AccountItem;
 	const rawAccount = await accountService.get(event.accountId).catch((err) => {
-		if ((err as { name?: string })?.name === "NotFoundError") return null;
+		if (isNotFoundError(err)) return null;
 		throw err;
 	});
 	if (!rawAccount) {
@@ -144,7 +145,7 @@ export const syncMessages = async (
 		.get(event.accountId, event.mailboxId)
 		.then(() => true)
 		.catch((err) => {
-			if ((err as { name?: string })?.name === "NotFoundError") return false;
+			if (isNotFoundError(err)) return false;
 			throw err;
 		});
 	if (!mailboxExists) {

package/src/is-not-found.ts

@@ -0,0 +1,17 @@
+/**
+ * A repository lookup or write for a row that no longer exists rejects with a
+ * `NotFoundError` (name-matched, since the class crosses the data-ports adapter
+ * boundary — see `@remit/data-ports/errors`).
+ *
+ * A worker event that references a deliberately-deleted mailbox is completed or
+ * moot work, never a transient fault: every redelivery re-throws the same
+ * `NotFoundError`, and because the sync queues carry `MessageGroupId=accountId`
+ * that permanently-failing head message stalls the whole account's per-group
+ * FIFO. Handlers use this predicate to resolve such an event terminally (ack
+ * with a WARN) instead of retrying forever (issues #287, #289, #290).
+ *
+ * The guard is narrow on purpose: only a genuine not-found terminates. Real
+ * IMAP/infra failures carry other errors and must still propagate to be retried.
+ */
+export const isNotFoundError = (error: unknown): boolean =>
+	(error as { name?: string })?.name === "NotFoundError";