@remit/imap-worker 0.0.90 → 0.0.91

package/dist/handlers/placement-move-push.js

@@ -0,0 +1,307 @@
+import { MessageMutation, MessageSyncStatus } from "@remit/domain-enums";
+import { guardConnectionCursor, isCursorRebuildNeeded, isMessageGoneFromOpenMailbox, MailboxCursorPausedError, resolveExhaustedPlacementMoveFailure, restoreSourcePlacement, } from "@remit/mailbox-service";
+import { isAccountDeleted } from "../account-check.js";
+import { emitFrom } from "../emit.js";
+import { findMailboxRow } from "../mailbox-row.js";
+import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+import { buildThreadMessageMoveUpdate, emitMailboxResync, emitMoveResync, searchMailboxForHighestMessageIdUid, } from "./message-move.js";
+import { probeableMessageIdHeader } from "./probe-message-id.js";
+/**
+ * Attempt the IMAP MOVE.
+ *
+ * Takes two connection handles rather than one: `sourceConnection` and
+ * `destinationConnection` wrap the SAME underlying connection but are each
+ * cursor-guarded (#1272) against their OWN mailbox — a `guardConnectionCursor`
+ * wrap binds `openBox` checks to whichever ONE mailbox snapshot it was built
+ * with, so verifying at the destination must never run through the source's
+ * guard (it would compare the destination's served UIDVALIDITY against the
+ * source's stored one and misfire).
+ *
+ * - `moved` with a `newUid` — confirmed, either via COPYUID or (see below)
+ *   an explicit destination verification.
+ * - `trycreate` — the destination mailbox doesn't exist yet; the caller
+ *   creates it and retries.
+ * - `not-found` — confirmed absent from BOTH source and destination. Only
+ *   this outcome supersedes the pending-move marker (drops it, reconciles
+ *   the row as an external delete).
+ * - Any other case throws (propagates for SQS retry, or as
+ *   `MailboxCursorPausedError` for the caller's cursor-pause handling) —
+ *   including an UNCONFIRMED move (no COPYUID, or an explicit "not
+ *   found"/NONEXISTENT from the server) whose message is still sitting at
+ *   the source. A MOVE that resolves without a uidMap entry on a
+ *   non-UIDPLUS server is a plausible SUCCESS, not evidence the message is
+ *   gone (PR #1289 review finding 2) — deleting the local row on that
+ *   ambiguity would be data loss. `not-found` is only returned once BOTH a
+ *   destination Message-ID search (when the header is known) misses AND
+ *   {@link isMessageGoneFromOpenMailbox} confirms the message absent from the
+ *   source — a FETCH returning no row does not, on its own, confirm anything.
+ */
+export const attemptMove = async (sourceConnection, destinationConnection, sourceMailboxPath, destinationMailboxPath, uid, messageIdHeader) => {
+    await sourceConnection.openBox(sourceMailboxPath, false);
+    const resolved = await sourceConnection
+        .moveMessages([uid], destinationMailboxPath)
+        .then((result) => ({ ok: true, newUid: result.uidMap.get(uid) }))
+        .catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("TRYCREATE")) {
+            return { ok: false, trycreate: true };
+        }
+        if (message.includes("not found") || message.includes("NONEXISTENT")) {
+            return { ok: false, trycreate: false };
+        }
+        throw error;
+    });
+    if (resolved.ok && resolved.newUid) {
+        return { kind: "moved", newUid: resolved.newUid };
+    }
+    if (!resolved.ok && resolved.trycreate) {
+        return { kind: "trycreate" };
+    }
+    // Unconfirmed: either no COPYUID entry, or the server explicitly claimed
+    // "not found" — never trust either without independent verification. A
+    // message this MOVE delivered is the newest copy of that Message-ID at the
+    // destination, so the probe binds to the highest matching uid (#1122).
+    // Unlike `confirmTrashMoveUid`, this probe is ungated: where the MOVE never
+    // ran and an older copy filed there earlier is the only match, the marker
+    // binds to that unrelated mail. Pre-existing, and not narrowed by taking the
+    // highest — the source is not asked first here, so nothing rules the case
+    // out.
+    if (messageIdHeader) {
+        const destinationUid = await searchMailboxForHighestMessageIdUid(destinationConnection, destinationMailboxPath, messageIdHeader);
+        if (destinationUid)
+            return { kind: "moved", newUid: destinationUid };
+    }
+    await sourceConnection.openBox(sourceMailboxPath, true);
+    if (!(await isMessageGoneFromOpenMailbox(sourceConnection, uid))) {
+        throw new Error("Placement move unresolved (unconfirmed at destination, still present at source) — retrying");
+    }
+    return { kind: "not-found" };
+};
+/**
+ * Handle PLACEMENT_MOVE_PUSH events (issue #1271, epic #1281). Drains ONE
+ * pending placement-move marker: resolves the UID fresh from the Message row
+ * (never trusts a captured value — invariant 1), pushes the IMAP MOVE, and
+ * clears the marker ONLY on confirmed success. Every precedence rule (epic
+ * invariant 2) is enforced here:
+ * - Pending Remit move wins on location: nothing in this handler ever
+ *   corrects `message.mailboxId` back toward the source — a resync elsewhere
+ *   (message-sync.ts) never overwrites an existing row's `mailboxId` either
+ *   (create-only-if-not-exists semantics), so the local move is never undone.
+ * - A NEWER local action superseding this marker (drop without pushing) —
+ *   see the `message.mailboxId !== marker.destinationMailboxId` check below.
+ * - An external delete supersedes the marker entirely — the `not-found`
+ *   outcome drops the marker and reconciles the stale row.
+ *
+ * Cursor-guarded (#1272, epic #1281 invariant 5): both the source and
+ * destination mailbox are checked for a non-`normal` `cursorState` before
+ * connecting, and the connection is wrapped per-mailbox via
+ * `guardConnectionCursor` so no stored UID touches the server while either
+ * mailbox's axis is being rebuilt. A trip pauses the push (routine, no
+ * alarm) — the marker stays durable and pushes again on the next event.
+ */
+export const handlePlacementMovePush = async (event, ctx, receiveCount) => {
+    const { log, pool, metrics, config } = ctx;
+    const emit = emitFrom(ctx);
+    const { account: accountService, mailbox: mailboxService, message: messageService, threadMessage: threadMessageService, placementMove: markerService, secrets, } = ctx.client;
+    const { accountId, accountConfigId, messageId } = event;
+    const marker = await markerService.find(messageId);
+    if (!marker) {
+        log.info({ messageId, accountId }, "No pending placement-move marker (already confirmed or superseded); nothing to push");
+        return;
+    }
+    const account = await accountService.get(accountId);
+    if (!account) {
+        throw new Error(`Account ${accountId} not found`);
+    }
+    if (isAccountDeleted(account, log)) {
+        return;
+    }
+    const message = await messageService.get(messageId);
+    const placementRead = {
+        status: message.status,
+        mailboxId: message.mailboxId,
+        uid: message.uid,
+    };
+    // A newer local action (drag-and-drop move, auto-moved Undo) already
+    // changed the message's location away from what this marker still
+    // promises — that later intent wins locally. Drop the now-stale marker
+    // without touching IMAP.
+    if (message.mailboxId !== marker.destinationMailboxId) {
+        await markerService.delete(messageId);
+        log.info({
+            messageId,
+            accountId,
+            markerDestination: marker.destinationMailboxId,
+            currentMailboxId: message.mailboxId,
+        }, "Placement move superseded by a newer local action; marker dropped without pushing");
+        return;
+    }
+    // The worker has picked up the event and is about to actually attempt the
+    // IMAP MOVE — advance the state engine (pending/queued -> processing).
+    // Idempotent to call again on a redelivered event (a prior attempt that
+    // died mid-flight already left it here).
+    await markerService.updateState(messageId, "processing");
+    // No MOVE has left for this marker, so the row is settled, not just unmarked.
+    const [source, destination] = await Promise.all([
+        findMailboxRow(mailboxService, accountId, marker.sourceMailboxId),
+        findMailboxRow(mailboxService, accountId, marker.destinationMailboxId),
+    ]);
+    if (source.kind === "gone" || destination.kind === "gone") {
+        const context = {
+            alert: "placement_move_mailbox_unreachable",
+            messageId,
+            accountId,
+            sourceMailboxId: marker.sourceMailboxId,
+            destinationMailboxId: marker.destinationMailboxId,
+        };
+        if (source.kind === "gone") {
+            const reconciled = await messageService.deleteIfPlacement(messageId, placementRead);
+            await markerService.delete(messageId);
+            log.error({ ...context, reconciled }, "Placement move not pushed: its source folder is gone; the stale row was reconciled");
+            if (destination.kind === "present") {
+                await emitMailboxResync(emit, {
+                    accountId,
+                    mailboxId: marker.destinationMailboxId,
+                });
+            }
+            return;
+        }
+        await restoreSourcePlacement({ messageService, threadMessageService }, {
+            accountConfigId,
+            messageId,
+            sourceMailboxId: marker.sourceMailboxId,
+            uid: message.uid,
+            syncStatus: MessageSyncStatus.synced,
+            abandonedMutation: MessageMutation.none,
+        });
+        await markerService.delete(messageId);
+        log.error(context, "Placement move not pushed: its destination folder is gone; the row was handed back to its source");
+        await emitMailboxResync(emit, {
+            accountId,
+            mailboxId: marker.sourceMailboxId,
+        });
+        return;
+    }
+    const sourceMailbox = source.mailbox;
+    const destinationMailbox = destination.mailbox;
+    // Cheap frugal skip (epic #1281 invariant 6): either mailbox already known
+    // paused never even borrows a connection. Optimization only — the
+    // guardConnectionCursor wraps below are the structural guarantee (#1272).
+    if (isCursorRebuildNeeded(sourceMailbox.cursorState) ||
+        isCursorRebuildNeeded(destinationMailbox.cursorState)) {
+        log.info({
+            messageId,
+            accountId,
+            sourceCursorState: sourceMailbox.cursorState,
+            destinationCursorState: destinationMailbox.cursorState,
+        }, "Mailbox cursor not normal; pausing outbound placement-move push this round");
+        return;
+    }
+    await withOAuthLifecycle(buildLifecycleDeps(secrets, accountService, ctx.oauth), account, log, async (credentials) => {
+        const scope = pool.borrow(account, credentials);
+        await scope
+            .getConnection()
+            .then(async (rawConnection) => {
+            // Guard at the openBox choke point (epic #1281 invariants 3 & 5).
+            // Two independently-scoped wraps around the SAME connection — see
+            // the attemptMove doc comment for why one guard per mailbox matters.
+            const sourceConnection = guardConnectionCursor(rawConnection, { mailboxService }, accountId, sourceMailbox);
+            const destinationConnection = guardConnectionCursor(rawConnection, { mailboxService }, accountId, destinationMailbox);
+            const outcome = await attemptMove(sourceConnection, destinationConnection, sourceMailbox.fullPath, destinationMailbox.fullPath, message.uid, await probeableMessageIdHeader(threadMessageService, accountConfigId, messageId));
+            if (outcome.kind === "trycreate") {
+                await destinationConnection.createMailbox(destinationMailbox.fullPath);
+                throw new Error(`Destination mailbox ${destinationMailbox.fullPath} did not exist; created, retrying`);
+            }
+            if (outcome.kind === "not-found") {
+                // External delete supersedes the marker entirely (epic invariant 2).
+                await markerService.delete(messageId);
+                const reconciled = await messageService.deleteIfPlacement(messageId, placementRead);
+                log.info({
+                    messageId,
+                    accountId,
+                    uid: message.uid,
+                    sourceMailboxPath: sourceMailbox.fullPath,
+                    reconciled,
+                }, "Message no longer at its pending-move source (external delete or moved away); marker dropped, stale row reconciled");
+                await emitMoveResync(emit, {
+                    accountId,
+                    sourceMailboxId: marker.sourceMailboxId,
+                    destinationMailboxId: marker.destinationMailboxId,
+                });
+                return;
+            }
+            const newUid = outcome.newUid;
+            await messageService.updateUid(messageId, newUid, marker.destinationMailboxId);
+            const threadMessage = await threadMessageService.findByMessageId(accountConfigId, messageId);
+            if (threadMessage) {
+                const args = buildThreadMessageMoveUpdate(threadMessage, newUid, marker.destinationMailboxId);
+                await threadMessageService.update(threadMessage.accountConfigId, threadMessage.threadMessageId, args.set, { composites: args.composites });
+            }
+            // Confirmed IMAP acknowledgement — the "processed" terminal state.
+            // Deleted immediately rather than persisted first (epic invariant
+            // 4: no lingering row once the move is no longer pending) — clears
+            // ONLY here, never on attempt (the defect issue #1271 fixes).
+            await markerService.delete(messageId);
+            log.info({
+                messageId,
+                accountId,
+                oldUid: message.uid,
+                newUid,
+                destination: destinationMailbox.fullPath,
+            }, "Placement move confirmed on IMAP; marker cleared");
+            await emitMoveResync(emit, {
+                accountId,
+                sourceMailboxId: marker.sourceMailboxId,
+                destinationMailboxId: marker.destinationMailboxId,
+            });
+        })
+            .catch(async (error) => {
+            // Expected pause (epic #1281 invariant 3), not a fault: ack and
+            // skip rather than propagating into SQS retry/DLQ. The marker
+            // stays durable; the push resumes once the mailbox returns to
+            // normal (driven by the next PLACEMENT_MOVE_PUSH for this message,
+            // or the surviving-marker re-enqueue in PlacementMoveService).
+            if (error instanceof MailboxCursorPausedError) {
+                log.info({ messageId, accountId, cursorState: error.state }, "UIDVALIDITY changed; mailbox cursor tripped, pausing outbound placement-move push");
+                return;
+            }
+            if (receiveCount < config.attempts.placementMove) {
+                // Transient push failure — expected (connections drop). No alarm;
+                // SQS redelivery retries from the still-durable marker.
+                throw error;
+            }
+            // Redelivery budget exhausted: resolve into exactly one of the two
+            // terminal outcomes (epic invariant 3) instead of dead-lettering
+            // with no diagnosis.
+            const { outcome } = await resolveExhaustedPlacementMoveFailure({ markerService, messageService, threadMessageService, log }, {
+                placement: {
+                    status: message.status,
+                    mailboxId: message.mailboxId,
+                    uid: message.uid,
+                },
+                accountId,
+                accountConfigId,
+                messageId,
+                uid: message.uid,
+                sourceMailboxId: marker.sourceMailboxId,
+                sourceMailboxPath: sourceMailbox.fullPath,
+                getConnection: scope.getConnection,
+            });
+            if (outcome === "reconciled") {
+                await emitMoveResync(emit, {
+                    accountId,
+                    sourceMailboxId: marker.sourceMailboxId,
+                    destinationMailboxId: marker.destinationMailboxId,
+                });
+                return;
+            }
+            // Terminal and never re-thrown, so the handler-outcome series
+            // records this record as a success. Counted here or it is invisible.
+            metrics.imapFailure("PLACEMENT_MOVE_EXHAUSTED", "other", 1);
+            log.error({ error: error instanceof Error ? error.message : String(error) }, "Placement move retry exhausted; message still exists at its source");
+            // Terminal — never re-thrown, so the caller acks either way.
+        })
+            .finally(() => scope.release());
+    });
+};

