@remit/imap-worker 0.0.60 → 0.0.62

package/package.json

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

package/src/filter-config.test.ts

@@ -15,6 +15,7 @@ import {
 	type PlacementMoveService,
 } from "@remit/mailbox-service";
 import { buildFilterConfig, type FilterConfigDeps } from "./filter-config.js";
+import { _resetMessageEmbedderForTest } from "./message-embedder.js";
 
 const anchorOnlyFilter = (destinationMailboxId: string): FilterItem =>
 	({
@@ -117,3 +118,54 @@ describe("buildFilterConfig", () => {
 		assert.equal(decision.move, undefined);
 	});
 });
+
+// An instance with semantic search off (issue #1068). `off` selects an embedder
+// that throws by design, and the throw lands in the pipeline's per-filter catch:
+// one error-level `filter_anchor_match_failed` for every semantic filter on
+// every message it syncs. The pipeline already has a designed skip for a
+// missing embedder, so the config passes none.
+describe("buildFilterConfig with semantic search off", () => {
+	const withProviderOff = async (body: () => Promise<void>): Promise<void> => {
+		const previous = process.env.SEARCH_EMBEDDING_PROVIDER;
+		process.env.SEARCH_EMBEDDING_PROVIDER = "off";
+		_resetMessageEmbedderForTest();
+		try {
+			await body();
+		} finally {
+			if (previous === undefined) {
+				delete process.env.SEARCH_EMBEDDING_PROVIDER;
+			} else {
+				process.env.SEARCH_EMBEDDING_PROVIDER = previous;
+			}
+			_resetMessageEmbedderForTest();
+		}
+	};
+
+	it("wires no embedder", async () => {
+		await withProviderOff(async () => {
+			const config = buildFilterConfig(repos(anchorOnlyFilter("mbx-archive")));
+
+			assert.ok(config);
+			assert.equal(config.embedder, undefined);
+		});
+	});
+
+	it("skips the semantic filter without logging an error", async () => {
+		await withProviderOff(async () => {
+			const config = buildFilterConfig(repos(anchorOnlyFilter("mbx-archive")));
+			assert.ok(config);
+
+			const errors: unknown[] = [];
+			const decision = await new FilterPipeline(config, {
+				info: () => {},
+				debug: () => {},
+				warn: () => {},
+				error: (fields) => errors.push(fields.alert),
+			}).evaluate("cfg-1", "m-off", message);
+
+			assert.deepEqual(decision.labels, []);
+			assert.equal(decision.move, undefined);
+			assert.deepEqual(errors, []);
+		});
+	});
+});

package/src/filter-config.ts

@@ -8,6 +8,10 @@ import type {
 	MessageEmbedder,
 	PlacementMoveService,
 } from "@remit/mailbox-service";