package/dist/handlers/probe-message-id.d.ts

@@ -0,0 +1,2 @@
+import type { IThreadMessageRepository } from "@remit/data-ports";
+export declare const probeableMessageIdHeader: (threadMessageService: Pick<IThreadMessageRepository, "findByMessageId">, accountConfigId: string, messageId: string) => Promise<string | undefined>;

package/dist/handlers/probe-message-id.js

@@ -0,0 +1,6 @@
+import { isValidMessageId } from "@remit/data-ports/id";
+export const probeableMessageIdHeader = async (threadMessageService, accountConfigId, messageId) => {
+    const row = await threadMessageService.findByMessageId(accountConfigId, messageId);
+    const header = row?.messageIdHeader;
+    return isValidMessageId(header) ? header : undefined;
+};

package/dist/handlers/sync-mailboxes.d.ts

@@ -0,0 +1,45 @@
+import type { ProcessContext } from "../context.js";
+import type { SyncMailboxesEvent, SyncMessagesEvent } from "../events.js";
+/**
+ * Whether this fan-out should enqueue a mailbox.
+ *
+ * A sync asked for by name — POST /sync, which is the refresh control,
+ * pull-to-refresh, and the client's automatic poll — always syncs every
+ * mailbox, whatever ran a moment ago. A sync that happens as a side effect of
+ * something else (config load, OAuth connect, account create, the scheduled
+ * tick) skips mailboxes synced inside the freshness window, which is
+ * what stops those triggers from re-enumerating an account's folders on every
+ * page load.
+ *
+ * A mailbox that has never synced is always due.
+ */
+export declare const mailboxNeedsSync: (mailbox: {
+    lastMessageSyncAt?: number;
+}, event: Pick<SyncMailboxesEvent, "explicitRequest">, now: number, freshnessMs: number) => boolean;
+export declare const syncMailboxes: (event: SyncMailboxesEvent, ctx: ProcessContext) => Promise<void>;
+type SyncMessagesInput = Omit<SyncMessagesEvent, "eventId" | "timestamp">;
+/**
+ * Separate INBOX from the rest of the fan-out. `collectAllMailboxes` sorts it
+ * first, but sort order alone decides nothing once the emits go out together.
+ */
+export declare const splitInboxFirst: <T extends {
+    fullPath: string;
+}>(mailboxes: readonly T[]) => {
+    inbox: T | undefined;
+    rest: T[];
+};
+/**
+ * Emit INBOX's SYNC_MESSAGES event and wait for it before emitting the rest.
+ *
+ * Every event of an account shares one FIFO group (`MessageGroupId =
+ * accountId`), so the queue serves them strictly in arrival order. Emitting
+ * the whole list through `pMap` only bounds concurrency — it races the writes,
+ * and INBOX could land behind up to `EVENT_EMIT_CONCURRENCY - 1` other
+ * folders. The mail a person pressed refresh for then arrived only after every
+ * one of those folders had finished syncing.
+ */
+export declare const emitSyncMessagesEvents: (accountId: string, mailboxes: readonly {
+    mailboxId: string;
+    fullPath: string;
+}[], emit: (event: SyncMessagesInput) => Promise<unknown>) => Promise<void>;
+export {};

package/dist/handlers/sync-mailboxes.js

@@ -0,0 +1,233 @@
+import { writeFolderRoleAppointment } from "@remit/backend/folder-role-appointments";
+import { bindImportedFolders, disableFiltersMissingFolders, } from "@remit/config-transfer";
+import { SyncPhase } from "@remit/domain-enums";
+import { RefreshTokenError } from "@remit/mail-oauth-service";
+import { MailboxQueueService, MailboxSyncService, MailConnectionError, standardMailboxManagement, } from "@remit/mailbox-service";
+import pMap from "p-map";
+import { isAccountDeleted, isMailSyncDisabled, isUnsyncableHost, } from "../account-check.js";
+import { emitFrom } from "../emit.js";
+import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+import { createImportedFolder } from "./imported-folder.js";
+import { orderMailboxesForSync } from "./mailbox-sync-order.js";
+const EVENT_EMIT_CONCURRENCY = 20;
+/**
+ * Whether this fan-out should enqueue a mailbox.
+ *
+ * A sync asked for by name — POST /sync, which is the refresh control,
+ * pull-to-refresh, and the client's automatic poll — always syncs every
+ * mailbox, whatever ran a moment ago. A sync that happens as a side effect of
+ * something else (config load, OAuth connect, account create, the scheduled
+ * tick) skips mailboxes synced inside the freshness window, which is
+ * what stops those triggers from re-enumerating an account's folders on every
+ * page load.
+ *
+ * A mailbox that has never synced is always due.
+ */
+export const mailboxNeedsSync = (mailbox, event, now, freshnessMs) => {
+    if (event.explicitRequest)
+        return true;
+    if (!mailbox.lastMessageSyncAt)
+        return true;
+    return now - mailbox.lastMessageSyncAt >= freshnessMs;
+};
+export const syncMailboxes = async (event, ctx) => {
+    const { client, log, queues } = ctx;
+    const { account: accountService, mailbox: mailboxService, mailboxSpecialUse: mailboxSpecialUseService, secrets, } = client;
+    const binder = {
+        repositories: client,
+        appointFolderRole: (configId, accountId, role, mailboxId, lastKnownPath) => writeFolderRoleAppointment(client.accountSetting, configId, accountId, role, mailboxId, lastKnownPath),
+        createFolder: createImportedFolder(mailboxService, new MailboxQueueService({
+            mailboxService,
+            enqueue: standardMailboxManagement(queues.mailboxManagement),
+            logger: log,
+        })),
+    };
+    const { accountId } = event;
+    log.info({ event: event.type, accountId }, "Handling event");
+    const account = await accountService.get(accountId);
+    if (!account) {
+        throw new Error(`Account ${accountId} not found`);
+    }
+    if (isAccountDeleted(account, log)) {
+        return;
+    }
+    if (isMailSyncDisabled(account, log)) {
+        return;
+    }
+    // A reserved/never-resolvable IMAP host (RFC 2606) can never connect, so a
+    // sync attempt would retry and dead-letter forever. Skip cleanly — ack the
+    // event without connecting or throwing.
+    if (isUnsyncableHost(account, log)) {
+        return;
+    }
+    // withOAuthLifecycle owns the reauth/ACK contract (skip-if-reauth, flip on
+    // terminal auth failure, rethrow transient). The inner try/catch only
+    // records the terminal non-auth error phase before letting the wrapper
+    // rethrow for SQS retry/DLQ.
+    await withOAuthLifecycle(buildLifecycleDeps(secrets, accountService, ctx.oauth), account, log, async (credentials) => {
+        try {
+            await syncMailboxesForAccount(event, account, credentials, mailboxService, mailboxSpecialUseService, accountService, binder, log, emitFrom(ctx), ctx.pool, ctx.config.mailboxFreshnessMs);
+        }
+        catch (err) {
+            // Auth failures are handled by the wrapper — rethrow untouched so it
+            // flips the account to reauth_required rather than recording an error
+            // phase.
+            if (err instanceof RefreshTokenError ||
+                (err instanceof MailConnectionError && err.kind === "auth")) {
+                throw err;
+            }
+            // Record the terminal error phase before crashing (let-it-crash:
+            // record state, then rethrow so the event is retried/DLQ'd).
+            const message = err instanceof Error ? err.message : String(err);
+            await accountService.update(accountId, {
+                syncPhase: SyncPhase.error,
+                lastError: message,
+            });
+            throw err;
+        }
+    });
+};
+const syncMailboxesForAccount = async (event, account, credentials, mailboxService, mailboxSpecialUseService, accountService, binder, log, emit, pool, freshnessMs) => {
+    const { accountId } = account;
+    const borrowed = pool.borrow(account, credentials);
+    const result = await (async () => {
+        const connection = await borrowed.getConnection();
+        await accountService.markAuthenticated(accountId);
+        await accountService.update(accountId, {
+            syncPhase: SyncPhase.discovering_mailboxes,
+        });
+        const mailboxSyncService = new MailboxSyncService(mailboxService, mailboxSpecialUseService, log);
+        return mailboxSyncService.syncMailboxes({ accountId }, connection);
+    })().finally(() => borrowed.release());
+    await accountService.update(accountId, { lastSyncAt: Date.now() });
+    log.info({ result }, "Mailbox sync complete");
+    // The folder list this account holds is now known, which is the one thing a
+    // configuration import could not know when it ran: every folder in a file is
+    // named by IMAP path, and the ids are minted here. Binding what is bindable
+    // belongs at exactly this point, and is idempotent, so a later discovery
+    // simply finds nothing left to do.
+    const bound = await bindImportedFolders(binder, account.accountConfigId, accountId);
+    if (Object.values(bound).some((count) => count > 0)) {
+        log.info({ accountId, ...bound }, "Bound imported folder references");
+    }
+    const disabled = await disableFiltersMissingFolders(binder.repositories, account.accountConfigId);
+    if (disabled > 0) {
+        log.warn({ accountId, disabled }, "Disabled filters whose move folder no longer exists");
+    }
+    const allMailboxes = await collectAllMailboxes(accountId, mailboxService);
+    // This fan-out is where an account's IMAP work is decided: one SEARCH per
+    // mailbox per event, on a queue every account shares. `GET /config` fires a
+    // trigger per account on every call, so without a gate here an idle client
+    // re-enumerates every folder it owns on every page load.
+    //
+    // The gate is per mailbox and a sync asked for by name skips it outright.
+    // That distinction is the whole point: the previous cooldown gated
+    // everything, which is what made a refresh a no-op whenever a side-effect
+    // trigger had just run (issue #37).
+    const now = Date.now();
+    const mailboxes = allMailboxes.filter((mailbox) => mailboxNeedsSync(mailbox, event, now, freshnessMs));
+    const skipped = allMailboxes.length - mailboxes.length;
+    if (skipped > 0) {
+        log.info({ accountId, skipped }, "Skipped recently-synced mailboxes for a side-effect trigger");
+    }
+    if (allMailboxes.length === 0) {
+        log.info({ accountId }, "No mailboxes to sync messages for");
+        await accountService.update(accountId, {
+            syncPhase: SyncPhase.complete,
+            mailboxCountTotal: 0,
+            mailboxCountSynced: 0,
+        });
+        return;
+    }
+    if (mailboxes.length === 0) {
+        log.info({ accountId }, "Every mailbox is fresh; nothing to sync");
+        await accountService.update(accountId, {
+            syncPhase: SyncPhase.complete,
+            mailboxCountTotal: allMailboxes.length,
+            mailboxCountSynced: allMailboxes.length,
+        });
+        return;
+    }
+    log.info({ accountId, count: mailboxes.length }, "Emitting SYNC_MESSAGES events");
+    // Phase transition. Only the enqueued mailboxes emit a completion, so the
+    // gated ones are pre-credited — otherwise synced could never reach total.
+    //
+    // The counter is progress through THIS round, not a lifetime total: a new
+    // round restarts it, which is why it can read lower than a moment ago while
+    // a previous round is still draining. That is the same instant
+    // `account.lastSyncAt` is stamped, and the per-mailbox completion guard in
+    // sync-messages.ts keys off exactly that stamp — so a completion still in
+    // flight from the previous round counts once towards the new one, and each
+    // mailbox counts at most once per round.
+    const inboxEnqueued = mailboxes.some((m) => m.fullPath.toUpperCase() === "INBOX");
+    await accountService.update(accountId, {
+        syncPhase: inboxEnqueued
+            ? SyncPhase.syncing_inbox
+            : SyncPhase.syncing_others,
+        mailboxCountTotal: allMailboxes.length,
+        mailboxCountSynced: skipped,
+    });
+    await emitSyncMessagesEvents(accountId, mailboxes, emit);
+};
+/**
+ * Separate INBOX from the rest of the fan-out. `collectAllMailboxes` sorts it
+ * first, but sort order alone decides nothing once the emits go out together.
+ */
+export const splitInboxFirst = (mailboxes) => {
+    const at = mailboxes.findIndex((mailbox) => mailbox.fullPath.toUpperCase() === "INBOX");
+    if (at === -1)
+        return { inbox: undefined, rest: [...mailboxes] };
+    return {
+        inbox: mailboxes[at],
+        rest: mailboxes.filter((_, index) => index !== at),
+    };
+};
+/**
+ * Emit INBOX's SYNC_MESSAGES event and wait for it before emitting the rest.
+ *
+ * Every event of an account shares one FIFO group (`MessageGroupId =
+ * accountId`), so the queue serves them strictly in arrival order. Emitting
+ * the whole list through `pMap` only bounds concurrency — it races the writes,
+ * and INBOX could land behind up to `EVENT_EMIT_CONCURRENCY - 1` other
+ * folders. The mail a person pressed refresh for then arrived only after every
+ * one of those folders had finished syncing.
+ */
+export const emitSyncMessagesEvents = async (accountId, mailboxes, emit) => {
+    const eventFor = (mailboxId) => ({
+        type: "SYNC_MESSAGES",
+        accountId,
+        mailboxId,
+    });
+    const { inbox, rest } = splitInboxFirst(mailboxes);
+    if (inbox)
+        await emit(eventFor(inbox.mailboxId));
+    await pMap(rest, ({ mailboxId }) => emit(eventFor(mailboxId)), {
+        concurrency: EVENT_EMIT_CONCURRENCY,
+    });
+};
+/**
+ * Collect all mailboxes for an account, ordered for sync fan-out by
+ * special-use: INBOX first, then Sent/Drafts, then normal folders, with
+ * Junk/Spam and Trash last (issue #567). Real mail dispatches ahead of bulk
+ * folders so a fresh account fills its inbox before its spam.
+ */
+const collectAllMailboxes = async (accountId, mailboxService) => {
+    const mailboxes = [];
+    let continuationToken;
+    do {
+        const result = await mailboxService.listByAccount(accountId, {
+            continuationToken,
+        });
+        for (const mailbox of result.items) {
+            mailboxes.push({
+                mailboxId: mailbox.mailboxId,
+                fullPath: mailbox.fullPath,
+                lastMessageSyncAt: mailbox.lastMessageSyncAt,
+                specialUse: mailbox.specialUse,
+            });
+        }
+        continuationToken = result.continuationToken ?? undefined;
+    } while (continuationToken);
+    return orderMailboxesForSync(mailboxes);
+};