+import {
+	EMBEDDING_PROVIDER_OFF,
+	readEmbeddingProviderFromEnv,
+} from "@remit/search-service/from-env";
 import { getMessageEmbedder } from "./message-embedder.js";
 
 export interface FilterConfigDeps {
@@ -17,6 +21,21 @@ export interface FilterConfigDeps {
 	placementMoveService?: PlacementMoveService;
 }
 
+/**
+ * The env-selected embedder, or none on an instance with semantic search off.
+ *
+ * `off` embeds nothing by design, and its embedder says so by throwing
+ * (EmbeddingDisabledError). The pipeline has a designed skip for a *missing*
+ * embedder — semantic filters are passed over and logged at debug — but a
+ * present embedder that throws lands in the per-filter catch instead, which is
+ * an error-level `filter_anchor_match_failed` for every semantic filter on
+ * every synced message. Same outcome, a log nobody can read.
+ */
+const embedderFromEnv = (): MessageEmbedder | undefined =>
+	readEmbeddingProviderFromEnv() === EMBEDDING_PROVIDER_OFF
+		? undefined
+		: getMessageEmbedder();
+
 /**
  * Assemble the index-time filter config the body-sync pass runs (RFC 034). The
  * embedder is provisioned from env exactly as the backend read-path and
@@ -33,11 +52,12 @@ export const buildFilterConfig = (
 ): FilterConfig | undefined => {
 	const { placementMoveService } = deps;
 	if (!placementMoveService) return undefined;
+	const resolved = embedder ?? embedderFromEnv();
 	return {
 		filterService: deps.filterService,
 		filterAnchorService: deps.filterAnchorService,
 		messageLabelService: deps.messageLabelService,
 		placementMoveService,
-		embedder: embedder ?? getMessageEmbedder(),
+		...(resolved ? { embedder: resolved } : {}),
 	};
 };

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

@@ -28,9 +28,19 @@ interface Connection {
 		uids: number[],
 		dest: string,
 	) => Promise<{ uidMap: Map<number, number> }>;
+	search: (criteria: unknown[]) => Promise<number[]>;
 	createMailbox: (path: string) => Promise<void>;
 }
 
+interface CopyRow {
+	messageId: string;
+	mailboxId: string;
+	uid: number;
+	status: string;
+	syncStatus: string;
+	messageIdHeader?: string;
+}
+
 interface Harness {
 	calls: Call[];
 	account: {
@@ -40,6 +50,8 @@ interface Harness {
 	} | null;
 	mailbox: { mailboxId: string; uidValidity: number; cursorState?: string };
 	mailboxError?: Error;
+	copyRow: CopyRow | null;
+	destinationHolds: number[];
 	connection: Connection;
 	getConnectionCount: number;
 	disconnectCount: number;
@@ -59,15 +71,36 @@ const record =
 	};
 
 const buildConnection = (): Connection => ({
-	openBox: async () => ({ uidvalidity: 1 }),
-	copyMessages: async () => ({ uidMap: new Map([[10, 20]]) }),
+	openBox: async (path: string, readOnly?: boolean) => {
+		h.calls.push({ method: "openBox", args: [path, readOnly] });
+		return { uidvalidity: 1 };
+	},
+	copyMessages: async (uids: number[], dest: string) => {
+		h.calls.push({ method: "copyMessages", args: [uids, dest] });
+		return { uidMap: new Map([[10, 20]]) };
+	},
+	search: async (criteria: unknown[]) => {
+		h.calls.push({ method: "search", args: criteria });
+		return h.destinationHolds;
+	},
 	createMailbox: record("createMailbox") as Connection["createMailbox"],
 });
 
+const unsettledCopyRow = (): CopyRow => ({
+	messageId: "new-msg",
+	mailboxId: "dst-mbx",
+	uid: 0,
+	status: "moving",
+	syncStatus: "pending",
+	messageIdHeader: "<abc@example.com>",
+});
+
 const fresh = (): Harness => ({
 	calls: [],
 	account: { accountId: "acc-1", accountConfigId: "cfg-1" },
 	mailbox: { mailboxId: "src-mbx", uidValidity: 1, cursorState: undefined },
+	copyRow: unsettledCopyRow(),
+	destinationHolds: [],
 	connection: buildConnection(),
 	getConnectionCount: 0,
 	disconnectCount: 0,
@@ -83,8 +116,13 @@ const deps = (): MessageCopyDeps =>
 				},
 			},
 			message: {
+				get: async (messageIds: string[]) => {
+					h.calls.push({ method: "message.get", args: [messageIds] });
+					return h.copyRow ? [h.copyRow] : [];
+				},
 				updateUid: record("message.updateUid"),
 				update: record("message.update"),
+				delete: record("message.delete"),
 			},
 			threadMessage: {
 				findByMessageId: async (cfg: string) => ({
@@ -97,6 +135,10 @@ const deps = (): MessageCopyDeps =>
 					hasStars: false,
 					hasAttachment: false,
 				}),
+				findAllByMessageId: async (cfg: string) => [
+					{ accountConfigId: cfg, threadMessageId: "tm-1" },
+				],
+				deleteMany: record("threadMessage.deleteMany"),
 				update: record("threadMessage.update"),
 			},
 			mailbox: {
@@ -141,13 +183,17 @@ const event: MessageCopyEvent = {
 const called = (method: string): Call[] =>
 	h.calls.filter((c) => c.method === method);
 
+const askedTheDestination = (): boolean =>
+	called("search").length > 0 &&
+	called("openBox").some((c) => c.args[0] === "Archive");
+
 describe("handleMessageCopy", () => {
 	beforeEach(() => {
 		h = fresh();
 	});
 
 	it("writes the new UID, marks the copy synced, and updates the thread row", async () => {
-		await handleMessageCopy(event, noopLog, deps());
+		await handleMessageCopy(event, noopLog, 1, deps());
 
 		assert.deepEqual(called("message.updateUid")[0]?.args, [
 			"new-msg",
@@ -163,18 +209,114 @@ describe("handleMessageCopy", () => {
 		assert.equal(h.disconnectCount, 1, "the scope is always disconnected");
 	});
 
-	it("marks the copy failed when the COPYUID response omits the source uid", async () => {
+	it("settles on the destination UID when a server without UIDPLUS omits COPYUID", async () => {
+		h.connection.copyMessages = async () => ({ uidMap: new Map() });
+		h.destinationHolds = [42];
+
+		await handleMessageCopy(event, noopLog, 1, deps());
+
+		assert.ok(askedTheDestination(), "the destination was asked for the copy");
+		assert.deepEqual(called("message.updateUid")[0]?.args, [
+			"new-msg",
+			42,
+			"dst-mbx",
+		]);
+		assert.equal(
+			(called("message.update")[0]?.args[1] as { syncStatus?: string })
+				?.syncStatus,
+			"synced",
+		);
+		assert.equal(called("threadMessage.update").length, 1);
+	});
+
+	it("reconciles the optimistic row away when the destination does not hold the copy", async () => {
 		h.connection.copyMessages = async () => ({ uidMap: new Map() });
+		h.destinationHolds = [];
 
-		await handleMessageCopy(event, noopLog, deps());
+		await handleMessageCopy(event, noopLog, 1, deps());
 
+		assert.ok(askedTheDestination());
+		assert.equal(called("message.delete")[0]?.args[0], "new-msg");
+		assert.equal(called("threadMessage.deleteMany").length, 1);
 		assert.equal(called("message.updateUid").length, 0);
+	});
+
+	it("settles a copy it cannot probe instead of retrying it into duplicates", async () => {
+		let copies = 0;
+		h.connection.copyMessages = async () => {
+			copies += 1;
+			return { uidMap: new Map() };
+		};
+		h.copyRow = { ...unsettledCopyRow(), messageIdHeader: undefined };
+
+		await handleMessageCopy(event, noopLog, 1, deps());
+
+		assert.equal(copies, 1, "the COPY is issued once");
+		assert.equal(called("search").length, 0, "there is nothing to ask with");
 		const update = called("message.update")[0];
+		assert.equal((update?.args[1] as { status?: string })?.status, "deleted");
 		assert.equal(
 			(update?.args[1] as { syncStatus?: string })?.syncStatus,
 			"failed",
 		);
-		assert.equal(called("threadMessage.update").length, 0);
+		assert.equal(called("message.delete").length, 0, "no row is thrown away");
+	});
+
+	it("never copies twice when a redelivered copy already landed", async () => {
+		h.destinationHolds = [42];
+
+		await handleMessageCopy(event, noopLog, 2, deps());
+
+		assert.equal(called("copyMessages").length, 0);
+		assert.deepEqual(called("message.updateUid")[0]?.args, [
+			"new-msg",
+			42,
+			"dst-mbx",
+		]);
+	});
+
+	it("never copies twice when a redelivered copy cannot be probed", async () => {
+		h.copyRow = { ...unsettledCopyRow(), messageIdHeader: undefined };
+		let copies = 0;
+		h.connection.copyMessages = async () => {
+			copies += 1;
+			// The COPY lands, then the tagged OK is lost with the connection.
+			throw new Error("connection reset by peer");
+		};
+
+		await assert.rejects(
+			handleMessageCopy(event, noopLog, 1, deps()),
+			/connection reset/,
+		);
+		await handleMessageCopy(event, noopLog, 2, deps());
+
+		assert.equal(copies, 1, "the redelivery issues no second COPY");
+		assert.equal(called("search").length, 0);
+		const settled = called("message.update").at(-1);
+		assert.equal((settled?.args[1] as { status?: string })?.status, "deleted");
+	});
+
+	it("acks a copy that already settled without touching IMAP", async () => {
+		h.copyRow = {
+			...unsettledCopyRow(),
+			uid: 20,
+			status: "active",
+			syncStatus: "synced",
+		};
+
+		await handleMessageCopy(event, noopLog, 2, deps());
+
+		assert.equal(h.getConnectionCount, 0);
+		assert.equal(called("copyMessages").length, 0);
+	});
+
+	it("acks when the copy row no longer exists", async () => {
+		h.copyRow = null;
+
+		await handleMessageCopy(event, noopLog, 1, deps());
+
+		assert.equal(h.getConnectionCount, 0);
+		assert.equal(called("message.update").length, 0);
 	});
 
 	it("returns early without connecting when the account is soft-deleted", async () => {
@@ -184,7 +326,7 @@ describe("handleMessageCopy", () => {
 			deletedAt: Date.now(),
 		};
 
-		await handleMessageCopy(event, noopLog, deps());
+		await handleMessageCopy(event, noopLog, 1, deps());
 
 		assert.equal(h.getConnectionCount, 0);
 	});
@@ -193,7 +335,7 @@ describe("handleMessageCopy", () => {
 		h.account = null;
 
 		await assert.rejects(
-			handleMessageCopy(event, noopLog, deps()),
+			handleMessageCopy(event, noopLog, 1, deps()),
 			/not found/,
 		);
 	});
@@ -201,7 +343,7 @@ describe("handleMessageCopy", () => {
 	it("acks terminally without connecting when the source mailbox was deleted", async () => {
 		h.mailboxError = notFoundError();
 
-		await handleMessageCopy(event, noopLog, deps());
+		await handleMessageCopy(event, noopLog, 1, deps());
 
 		assert.equal(h.getConnectionCount, 0);
 		assert.equal(called("message.updateUid").length, 0);
@@ -215,7 +357,7 @@ describe("handleMessageCopy", () => {
 			cursorState: "rebuilding",
 		};
 
-		await handleMessageCopy(event, noopLog, deps());
+		await handleMessageCopy(event, noopLog, 1, deps());
 
 		assert.equal(h.getConnectionCount, 0);
 		assert.equal(called("message.updateUid").length, 0);
@@ -224,7 +366,7 @@ describe("handleMessageCopy", () => {
 	it("pauses quietly when openBox trips a UIDVALIDITY mismatch", async () => {
 		h.connection.openBox = async () => ({ uidvalidity: 999 });
 
-		await handleMessageCopy(event, noopLog, deps());
+		await handleMessageCopy(event, noopLog, 1, deps());
 
 		assert.equal(
 			(called("mailbox.update")[0]?.args[2] as { cursorState?: string })
@@ -242,7 +384,7 @@ describe("handleMessageCopy", () => {
 		};
 
 		await assert.rejects(
-			handleMessageCopy(event, noopLog, deps()),
+			handleMessageCopy(event, noopLog, 1, deps()),
 			/TRYCREATE/,
 		);
 
@@ -255,20 +397,20 @@ describe("handleMessageCopy", () => {
 			throw new Error("NONEXISTENT source message");
 		};
 
-		await handleMessageCopy(event, noopLog, deps());
+		await handleMessageCopy(event, noopLog, 1, deps());
 
 		const update = called("message.update")[0];
 		assert.equal((update?.args[1] as { status?: string })?.status, "deleted");
 		assert.equal(called("createMailbox").length, 0);
 	});
 
-	it("marks failed and rethrows on an unclassified IMAP error", async () => {
+	it("marks failed and rethrows on an unclassified IMAP error within the budget", async () => {
 		h.connection.copyMessages = async () => {
 			throw new Error("server exploded");
 		};
 
 		await assert.rejects(
-			handleMessageCopy(event, noopLog, deps()),
+			handleMessageCopy(event, noopLog, 1, deps()),
 			/server exploded/,
 		);
 
@@ -278,4 +420,36 @@ describe("handleMessageCopy", () => {
 			"failed",
 		);
 	});
+
+	it("settles on the destination UID instead of dead-lettering the last attempt", async () => {
+		h.connection.copyMessages = async () => {
+			throw new Error("server exploded");
+		};
+		let asked = 0;
+		h.connection.search = async (criteria: unknown[]) => {
+			h.calls.push({ method: "search", args: criteria });
+			asked += 1;
+			return asked === 1 ? [] : [42];
+		};
+
+		await handleMessageCopy(event, noopLog, 3, deps());
+
+		assert.deepEqual(called("message.updateUid")[0]?.args, [
+			"new-msg",
+			42,
+			"dst-mbx",
+		]);
+	});
+
+	it("reconciles the row away when the last attempt finds nothing at the destination", async () => {
+		h.connection.copyMessages = async () => {
+			throw new Error("server exploded");
+		};
+		h.destinationHolds = [];
+
+		await handleMessageCopy(event, noopLog, 3, deps());
+
+		assert.equal(called("message.delete")[0]?.args[0], "new-msg");
+		assert.equal(called("threadMessage.deleteMany").length, 1);
+	});
 });

package/src/handlers/message-copy.ts

@@ -3,8 +3,11 @@ import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
 import type { Logger } from "@remit/logger-lambda";
 import {
 	guardConnectionCursor,
+	type IImapConnection,
 	isCursorRebuildNeeded,
+	isPlacementUnsettled,
 	MailboxCursorPausedError,
+	reconcileStaleMessage,
 } from "@remit/mailbox-service";
 import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
@@ -12,6 +15,7 @@ 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";
+import { searchMailboxByMessageId } from "./message-move.js";
 
 export interface MessageCopyDeps {
 	getClient: typeof getClient;
@@ -27,13 +31,65 @@ const defaultDeps: MessageCopyDeps = {
 	createConnectionScope: createConnectionScopeWithCredentials,
 };
 
+/**
+ * Fallback when `MESSAGE_COPY_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
+ * `MESSAGE_MOVE_MAX_ATTEMPTS`.
+ */
+const DEFAULT_MESSAGE_COPY_MAX_ATTEMPTS = 3;
+
+export const getMessageCopyMaxAttempts = (
+	processEnv: NodeJS.ProcessEnv = process.env,
+): number => {
+	const raw = processEnv.MESSAGE_COPY_MAX_ATTEMPTS;
+	if (!raw) return DEFAULT_MESSAGE_COPY_MAX_ATTEMPTS;
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isFinite(parsed) && parsed > 0
+		? parsed
+		: DEFAULT_MESSAGE_COPY_MAX_ATTEMPTS;
+};
+
+export const MESSAGE_COPY_MAX_ATTEMPTS = getMessageCopyMaxAttempts();
+
+/**
+ * Where the destination says this copy is. `unprobeable` is the row that
+ * carries no Message-ID header (`messageIdHeader` is optional on Message, and
+ * drafts and automated senders do arrive without one): the server was never
+ * asked, so its silence says nothing.
+ */
+export type CopyProbe =
+	| { kind: "confirmed"; uid: number }
+	| { kind: "absent" }
+	| { kind: "unprobeable" };
+
 /**
  * Handle MESSAGE_COPY events.
  * Executes IMAP COPY command and updates local state with new UID.
+ *
+ * IMAP COPY is not idempotent and the message queue is FIFO per account, so
+ * this handler never manufactures a retry to resolve an ambiguous answer: a
+ * second COPY duplicates the mail, and a record that keeps coming back blocks
+ * every later move, copy and delete for that account (issues #287, #289,
+ * #290). Ambiguity is resolved in place, by asking the destination.
+ *
+ * A fault the server threw is still retried up to
+ * {@link MESSAGE_COPY_MAX_ATTEMPTS}, because it may be a dropped connection.
+ * Two guards make that safe: a redelivery asks the destination BEFORE issuing
+ * COPY again, and the last attempt settles the row instead of dead-lettering
+ * it. The copy row is a reconcile-model dependent (`copySettledMessage` writes
+ * its ThreadMessage row at `uid: 0` before the server has confirmed anything,
+ * docs/architecture/imap-mutations.md R2) and these terminal settles are its
+ * reconciliation path: every verdict the server gives an answer for settles the
+ * row out of `uid: 0`/`moving` (#1097). A server that cannot be reached at all
+ * gives no verdict — the record dead-letters with the row untouched, the same
+ * caveat `resolveExhaustedMessageMoveFailure` carries, because absence is only
+ * ever concluded from an answer.
  */
 export const handleMessageCopy = async (
 	event: MessageCopyEvent,
 	log: Logger,
+	receiveCount = 1,
 	deps: MessageCopyDeps = defaultDeps,
 ): Promise<void> => {
 	const {
@@ -83,6 +139,29 @@ export const handleMessageCopy = async (
 		return;
 	}
 
+	const [copyRow] = await messageService.get([newMessageId]);
+
+	// The copy row is already gone — a reconciliation path settled it. Nothing
+	// left to bind a UID to; ack.
+	if (!copyRow) {
+		log.warn(
+			{ accountId, sourceMessageId, newMessageId },
+			"Skipping MESSAGE_COPY: copy row no longer exists",
+		);
+		return;
+	}
+
+	// This copy already settled — `updateUid` cleared `status: moving` when the
+	// server confirmed it. A redelivery reaching here would COPY the message a
+	// second time, and COPY has no source-side effect to make that a no-op.
+	if (!isPlacementUnsettled(copyRow)) {
+		log.info(
+			{ accountId, newMessageId, uid: copyRow.uid, status: copyRow.status },
+			"Skipping MESSAGE_COPY: the copy already settled against confirmed IMAP state",
+		);
+		return;
+	}
+
 	await withOAuthLifecycle(
 		buildLifecycleDeps(secrets, accountService),
 		account,
@@ -118,6 +197,131 @@ export const handleMessageCopy = async (
 				return;
 			}
 
+			// The copy row carries the source's Message-ID header, so the
+			// destination can be asked where this copy is. Always on the UNGUARDED
+			// handle: a `guardConnectionCursor` wrap is bound to the SOURCE mailbox
+			// snapshot alone, and opening the destination through it trips that
+			// mailbox into a rebuild.
+			const probeDestination = async (
+				connection: IImapConnection,
+			): Promise<CopyProbe> => {
+				if (!copyRow.messageIdHeader) return { kind: "unprobeable" };
+				const probedUid = await searchMailboxByMessageId(
+					connection,
+					destinationMailboxPath,
+					copyRow.messageIdHeader,
+				);
+				return probedUid === null
+					? { kind: "absent" }
+					: { kind: "confirmed", uid: probedUid };
+			};
+
+			const settleCopied = async (newUid: number): Promise<void> => {
+				await messageService.updateUid(
+					newMessageId,
+					newUid,
+					destinationMailboxId,
+				);
+
+				await messageService.update(newMessageId, {
+					status: MessageStatus.active,
+					syncStatus: MessageSyncStatus.synced,
+				});
+
+				const threadMessage = await threadMessageService.findByMessageId(
+					account.accountConfigId,
+					newMessageId,
+				);
+				if (threadMessage) {
+					await threadMessageService.update(
+						threadMessage.accountConfigId,
+						threadMessage.threadMessageId,
+						{ uid: newUid },
+						{
+							composites: {
+								sentDate: threadMessage.sentDate,
+								mailboxId: threadMessage.mailboxId,
+								isRead: threadMessage.isRead,
+								isDeleted: threadMessage.isDeleted,
+								hasStars: threadMessage.hasStars,
+								hasAttachment: threadMessage.hasAttachment,
+							},
+						},
+					);
+				}
+
+				log.info(
+					{
+						sourceMessageId,
+						newMessageId,
+						oldUid: uid,
+						newUid,
+						destination: destinationMailboxPath,
+					},
+					"Message copied successfully",
+				);
+			};
+
+			// The destination answered that it does not hold this message, so the
+			// copy never landed and the optimistic row records something the server
+			// does not have. Deleting it (with its ThreadMessage rows) is the exact
+			// reality, the same terminal outcome `resolveExhaustedMessageMoveFailure`
+			// calls `reconciled`. Routine: metric, no alarm.
+			const settleNeverLanded = async (reason: string): Promise<void> => {
+				const { threadMessagesDeleted } = await reconcileStaleMessage(
+					{ messageService, threadMessageService },
+					account.accountConfigId,
+					newMessageId,
+				);
+				log.info(
+					{
+						metric: "message_copy_not_landed",
+						accountId,
+						sourceMessageId,
+						newMessageId,
+						destination: destinationMailboxPath,
+						threadMessagesDeleted,
+						reason,
+					},
+					"Copy absent from its destination; optimistic copy row reconciled away",
+				);
+			};
+
+			// The server never answered where the copy is, so nothing here may
+			// delete a row that might describe real mail. The row is settled out of
+			// `moving` instead — `status: deleted` is the state this handler already
+			// writes for a copy that will not happen, and it keeps `holdsCopyOf`
+			// answering true so a sighting at the destination cannot drag the SOURCE
+			// row out of the folder it was copied from.
+			//
+			// The cost, paid deliberately: if that COPY did land, this row is the
+			// only one the copy will ever have — `holdsCopyOf` tests row existence
+			// alone (`message-sync.ts`), so no sync creates a second one — and
+			// `deleted` hides it. Real mail then sits at the destination on the
+			// server and invisible in the product until an operator acts on the
+			// alert. `settleNeverLanded` has the opposite property: it deletes only
+			// what the server denied holding, and a later sync re-projects anything
+			// that turns out to be there. Silence buys the safer half of one pair
+			// and the worse half of the other.
+			const settleBroken = async (reason: string): Promise<void> => {
+				await messageService.update(newMessageId, {
+					status: MessageStatus.deleted,
+					syncStatus: MessageSyncStatus.failed,
+				});
+				log.error(
+					{
+						alert: "message_copy_unconfirmed",
+						accountId,
+						sourceMessageId,
+						newMessageId,
+						uid,
+						destination: destinationMailboxPath,
+						reason,
+					},
+					"Copy could not be bound to a destination UID; row settled failed for operator investigation",
+				);
+			};
+
 			const scope = createConnectionScopeWithCredentials(account, credentials);
 
 			await scope
@@ -132,6 +336,27 @@ export const handleMessageCopy = async (
 						accountId,
 						mailbox,
 					);
+
+					// A redelivery means the previous attempt threw, which does not
+					// mean its COPY failed — the tagged OK can be lost with the
+					// connection. Ask before copying again, or the retry is what
+					// duplicates the mail. `absent` is an answer the server gave, so
+					// copying again is safe; `unprobeable` is silence, and copying on
+					// silence is the duplicate this guard exists to prevent.
+					if (receiveCount > 1) {
+						const earlier = await probeDestination(rawConnection);
+						if (earlier.kind === "confirmed") {
+							await settleCopied(earlier.uid);
+							return;
+						}
+						if (earlier.kind === "unprobeable") {
+							await settleBroken(
+								"redelivered with no Message-ID to ask the destination with",
+							);
+							return;
+						}
+					}
+
 					// Open source mailbox (read-only is fine for COPY)
 					await connection.openBox(sourceMailboxPath, true);
 
@@ -141,66 +366,30 @@ export const handleMessageCopy = async (
 						destinationMailboxPath,
 					);
 
-					// Get new UID from COPYUID response
-					const newUid = result.uidMap.get(uid);
-
-					if (newUid) {
-						// Update the new message with the actual UID
-						await messageService.updateUid(
-							newMessageId,
-							newUid,
-							destinationMailboxId,
-						);
-
-						// Update message status to active
-						await messageService.update(newMessageId, {
-							status: MessageStatus.active,
-							syncStatus: MessageSyncStatus.synced,
-						});
-
-						// Update ThreadMessage UID
-						const threadMessage = await threadMessageService.findByMessageId(
-							account.accountConfigId,
-							newMessageId,
-						);
-						if (threadMessage) {
-							await threadMessageService.update(
-								threadMessage.accountConfigId,
-								threadMessage.threadMessageId,
-								{ uid: newUid },
-								{
-									composites: {
-										sentDate: threadMessage.sentDate,
-										mailboxId: threadMessage.mailboxId,
-										isRead: threadMessage.isRead,
-										isDeleted: threadMessage.isDeleted,
-										hasStars: threadMessage.hasStars,
-										hasAttachment: threadMessage.hasAttachment,
-									},
-								},
-							);
-						}
+					const copiedUid = result.uidMap.get(uid);
+					if (copiedUid) {
+						await settleCopied(copiedUid);
+						return;
+					}
 
-						log.info(
-							{
-								sourceMessageId,
-								newMessageId,
-								oldUid: uid,
-								newUid,
-								destination: destinationMailboxPath,
-							},
-							"Message copied successfully",
-						);
-					} else {
-						// Source message may have been deleted on server
-						log.error(
-							{ sourceMessageId, uid },
-							"Source message not found in COPYUID response - may have been deleted",
+					// A server without UIDPLUS answers a perfectly successful COPY
+					// with no COPYUID entry, so an empty map is UNCONFIRMED, never
+					// evidence the server matched nothing (#1097). The destination is
+					// asked before any verdict, as `message-move.ts` does (#912, #979).
+					const probe = await probeDestination(rawConnection);
+					if (probe.kind === "confirmed") {
+						await settleCopied(probe.uid);
+						return;
+					}
+					if (probe.kind === "absent") {
+						await settleNeverLanded(
+							"no COPYUID entry, absent from destination",
 						);
-						await messageService.update(newMessageId, {
-							syncStatus: MessageSyncStatus.failed,
-						});
+						return;
 					}
+					await settleBroken(
+						"no COPYUID entry and no Message-ID to probe with",
+					);
 				})
 				.catch(async (error: unknown) => {
 					if (error instanceof MailboxCursorPausedError) {
@@ -227,7 +416,10 @@ export const handleMessageCopy = 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, as the
+						// move path does: the destination now exists, so the record is
+						// worth redriving from the DLQ.
 						throw error;
 					}
 
@@ -247,11 +439,33 @@ export const handleMessageCopy = async (
 						return;
 					}
 
-					// Mark as failed for other errors
-					await messageService.update(newMessageId, {
-						syncStatus: MessageSyncStatus.failed,
-					});
-					throw error;
+					if (receiveCount < MESSAGE_COPY_MAX_ATTEMPTS) {
+						// Transient copy failure — expected (connections drop). Queue
+						// redelivery retries, and the probe above keeps the retry from
+						// copying the message twice.
+						await messageService.update(newMessageId, {
+							syncStatus: MessageSyncStatus.failed,
+						});
+						throw error;
+					}
+
+					// Redelivery budget exhausted. Dead-lettering here would leave the
+					// row at `uid: 0`/`moving` with nothing left to settle it and the
+					// account's FIFO group still holding the record, so the row is
+					// resolved into one terminal outcome instead — never by inferring
+					// the server's state from our own failures. A server that cannot be
+					// reached reaches no verdict: the probe throws and the record
+					// dead-letters with the row untouched.
+					const probe = await probeDestination(await scope.getConnection());
+					if (probe.kind === "confirmed") {
+						await settleCopied(probe.uid);
+						return;
+					}
+					if (probe.kind === "absent") {
+						await settleNeverLanded(`retry exhausted: ${errorMessage}`);
+						return;
+					}
+					await settleBroken(`retry exhausted: ${errorMessage}`);
 				})
 				.finally(() => scope.disconnect());
 		},

package/src/processor.ts

@@ -19,7 +19,8 @@ export const processEvent = async (
 	/**
 	 * 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,
-	 * APPEND_SENT_MESSAGE and MESSAGE_MOVE — each knows from it when this is
+	 * APPEND_SENT_MESSAGE, MESSAGE_MOVE, MESSAGE_DELETE and MESSAGE_COPY — 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.
@@ -46,7 +47,7 @@ export const processEvent = async (
 		case "FLAG_PUSH":
 			return handleFlagPush(event, log, receiveCount);
 		case "MESSAGE_COPY":
-			return handleMessageCopy(event, log);
+			return handleMessageCopy(event, log, receiveCount);
 		case "EMPTY_TRASH":
 			return handleEmptyTrash(event, log);
 		case "APPEND_SENT_MESSAGE":