package/dist/handlers/sync-message-body.d.ts

@@ -0,0 +1,23 @@
+import type { ProcessContext } from "../context.js";
+import type { SyncMessageBodyEvent } from "../events.js";
+/**
+ * The ordered message ids to sync, plus a uid lookup when the event carried the
+ * preferred `messages` shape. The uid map lets the body-sync service skip the
+ * per-message DDB get; legacy events (ids only) leave it undefined and the
+ * service resolves uids itself.
+ */
+export interface ResolvedBatch {
+    messageIds: string[];
+    uidByMessageId?: Map<string, number>;
+    force: boolean;
+}
+export declare const resolveBatch: (event: SyncMessageBodyEvent) => ResolvedBatch;
+/**
+ * Build the loud, structured error thrown when a batch still has failed
+ * messages and SQS redelivery budget left. Throwing (rather than swallowing
+ * into a fresh re-enqueue) is what lets a genuine processing failure reach
+ * the body-dlq once `BODY_SYNC_MAX_ATTEMPTS` is exhausted — the SQS-level
+ * redrive owns retry scheduling now, not this handler.
+ */
+export declare const buildRetryableFailureError: (failedMessageIds: string[], receiveCount: number, maxAttempts: number) => Error;
+export declare const syncMessageBody: (event: SyncMessageBodyEvent, ctx: ProcessContext, receiveCount: number) => Promise<void>;