@bobfrankston/mailx 1.0.361 → 1.0.366

package/bin/mailx.js

@@ -1284,11 +1284,32 @@ RFC 5322 with CRLF line endings. Bodies are quoted-printable encoded (readable i
     if (settings.accounts.some(a => a.enabled)) {
         imapManager.syncAll()
             .then(() => imapManager.startWatching())
+            .then(() => {
+            // Seed the contacts table from received messages so address
+            // autocomplete works on the first compose without waiting for
+            // the user to manually trigger it. Cheap — one grouped SELECT
+            // + one INSERT per new sender. No-op if contact already exists.
+            const added = db.seedContactsFromMessages();
+            if (added > 0)
+                console.log(`  [contacts] seeded ${added} from message senders`);
+        })
             .catch(e => console.error(`  Sync error: ${e.message}`));
     }
     imapManager.startPeriodicSync(settings.sync.intervalMinutes);
     imapManager.startOutboxWorker();
     imapManager.watchConfigFiles();
+    // Re-seed contacts every 30 min so newly-received senders surface in
+    // autocomplete without restarting mailx. Cheap; idempotent.
+    setInterval(() => {
+        try {
+            const added = db.seedContactsFromMessages();
+            if (added > 0)
+                console.log(`  [contacts] periodic seed added ${added} new senders`);
+        }
+        catch (e) {
+            console.error(`  [contacts] periodic seed error: ${e.message}`);
+        }
+    }, 30 * 60_000);
     // Auto-update: periodically check npm for a newer version and push a
     // notification to the WebView so the user can update with one click.
     const UPDATE_CHECK_MS = 30 * 60_000; // 30 minutes

package/client/app.js

@@ -240,6 +240,11 @@ let currentFolderSpecialUse = "";
 function clearViewer() {
     messageState.select(null); // Deselect — viewer clears via subscription
 }
+// Anyone can ask the viewer to clear by dispatching a `mailx-clear-viewer`
+// CustomEvent on document. Used by message-list's loadSearchResults so the
+// stale preview from the prior selection doesn't linger over the new search
+// results. Slice D will replace this with row-object-level `unfocus()`.
+document.addEventListener("mailx-clear-viewer", () => clearViewer());
 const folderTitleEl = document.getElementById("ml-folder-title");
 let currentFolderName = "";
 let currentFolderSyncedAt;
@@ -1436,10 +1441,22 @@ onWsEvent((event) => {
             // Don't refresh folder tree on connect — it's already loaded by initFolderTree
             break;
         case "syncProgress": {
+            // Aggregate folders phases ("folders:<path>" when starting a folder,
+            // "folders-done" between folders) print as a proportion so the user
+            // can see forward progress instead of a meaningless "47%". Older
+            // phase strings ("sync:<path>", "folders") still render raw.
+            let label = `${event.phase} ${event.progress || 0}%`;
+            if (typeof event.phase === "string" && event.phase.startsWith("folders:")) {
+                const folderPath = event.phase.slice("folders:".length);
+                label = `folders — ${folderPath} (${event.progress || 0}%)`;
+            }
+            else if (event.phase === "folders-done") {
+                label = `folders ${event.progress || 0}% done`;
+            }
             if (statusSync)
-                statusSync.textContent = `Syncing ${event.accountId}: ${event.phase} ${event.progress || 0}%`;
+                statusSync.textContent = `Syncing ${event.accountId}: ${label}`;
             if (startupStatus)
-                startupStatus.textContent = `Syncing ${event.accountId}: ${event.phase}`;
+                startupStatus.textContent = `Syncing ${event.accountId}: ${label}`;
             // Mark syncing folder in tree — bubble up to visible parent if collapsed
             const syncPath = event.phase?.startsWith("sync:") ? event.phase.slice(5) : null;
             // Clear previous syncing markers for this account
@@ -2551,20 +2568,56 @@ function renderOutboxStatus(s) {
 }
 setInterval(async () => {
     try {
-        const { getOutboxStatus } = await import("./lib/api-client.js");
-        const s = await getOutboxStatus();
-        renderOutboxStatus(s);
+        const { getOutboxStatus, getDiagnostics } = await import("./lib/api-client.js");
+        renderOutboxStatus(await getOutboxStatus());
+        renderDiagnosticsBadge(await getDiagnostics());
     }
     catch { /* service unreachable */ }
 }, 15000);
 // First read on startup so the bar isn't blank.
 (async () => {
     try {
-        const { getOutboxStatus } = await import("./lib/api-client.js");
+        const { getOutboxStatus, getDiagnostics } = await import("./lib/api-client.js");
         renderOutboxStatus(await getOutboxStatus());
+        renderDiagnosticsBadge(await getDiagnostics());
     }
     catch { /* */ }
 })();
+/** Render the ⚠ "something's wrong" badge next to status-sync. Shown when
+ *  any account has non-zero diagnostic counters (inactivity timeouts,
+ *  connection-cap hits, rate-limit waits). Tooltip breaks down per-account. */
+function renderDiagnosticsBadge(snapshot) {
+    const host = document.getElementById("status-diag");
+    if (!host)
+        return;
+    const issues = (snapshot || []).filter(d => d.inactivityTimeouts > 0 || d.connCapHits > 0 || d.rateLimitWaits > 0);
+    if (issues.length === 0) {
+        host.hidden = true;
+        host.textContent = "";
+        host.title = "";
+        return;
+    }
+    host.hidden = false;
+    host.textContent = "⚠";
+    const totalTimeouts = issues.reduce((a, d) => a + d.inactivityTimeouts, 0);
+    const totalCapHits = issues.reduce((a, d) => a + d.connCapHits, 0);
+    const totalRateLimits = issues.reduce((a, d) => a + d.rateLimitWaits, 0);
+    const summary = [
+        totalTimeouts > 0 ? `${totalTimeouts} IMAP inactivity timeout${totalTimeouts === 1 ? "" : "s"}` : null,
+        totalCapHits > 0 ? `${totalCapHits} conn-cap rejection${totalCapHits === 1 ? "" : "s"}` : null,
+        totalRateLimits > 0 ? `${totalRateLimits} rate-limit wait${totalRateLimits === 1 ? "" : "s"}` : null,
+    ].filter(Boolean).join("; ");
+    const detail = issues.map(d => {
+        const parts = [
+            d.inactivityTimeouts > 0 ? `${d.inactivityTimeouts} timeout${d.inactivityTimeouts === 1 ? "" : "s"}` : null,
+            d.connCapHits > 0 ? `${d.connCapHits} conn-cap` : null,
+            d.rateLimitWaits > 0 ? `${d.rateLimitWaits} rate-limit` : null,
+        ].filter(Boolean).join(", ");
+        const last = d.lastCommand ? `\n  last: ${d.lastCommand}` : "";
+        return `${d.accountId}: ${parts}${last}`;
+    }).join("\n");
+    host.title = `Connection issues — ${summary}\n\n${detail}`;
+}
 // Q64: pop-out a message into a floating overlay (real-OS-window pending C44).
 document.addEventListener("mailx-popout-message", (async (e) => {
     const { accountId, uid, folderId, subject } = e.detail || {};

package/client/components/message-list.js

@@ -220,6 +220,11 @@ export async function loadSearchResults(query, scope = "all", accountId = "", fo
     const body = document.getElementById("ml-body");
     if (!body)
         return;
+    // Clear the preview pane — old preview from the prior selection lingers
+    // until the user clicks a search result. Atomic clear-on-list-mutation
+    // is what Slice D's row-objects-own-preview will do generally; this is
+    // the band-aid for the search-specific case until that lands.
+    document.dispatchEvent(new CustomEvent("mailx-clear-viewer"));
     body.innerHTML = `<div class="ml-empty">Searching...</div>`;
     try {
         // Regex search: filter client-side
@@ -455,6 +460,10 @@ function appendMessages(body, accountId, items) {
             row.classList.add("flagged");
         if (!msg.bodyPath)
             row.classList.add("not-downloaded");
+        // Pink-row visible reconciliation state (S1 slice C): a queued local
+        // action (move/flag/delete) hasn't been ACK'd by the server yet.
+        if (msg.pending)
+            row.classList.add("pending-reconcile");
         row.dataset.uid = String(msg.uid);
         row.dataset.accountId = msgAccountId;
         row.dataset.folderId = String(msg.folderId);

package/client/components/message-viewer.js

@@ -34,7 +34,17 @@ export function initViewer() {
                 clearViewer();
             }
         }
-        // "messages" change (sync reload) — don't touch the viewer
+        else if (change === "messages") {
+            // List was replaced (search, folder switch, sync reload). If the
+            // currently-displayed message is no longer in the list, clear the
+            // viewer — otherwise the user sees a preview that doesn't match
+            // any visible row. (The "search-clears-preview" bug class.)
+            // setMessages already deselects in this case; we just need to
+            // notice and clear here since the viewer ignored "messages" before.
+            if (currentMessage && !state.getSelected()) {
+                clearViewer();
+            }
+        }
     });
 }
 // Zoom is persisted across messages via localStorage

package/client/index.html

@@ -157,6 +157,7 @@
     <footer class="status-bar" id="status-bar">
         <span id="status-accounts"></span>
         <span id="status-sync">Syncing...</span>
+        <span id="status-diag" class="status-diag" hidden title=""></span>
         <span id="status-pending"></span>
         <span id="status-queue"></span>
         <span class="app-version" id="status-version">mailx</span>

package/client/lib/api-client.js

@@ -131,6 +131,9 @@ export function reauthenticate(accountId) {
 export function getSyncPending() {
     return ipc().getSyncPending();
 }
+export function getDiagnostics() {
+    return ipc().getDiagnostics?.() ?? Promise.resolve([]);
+}
 export function getOutboxStatus() {
     return ipc().getOutboxStatus();
 }

package/client/lib/mailxapi.js

@@ -159,6 +159,7 @@
         syncAccount: function(accountId) { return callNode("syncAccount", { accountId: accountId }); },
         getSyncPending: function() { return callNode("getSyncPending"); },
         getOutboxStatus: function() { return callNode("getOutboxStatus"); },
+        getDiagnostics: function() { return callNode("getDiagnostics"); },
         listQueuedOutgoing: function() { return callNode("listQueuedOutgoing"); },
         cancelQueuedOutgoing: function(p) { return callNode("cancelQueuedOutgoing", { path: p }); },
         reauthenticate: function(accountId) { return callNode("reauthenticate", { accountId: accountId }); },

package/client/styles/components.css

@@ -779,6 +779,17 @@ button.tb-menu-item { background: none; border: none; color: inherit; width: 100
     opacity: 0.5;
 }
 
+/* S1 slice C — pink row when a local action (move/flag/delete) is queued
+   but the server hasn't ACK'd. Visible reconciliation state: "we did your
+   thing locally, the server hasn't agreed yet." Selection still wins
+   visually so the active row is identifiable. */
+.ml-row.pending-reconcile {
+    background: oklch(0.96 0.04 350);  /* pale pink */
+}
+.ml-row.pending-reconcile.selected {
+    background: oklch(0.85 0.10 350);  /* deeper pink when selected */
+}
+
 .ml-empty {
     grid-column: 1 / -1;
     display: flex;
@@ -1072,6 +1083,15 @@ button.tb-menu-item { background: none; border: none; color: inherit; width: 100
     font-size: var(--font-size-sm);
     color: var(--color-text-muted);
 }
+
+/* Diagnostics ⚠ badge next to status-sync — inactivity timeouts and similar
+   server-misbehavior counters. Hover for per-account detail. */
+.status-diag {
+    color: oklch(0.70 0.18 55);  /* amber */
+    cursor: help;
+    font-size: var(--font-size-base);
+    margin-left: calc(var(--gap-xs) * -1);
+}
 .status-action {
     border: 1px solid oklch(0.65 0.15 25);
     background: transparent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx",
-  "version": "1.0.361",
+  "version": "1.0.366",
   "description": "Local-first email client with IMAP sync and standalone native app",
   "type": "module",
   "main": "bin/mailx.js",

package/packages/mailx-core/index.d.ts

@@ -57,6 +57,8 @@ export declare function getMessage(params: {
     folderId: number;
     folderName?: string;
     uid: number;
+    uuid?: string;
+    pending?: boolean;
     messageId: string;
     inReplyTo: string;
     references: string[];

package/packages/mailx-imap/index.d.ts

@@ -28,6 +28,20 @@ export interface ImapManagerEvents {
      *  queue-status indicator without polling. Aggregate status across all
      *  accounts is included so the listener doesn't have to reassemble it. */
     outboxStatus: (status: OutboxStatus) => void;
+    /** Per-account health counter update. Fires when an inactivity timeout,
+     *  connection-cap hit, or rate-limit wait happens. */
+    diagnostics: (accountId: string, snapshot: AccountDiagnostics) => void;
+}
+/** Per-account diagnostic counters — tracks "something's wrong" events the
+ *  user should be able to see without opening the log. */
+export interface AccountDiagnostics {
+    accountId: string;
+    inactivityTimeouts: number;
+    connCapHits: number;
+    rateLimitWaits: number;
+    lastTimeoutAt: number;
+    lastCommand: string;
+    lastError: string;
 }
 /** Per-account outbox queue breakdown, plus totals for the UI. */
 export interface OutboxStatus {
@@ -57,6 +71,19 @@ export declare class ImapManager extends EventEmitter {
     useNativeClient: boolean;
     /** Accounts hitting connection limits — back off until this time */
     private connectionBackoff;
+    /** Per-account health counters. Incremented when the server misbehaves
+     *  in ways that suggest a problem the user should know about (inactivity
+     *  timeouts, connection-cap hits, rate-limit waits). Surfaced via a
+     *  `diagnostics` event + `getDiagnostics` IPC so the UI can show a ⚠
+     *  badge instead of burying the issue in the log. */
+    private diagnostics;
+    private getDiagnosticsEntry;
+    /** Classify an error message and bump the relevant counter; emit the
+     *  updated diagnostics snapshot. Call this from every catch in the sync
+     *  paths so the UI can count "something's wrong" in real time. */
+    private recordError;
+    /** Public read for the IPC surface: snapshot of all account diagnostics. */
+    getDiagnosticsSnapshot(): AccountDiagnostics[];
     private transportFactory;
     constructor(db: MailxDB, transportFactory: TransportFactory);
     /** Get OAuth access token for an account (for SMTP auth) */
@@ -177,6 +204,10 @@ export declare class ImapManager extends EventEmitter {
      *  The persistent fetchClient can only handle one command at a time (IMAP protocol limitation). */
     private fetchQueues;
     /** Serialize body fetch operations per account — prevents concurrent IMAP commands on same connection */
+    /** Unlink the on-disk body file for a message by reading its `body_path`
+     *  from the DB. Safe to call either before or after `db.deleteMessage`
+     *  — read body_path first, store it, then unlink whenever. */
+    private unlinkBodyFile;
     private enqueueFetch;
     /** Fetch a single message body on demand, caching in the store.
      *  Uses its own fresh connection — never blocked by background prefetch. */

package/packages/mailx-imap/index.js

@@ -148,6 +148,48 @@ export class ImapManager extends EventEmitter {
     /** Accounts hitting connection limits — back off until this time */
     connectionBackoff = new Map();
     // Connection management: see withConnection() below — no semaphore needed
+    /** Per-account health counters. Incremented when the server misbehaves
+     *  in ways that suggest a problem the user should know about (inactivity
+     *  timeouts, connection-cap hits, rate-limit waits). Surfaced via a
+     *  `diagnostics` event + `getDiagnostics` IPC so the UI can show a ⚠
+     *  badge instead of burying the issue in the log. */
+    diagnostics = new Map();
+    getDiagnosticsEntry(accountId) {
+        let d = this.diagnostics.get(accountId);
+        if (!d) {
+            d = { accountId, inactivityTimeouts: 0, connCapHits: 0, rateLimitWaits: 0, lastTimeoutAt: 0, lastCommand: "", lastError: "" };
+            this.diagnostics.set(accountId, d);
+        }
+        return d;
+    }
+    /** Classify an error message and bump the relevant counter; emit the
+     *  updated diagnostics snapshot. Call this from every catch in the sync
+     *  paths so the UI can count "something's wrong" in real time. */
+    recordError(accountId, errMsg) {
+        const d = this.getDiagnosticsEntry(accountId);
+        if (/inactivity timeout/i.test(errMsg)) {
+            d.inactivityTimeouts++;
+            d.lastTimeoutAt = Date.now();
+            const m = errMsg.match(/A\d+ [A-Z ]+.*$/);
+            if (m)
+                d.lastCommand = m[0].slice(0, 120);
+        }
+        else if (/UNAVAILABLE|Maximum number of connections|too many connections/i.test(errMsg)) {
+            d.connCapHits++;
+        }
+        else if (/429|rate limit/i.test(errMsg)) {
+            d.rateLimitWaits++;
+        }
+        else {
+            return; // not a known diagnostic class — don't emit
+        }
+        d.lastError = errMsg.slice(0, 200);
+        this.emit("diagnostics", accountId, { ...d });
+    }
+    /** Public read for the IPC surface: snapshot of all account diagnostics. */
+    getDiagnosticsSnapshot() {
+        return Array.from(this.diagnostics.values()).map(d => ({ ...d }));
+    }
     transportFactory;
     constructor(db, transportFactory) {
         super();
@@ -939,8 +981,9 @@ export class ImapManager extends EventEmitter {
                 const localUids = this.db.getUidsForFolder(accountId, folderId);
                 for (const uid of localUids) {
                     if (!serverUids.has(uid)) {
+                        // Read body_path BEFORE deleting the row, then unlink.
+                        this.unlinkBodyFile(accountId, uid, folderId).catch(() => { });
                         this.db.deleteMessage(accountId, uid);
-                        this.bodyStore.deleteMessage(accountId, folderId, uid).catch(() => { });
                         deletedCount++;
                     }
                 }
@@ -1079,47 +1122,77 @@ export class ImapManager extends EventEmitter {
             else {
                 console.log(`  [sync] ${accountId}: no INBOX folder found`);
             }
-            // Step 3: Sync remaining folders
+            // Step 3: Sync remaining folders.
+            //
+            // Parallel pool (concurrency 2) with a per-folder wall-clock cap.
+            // Previous serial loop meant one slow Dovecot UID FETCH could park
+            // every other folder behind it for minutes — user observed "mailx
+            // says synced but 90 folders are empty" because the loop never
+            // progressed past the stalled FETCH before the next sync tick.
+            //
+            // Parallelism uses independent IMAP sockets from the ops-client
+            // pool, so one stalled socket doesn't block the others. The 60s
+            // timeout abandons a stalled command instead of waiting out
+            // Dovecot's 300s server-side inactivity timer; the next sync tick
+            // retries on a fresh socket.
             const remaining = folders.filter(f => f.specialUse !== "inbox");
             remaining.sort((a, b) => {
                 const pa = priorityOrder.indexOf(a.specialUse || "") >= 0 ? priorityOrder.indexOf(a.specialUse || "") : 5;
                 const pb = priorityOrder.indexOf(b.specialUse || "") >= 0 ? priorityOrder.indexOf(b.specialUse || "") : 5;
                 return pa - pb;
             });
-            let consecutiveErrors = 0;
-            for (const folder of remaining) {
+            const CONCURRENCY = 2;
+            const PER_FOLDER_TIMEOUT_MS = 60_000;
+            const total = remaining.length;
+            let done = 0;
+            let idx = 0;
+            const syncOne = async (folder) => {
                 const isTrashChild = folder.path.includes("/") && folder.path.toLowerCase().startsWith("trash");
                 const highestUid = this.db.getHighestUid(accountId, folder.id);
                 if (isTrashChild && highestUid === 0)
-                    continue;
+                    return;
                 try {
-                    client = await this.getOpsClient(accountId);
-                    await this.syncFolder(accountId, folder.id, client);
-                    consecutiveErrors = 0;
+                    const fresh = await this.getOpsClient(accountId);
+                    await Promise.race([
+                        this.syncFolder(accountId, folder.id, fresh),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error(`per-folder timeout (${PER_FOLDER_TIMEOUT_MS / 1000}s): ${folder.path}`)), PER_FOLDER_TIMEOUT_MS)),
+                    ]);
                 }
                 catch (e) {
-                    consecutiveErrors++;
                     if (e.responseText?.includes("doesn't exist")) {
                         this.db.deleteFolder(folder.id);
                     }
                     else {
                         console.error(`  Skipping ${folder.path}: ${e.message}`);
-                        // Connection is probably dead — reconnect
-                        await this.reconnectOps(accountId);
-                    }
-                    // Too many consecutive errors = connection fundamentally broken
-                    if (consecutiveErrors >= 3) {
-                        console.error(`  [sync] ${accountId}: ${consecutiveErrors} consecutive errors — aborting sync`);
-                        break;
+                        this.recordError(accountId, e.message || String(e));
+                        // A timeout or stale-socket failure — drop the ops
+                        // client so the next iteration reconnects rather than
+                        // inheriting the doomed socket.
+                        await this.reconnectOps(accountId).catch(() => { });
                     }
                 }
-            }
+            };
+            const worker = async () => {
+                while (true) {
+                    const myIdx = idx++;
+                    if (myIdx >= remaining.length)
+                        return;
+                    const folder = remaining[myIdx];
+                    this.emit("syncProgress", accountId, `folders:${folder.path}`, Math.round((done / Math.max(total, 1)) * 100));
+                    await syncOne(folder);
+                    done++;
+                    this.emit("syncProgress", accountId, `folders-done`, Math.round((done / Math.max(total, 1)) * 100));
+                    console.log(`  [sync] ${accountId}: folder ${done}/${total} done (${folder.path})`);
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(CONCURRENCY, remaining.length) }, () => worker()));
             this.accountErrorShown.delete(accountId);
             this.emit("syncComplete", accountId);
         }
         catch (e) {
             const errMsg = imapError(e);
             this.emit("syncError", accountId, errMsg);
+            this.recordError(accountId, errMsg);
             console.error(`Sync error for ${accountId}: ${errMsg}`);
             this.handleSyncError(accountId, errMsg);
         }
@@ -1273,8 +1346,8 @@ export class ImapManager extends EventEmitter {
                 }
                 else {
                     for (const uid of toDelete) {
+                        this.unlinkBodyFile(accountId, uid, folder.id).catch(() => { });
                         this.db.deleteMessage(accountId, uid);
-                        this.bodyStore.deleteMessage(accountId, folder.id, uid).catch(() => { });
                     }
                     if (toDelete.length > 0)
                         console.log(`  [api] ${accountId}/${folder.path}: ${toDelete.length} deleted`);
@@ -1660,6 +1733,18 @@ export class ImapManager extends EventEmitter {
      *  The persistent fetchClient can only handle one command at a time (IMAP protocol limitation). */
     fetchQueues = new Map();
     /** Serialize body fetch operations per account — prevents concurrent IMAP commands on same connection */
+    /** Unlink the on-disk body file for a message by reading its `body_path`
+     *  from the DB. Safe to call either before or after `db.deleteMessage`
+     *  — read body_path first, store it, then unlink whenever. */
+    async unlinkBodyFile(accountId, uid, folderId) {
+        try {
+            const row = this.db.getMessageByUid(accountId, uid, folderId);
+            const p = row?.bodyPath;
+            if (p)
+                await this.bodyStore.unlinkByPath(p);
+        }
+        catch { /* row already gone / file already gone — both fine */ }
+    }
     enqueueFetch(accountId, fn) {
         const prev = this.fetchQueues.get(accountId) || Promise.resolve();
         const next = prev.then(fn, fn); // run fn after previous completes (regardless of success/failure)
@@ -1670,48 +1755,15 @@ export class ImapManager extends EventEmitter {
     /** Fetch a single message body on demand, caching in the store.
      *  Uses its own fresh connection — never blocked by background prefetch. */
     async fetchMessageBody(accountId, folderId, uid) {
-        // Already cached? If the file is on disk but body_path wasn't written to
-        // the DB (e.g. from an interrupted earlier run), the prefetch loop would
-        // otherwise keep returning the same missing rows forever — once saw
-        // "gmail: 17266796 bodies cached" in the logs, which is the counter
-        // spinning on the same 100 rows.
-        if (await this.bodyStore.hasMessage(accountId, folderId, uid)) {
-            // COMINGLING GUARD: verify the cached body's Message-ID matches the
-            // DB row's messageId. If UIDVALIDITY changed server-side (mailbox
-            // recreated, server quirk) the same integer UID can point at a
-            // different message — the on-disk .eml becomes stale but hasMessage()
-            // still returns true. User-reported: "Peter Hoddie letter comingled
-            // with a much older letter." Check fixes it regardless of root cause.
-            const cached = await this.bodyStore.getMessage(accountId, folderId, uid);
-            const envelope = this.db.getMessageByUid(accountId, uid, folderId);
-            const expectedId = envelope?.messageId || "";
-            if (expectedId) {
-                // Scan headers only — Message-ID should land in the first few KB.
-                const head = cached.subarray(0, Math.min(cached.length, 16 * 1024)).toString("utf-8");
-                const m = head.match(/^Message-ID:\s*<([^>\r\n]+)>/im);
-                const cachedId = m ? `<${m[1]}>` : "";
-                if (cachedId && expectedId && cachedId !== expectedId) {
-                    console.error(`  [body] COMINGLING DETECTED ${accountId}/${folderId}/${uid}: expected ${expectedId}, cached ${cachedId} — dropping cache, re-fetching`);
-                    try {
-                        await this.bodyStore.deleteMessage(accountId, folderId, uid);
-                    }
-                    catch { /* */ }
-                    // fall through to re-fetch path
-                }
-                else {
-                    const existingPath = this.bodyStore.getMessagePath?.(accountId, folderId, uid);
-                    if (existingPath)
-                        this.db.updateBodyPath(accountId, uid, existingPath);
-                    return cached;
-                }
-            }
-            else {
-                // No messageId on the DB row (shouldn't happen but be permissive).
-                const existingPath = this.bodyStore.getMessagePath?.(accountId, folderId, uid);
-                if (existingPath)
-                    this.db.updateBodyPath(accountId, uid, existingPath);
-                return cached;
-            }
+        // Already cached? Read the DB row's `body_path` and check the file
+        // exists there. No more `(folderId, uid)` path reconstruction — that
+        // was the source of the S49 comingling bug (UID reuse + folder move
+        // pointing two messages at one file). `body_path` is the sole
+        // authority on where a given message's body lives on disk.
+        const envelope = this.db.getMessageByUid(accountId, uid, folderId);
+        const storedPath = envelope?.bodyPath || "";
+        if (storedPath && await this.bodyStore.hasByPath(storedPath)) {
+            return this.bodyStore.readByPath(storedPath);
         }
         if (!this.configs.has(accountId))
             return null;
@@ -1967,8 +2019,8 @@ export class ImapManager extends EventEmitter {
                                 if (received.has(uid))
                                     continue;
                                 try {
+                                    this.unlinkBodyFile(accountId, uid, folderId).catch(() => { });
                                     this.db.deleteMessage(accountId, uid);
-                                    this.bodyStore.deleteMessage(accountId, folderId, uid).catch(() => { });
                                     counters.deleted++;
                                     madeProgress = true;
                                 }
@@ -2051,8 +2103,8 @@ export class ImapManager extends EventEmitter {
                                 if (received.has(uid))
                                     continue;
                                 try {
+                                    this.unlinkBodyFile(accountId, uid, folderId).catch(() => { });
                                     this.db.deleteMessage(accountId, uid);
-                                    this.bodyStore.deleteMessage(accountId, folderId, uid).catch(() => { });
                                     counters.deleted++;
                                     madeProgress = true;
                                 }
@@ -2096,8 +2148,8 @@ export class ImapManager extends EventEmitter {
         const trash = this.findFolder(accountId, "trash");
         // Local first — remove all from DB immediately
         for (const msg of messages) {
+            this.unlinkBodyFile(accountId, msg.uid, msg.folderId).catch(() => { });
             this.db.deleteMessage(accountId, msg.uid);
-            this.bodyStore.deleteMessage(accountId, msg.folderId, msg.uid).catch(() => { });
         }
         console.log(`  Deleted ${messages.length} messages locally`);
         // Queue IMAP actions
@@ -2149,8 +2201,8 @@ export class ImapManager extends EventEmitter {
     async trashMessage(accountId, folderId, uid) {
         const trash = this.findFolder(accountId, "trash");
         // Local first — remove from DB immediately
+        this.unlinkBodyFile(accountId, uid, folderId).catch(() => { });
         this.db.deleteMessage(accountId, uid);
-        this.bodyStore.deleteMessage(accountId, folderId, uid).catch(() => { });
         // Queue IMAP action + log the resolution so "I deleted a message and
         // now it's in neither trash nor deleted" is diagnosable from the log.
         if (trash && trash.id !== folderId) {

package/packages/mailx-service/index.d.ts

@@ -36,6 +36,9 @@ export declare class MailxService {
     };
     /** Outbox queue depth + retry status for the UI status bar. Cheap to call. */
     getOutboxStatus(): any;
+    /** Per-account health snapshot: inactivity-timeout count, conn-cap hits,
+     *  last failed IMAP command. Drives the diagnostics ⚠ badge in the UI. */
+    getDiagnostics(): any;
     /** List queued outgoing messages with parsed envelope headers so the UI
      *  can render a pink-row "pending" view before IMAP APPEND succeeds. */
     listQueuedOutgoing(): any[];

package/packages/mailx-service/index.js

@@ -413,6 +413,11 @@ export class MailxService {
     getOutboxStatus() {
         return this.imapManager.getOutboxStatus();
     }
+    /** Per-account health snapshot: inactivity-timeout count, conn-cap hits,
+     *  last failed IMAP command. Drives the diagnostics ⚠ badge in the UI. */
+    getDiagnostics() {
+        return this.imapManager.getDiagnosticsSnapshot();
+    }
     /** List queued outgoing messages with parsed envelope headers so the UI
      *  can render a pink-row "pending" view before IMAP APPEND succeeds. */
     listQueuedOutgoing() {

package/packages/mailx-service/jsonrpc.js

@@ -94,6 +94,8 @@ async function dispatchAction(svc, action, p) {
             return { ok: true };
         case "getSyncPending":
             return svc.getSyncPending();
+        case "getDiagnostics":
+            return svc.getDiagnostics();
         case "getOutboxStatus":
             return svc.getOutboxStatus();
         case "listQueuedOutgoing":

package/packages/mailx-store/db.d.ts

@@ -7,6 +7,10 @@ import type { MessageEnvelope, Folder, EmailAddress, PagedResult, MessageQuery }
 export declare class MailxDB {
     private db;
     constructor(dbDir: string);
+    /** One-time: assign UUIDs to every `messages` row that's missing one.
+     *  Runs on every startup but the WHERE clause makes it a no-op after the
+     *  first pass. */
+    private backfillUuids;
     /** Has this Message-ID already been sent? Used to prevent the outbox from
      *  re-sending the same raw file across crash/restart cycles. */
     hasSentMessage(messageId: string): boolean;
@@ -85,7 +89,17 @@ export declare class MailxDB {
     getMessages(query: MessageQuery): PagedResult<MessageEnvelope>;
     /** Unified inbox: all inbox folders across accounts, sorted by date, paginated in SQL */
     getUnifiedInbox(page?: number, pageSize?: number): PagedResult<MessageEnvelope>;
+    /** Map a `messages` row to a MessageEnvelope. Exposes `uuid` (stable local
+     *  identity) and `bodyPath` (authoritative on-disk location) in addition
+     *  to the server-binding metadata. */
+    private rowToEnvelope;
     getMessageByUid(accountId: string, uid: number, folderId?: number): MessageEnvelope;
+    /** Look up a message by its stable local UUID. Returned envelope includes
+     *  the current (folder_id, uid) — these may have changed since the UUID
+     *  was minted (folder move or server UID renumber) but the UUID itself
+     *  is stable. Use this as the identity in any long-lived reference
+     *  (compose in-reply-to, dally, undo stacks). */
+    getMessageByUuid(uuid: string): MessageEnvelope;
     getMessageBodyPath(accountId: string, uid: number): string;
     updateMessageFlags(accountId: string, uid: number, flags: string[]): void;
     updateMessageFolder(accountId: string, uid: number, targetFolderId: number): void;

package/packages/mailx-store/db.js

@@ -4,6 +4,7 @@
  * Message bodies are NOT here -- they live in the MessageStore backend.
  */
 import { DatabaseSync } from "node:sqlite";
+import { randomUUID } from "node:crypto";
 import * as path from "node:path";
 import * as fs from "node:fs";
 const SCHEMA = `
@@ -166,6 +167,46 @@ export class MailxDB {
         // directly instead of paginating listMessageIds for every body fetch
         // — a UID-only path costs 2-3 rate-limited API calls per message.
         this.addColumnIfMissing("messages", "provider_id", "TEXT");
+        // uuid: stable per-message local identity. Assigned the first time
+        // mailx sees the message and never changes — survives server UID
+        // renumbers, UIDVALIDITY bumps, and cross-folder moves (the sync
+        // rebinds the (folder_id, uid) tuple but keeps the UUID). All UI
+        // references SHOULD flow through uuid; (account_id, folder_id, uid)
+        // remains the server-binding metadata used only by sync.
+        this.addColumnIfMissing("messages", "uuid", "TEXT");
+        try {
+            this.db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_messages_uuid ON messages(uuid)");
+        }
+        catch { /* already exists */ }
+        // Backfill UUIDs for any pre-existing rows that were inserted before
+        // this column landed. One UPDATE + an id roundtrip per row — cheap
+        // at our row counts, runs once per DB upgrade.
+        this.backfillUuids();
+    }
+    /** One-time: assign UUIDs to every `messages` row that's missing one.
+     *  Runs on every startup but the WHERE clause makes it a no-op after the
+     *  first pass. */
+    backfillUuids() {
+        try {
+            const rows = this.db.prepare("SELECT id FROM messages WHERE uuid IS NULL OR uuid = ''").all();
+            if (rows.length === 0)
+                return;
+            console.log(`  [db] backfilling ${rows.length} message UUIDs`);
+            const upd = this.db.prepare("UPDATE messages SET uuid = ? WHERE id = ?");
+            this.db.exec("BEGIN");
+            try {
+                for (const r of rows)
+                    upd.run(randomUUID().replace(/-/g, ""), r.id);
+                this.db.exec("COMMIT");
+            }
+            catch (e) {
+                this.db.exec("ROLLBACK");
+                throw e;
+            }
+        }
+        catch (e) {
+            console.error(`  [db] backfillUuids failed: ${e.message}`);
+        }
     }
     // ── Sent-log (dedup) ──
     /** Has this Message-ID already been sent? Used to prevent the outbox from
@@ -423,6 +464,24 @@ export class MailxDB {
             }
             return existing.id;
         }
+        // Move-detection: if this Message-ID already exists for this account
+        // in a DIFFERENT folder, treat it as a server-side move rather than a
+        // new arrival. Rebind that row to (folder_id, uid) — keep the UUID,
+        // body_path, flags, all the local state. Saves a body re-fetch and
+        // preserves any local references (in_reply_to, dally entries, undo
+        // stacks) that point at the UUID. Only kicks in when messageId is
+        // present (servers usually include it; if not we fall through to a
+        // fresh insert which mints a new UUID).
+        if (msg.messageId) {
+            const moved = this.db.prepare("SELECT id, folder_id, uid FROM messages WHERE account_id = ? AND message_id = ? LIMIT 1").get(msg.accountId, msg.messageId);
+            if (moved) {
+                console.log(`  [move-detect] ${msg.accountId} ${msg.messageId}: rebinding row ${moved.id} (folder ${moved.folder_id}/uid ${moved.uid} → folder ${msg.folderId}/uid ${msg.uid})`);
+                // Update folder_id + uid; preserve uuid, body_path, flags
+                // (server flags will catch up on the next full sync).
+                this.db.prepare("UPDATE messages SET folder_id = ?, uid = ?, cached_at = ? WHERE id = ?").run(msg.folderId, msg.uid, Date.now(), moved.id);
+                return moved.id;
+            }
+        }
         const toText = msg.to.map(a => `${a.name} ${a.address}`).join(" ");
         const ccText = msg.cc.map(a => `${a.name} ${a.address}`).join(" ");
         // Thread id = oldest ancestor in the reference chain, or the in-reply-to
@@ -430,13 +489,17 @@ export class MailxDB {
         // whether an existing row already has a thread_id for any of the refs,
         // so late-arriving replies latch onto the same thread.
         const threadId = this.computeThreadId(msg.accountId, msg.messageId, msg.inReplyTo, msg.references);
+        // Mint a per-message local identity UUID at first-sight. Stable for
+        // the life of the row — survives server UID renumbers, folder moves
+        // (sync rebinds folder_id/uid but keeps uuid), UIDVALIDITY bumps.
+        const uuid = randomUUID().replace(/-/g, "");
         const result = this.db.prepare(`
             INSERT INTO messages (
-                account_id, folder_id, uid, message_id, in_reply_to, refs, thread_id,
+                account_id, folder_id, uid, uuid, message_id, in_reply_to, refs, thread_id,
                 date, subject, from_address, from_name, to_json, cc_json,
                 flags_json, size, has_attachments, preview, body_path, cached_at, provider_id
-            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-        `).run(msg.accountId, msg.folderId, msg.uid, msg.messageId, msg.inReplyTo, JSON.stringify(msg.references), threadId, msg.date, msg.subject, msg.from.address, msg.from.name, JSON.stringify(msg.to), JSON.stringify(msg.cc), JSON.stringify(msg.flags), msg.size, msg.hasAttachments ? 1 : 0, msg.preview, msg.bodyPath, Date.now(), msg.providerId || null);
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(msg.accountId, msg.folderId, msg.uid, uuid, msg.messageId, msg.inReplyTo, JSON.stringify(msg.references), threadId, msg.date, msg.subject, msg.from.address, msg.from.name, JSON.stringify(msg.to), JSON.stringify(msg.cc), JSON.stringify(msg.flags), msg.size, msg.hasAttachments ? 1 : 0, msg.preview, msg.bodyPath, Date.now(), msg.providerId || null);
         const rowId = Number(result.lastInsertRowid);
         // Index for full-text search
         try {
@@ -466,12 +529,22 @@ export class MailxDB {
             where += " AND flags_json LIKE '%\\\\Flagged%'";
         }
         const total = this.db.prepare(`SELECT COUNT(*) as cnt FROM messages WHERE ${where}`).get(...params).cnt;
-        const rows = this.db.prepare(`SELECT * FROM messages WHERE ${where} ORDER BY ${sortCol} ${sortDir} LIMIT ? OFFSET ?`).all(...params, pageSize, offset);
+        // LEFT JOIN sync_actions so each row carries a `pending` flag —
+        // true when the user has a queued local action (move/flag/delete)
+        // not yet acknowledged by the server. UI renders these in pink so
+        // local-only state is visible (Slice C of S1).
+        const rows = this.db.prepare(`SELECT m.*, EXISTS(
+                SELECT 1 FROM sync_actions sa
+                WHERE sa.account_id = m.account_id AND sa.uid = m.uid
+            ) AS pending
+            FROM messages m WHERE ${where.replace(/\b(account_id|folder_id|uid|date|subject|from_name|from_address|flags_json)\b/g, "m.$1")}
+            ORDER BY m.${sortCol} ${sortDir} LIMIT ? OFFSET ?`).all(...params, pageSize, offset);
         const items = rows.map(r => ({
             id: r.id,
             accountId: r.account_id,
             folderId: r.folder_id,
             uid: r.uid,
+            uuid: r.uuid || "",
             messageId: r.message_id || "",
             inReplyTo: r.in_reply_to || "",
             references: JSON.parse(r.refs || "[]"),
@@ -485,7 +558,8 @@ export class MailxDB {
             size: r.size,
             hasAttachments: !!r.has_attachments,
             preview: r.preview,
-            bodyPath: r.body_path || ""
+            bodyPath: r.body_path || "",
+            pending: !!r.pending,
         }));
         return { items, total, page, pageSize };
     }
@@ -522,19 +596,16 @@ export class MailxDB {
         }));
         return { items, total, page, pageSize };
     }
-    getMessageByUid(accountId, uid, folderId) {
-        const sql = folderId != null
-            ? "SELECT * FROM messages WHERE account_id = ? AND uid = ? AND folder_id = ?"
-            : "SELECT * FROM messages WHERE account_id = ? AND uid = ?";
-        const params = folderId != null ? [accountId, uid, folderId] : [accountId, uid];
-        const r = this.db.prepare(sql).get(...params);
-        if (!r)
-            return null;
+    /** Map a `messages` row to a MessageEnvelope. Exposes `uuid` (stable local
+     *  identity) and `bodyPath` (authoritative on-disk location) in addition
+     *  to the server-binding metadata. */
+    rowToEnvelope(r) {
         return {
             id: r.id,
             accountId: r.account_id,
             folderId: r.folder_id,
             uid: r.uid,
+            uuid: r.uuid || "",
             messageId: r.message_id || "",
             inReplyTo: r.in_reply_to || "",
             references: JSON.parse(r.refs || "[]"),
@@ -548,9 +619,33 @@ export class MailxDB {
             size: r.size,
             hasAttachments: !!r.has_attachments,
             preview: r.preview,
+            bodyPath: r.body_path || "",
             providerId: r.provider_id || undefined,
         };
     }
+    getMessageByUid(accountId, uid, folderId) {
+        const sql = folderId != null
+            ? "SELECT * FROM messages WHERE account_id = ? AND uid = ? AND folder_id = ?"
+            : "SELECT * FROM messages WHERE account_id = ? AND uid = ?";
+        const params = folderId != null ? [accountId, uid, folderId] : [accountId, uid];
+        const r = this.db.prepare(sql).get(...params);
+        if (!r)
+            return null;
+        return this.rowToEnvelope(r);
+    }
+    /** Look up a message by its stable local UUID. Returned envelope includes
+     *  the current (folder_id, uid) — these may have changed since the UUID
+     *  was minted (folder move or server UID renumber) but the UUID itself
+     *  is stable. Use this as the identity in any long-lived reference
+     *  (compose in-reply-to, dally, undo stacks). */
+    getMessageByUuid(uuid) {
+        if (!uuid)
+            return null;
+        const r = this.db.prepare("SELECT * FROM messages WHERE uuid = ?").get(uuid);
+        if (!r)
+            return null;
+        return this.rowToEnvelope(r);
+    }
     getMessageBodyPath(accountId, uid) {
         const r = this.db.prepare("SELECT body_path FROM messages WHERE account_id = ? AND uid = ?").get(accountId, uid);
         return r?.body_path || "";

package/packages/mailx-store/file-store.d.ts

@@ -1,18 +1,36 @@
 /**
  * File-per-message body storage backend.
- * Messages stored as: {basePath}/{accountId}/{folderId}/{uid}.eml
- * Folder IDs are numeric (from SQLite), not names.
+ *
+ * Disk layout: {basePath}/{accountId}/<xx>/<uuid>.eml
+ * Filename is an opaque UUID. Two-char prefix dir for filesystem fan-out.
+ *
+ * CRITICAL: the on-disk filename carries NO semantic meaning — not folder
+ * id, not UID, not Message-ID. A new UUID is minted on every `putMessage`.
+ * Moves, UID renumbers, UIDVALIDITY bumps cannot shadow a body because no
+ * filename is ever reused. DB's `body_path` column is the sole authority
+ * on where a given message's body lives.
  */
 import type { MessageStore } from "@bobfrankston/mailx-types";
 export declare class FileMessageStore implements MessageStore {
     private basePath;
     constructor(basePath: string);
-    private messagePath;
-    /** Public lookup of the on-disk path without touching the file. */
-    getMessagePath(accountId: string, folderId: number, uid: number): string;
-    putMessage(accountId: string, folderId: number, uid: number, raw: Buffer): Promise<string>;
-    getMessage(accountId: string, folderId: number, uid: number): Promise<Buffer>;
-    deleteMessage(accountId: string, folderId: number, uid: number): Promise<void>;
-    hasMessage(accountId: string, folderId: number, uid: number): Promise<boolean>;
+    /** Fresh opaque path per call. No inputs from the caller affect the name. */
+    private newMessagePath;
+    /** Verify a given path resolves inside this store's basePath — refuses
+     *  any value that doesn't (cheap directory-traversal guard). */
+    private inStore;
+    /** Write a new body. Always a fresh UUID path. Caller MUST persist the
+     *  returned path in the DB (`body_path`) and use it for all reads. The
+     *  (folderId, uid) args are kept for interface compatibility; they do
+     *  NOT affect the filename. */
+    putMessage(accountId: string, _folderId: number, _uid: number, raw: Buffer): Promise<string>;
+    /** Read by absolute path (DB `body_path`). The primary read API. */
+    readByPath(fullPath: string): Promise<Buffer>;
+    hasByPath(fullPath: string): Promise<boolean>;
+    unlinkByPath(fullPath: string): Promise<void>;
+    getMessagePath(_accountId: string, _folderId: number, _uid: number): string;
+    getMessage(_accountId: string, _folderId: number, _uid: number): Promise<Buffer>;
+    hasMessage(_accountId: string, _folderId: number, _uid: number): Promise<boolean>;
+    deleteMessage(_accountId: string, _folderId: number, _uid: number): Promise<void>;
 }
 //# sourceMappingURL=file-store.d.ts.map

package/packages/mailx-store/file-store.js

@@ -1,39 +1,80 @@
 /**
  * File-per-message body storage backend.
- * Messages stored as: {basePath}/{accountId}/{folderId}/{uid}.eml
- * Folder IDs are numeric (from SQLite), not names.
+ *
+ * Disk layout: {basePath}/{accountId}/<xx>/<uuid>.eml
+ * Filename is an opaque UUID. Two-char prefix dir for filesystem fan-out.
+ *
+ * CRITICAL: the on-disk filename carries NO semantic meaning — not folder
+ * id, not UID, not Message-ID. A new UUID is minted on every `putMessage`.
+ * Moves, UID renumbers, UIDVALIDITY bumps cannot shadow a body because no
+ * filename is ever reused. DB's `body_path` column is the sole authority
+ * on where a given message's body lives.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { randomUUID } from "node:crypto";
 export class FileMessageStore {
     basePath;
     constructor(basePath) {
         this.basePath = basePath;
         fs.mkdirSync(basePath, { recursive: true });
     }
-    messagePath(accountId, folderId, uid) {
-        return path.join(this.basePath, accountId, String(folderId), `${uid}.eml`);
+    /** Fresh opaque path per call. No inputs from the caller affect the name. */
+    newMessagePath(accountId) {
+        const uuid = randomUUID().replace(/-/g, "");
+        const prefix = uuid.slice(0, 2);
+        return path.join(this.basePath, accountId, prefix, `${uuid}.eml`);
     }
-    /** Public lookup of the on-disk path without touching the file. */
-    getMessagePath(accountId, folderId, uid) {
-        return this.messagePath(accountId, folderId, uid);
+    /** Verify a given path resolves inside this store's basePath — refuses
+     *  any value that doesn't (cheap directory-traversal guard). */
+    inStore(fullPath) {
+        if (!fullPath)
+            return false;
+        const rel = path.relative(path.resolve(this.basePath), path.resolve(fullPath));
+        return !rel.startsWith("..") && !path.isAbsolute(rel);
     }
-    async putMessage(accountId, folderId, uid, raw) {
-        const filePath = this.messagePath(accountId, folderId, uid);
+    /** Write a new body. Always a fresh UUID path. Caller MUST persist the
+     *  returned path in the DB (`body_path`) and use it for all reads. The
+     *  (folderId, uid) args are kept for interface compatibility; they do
+     *  NOT affect the filename. */
+    async putMessage(accountId, _folderId, _uid, raw) {
+        const filePath = this.newMessagePath(accountId);
         fs.mkdirSync(path.dirname(filePath), { recursive: true });
         fs.writeFileSync(filePath, raw);
         return filePath;
     }
-    async getMessage(accountId, folderId, uid) {
-        return fs.readFileSync(this.messagePath(accountId, folderId, uid));
+    /** Read by absolute path (DB `body_path`). The primary read API. */
+    async readByPath(fullPath) {
+        if (!this.inStore(fullPath))
+            throw new Error(`refusing to read outside store: ${fullPath}`);
+        return fs.readFileSync(fullPath);
     }
-    async deleteMessage(accountId, folderId, uid) {
-        const filePath = this.messagePath(accountId, folderId, uid);
-        if (fs.existsSync(filePath))
-            fs.unlinkSync(filePath);
+    async hasByPath(fullPath) {
+        if (!this.inStore(fullPath))
+            return false;
+        return fs.existsSync(fullPath);
     }
-    async hasMessage(accountId, folderId, uid) {
-        return fs.existsSync(this.messagePath(accountId, folderId, uid));
+    async unlinkByPath(fullPath) {
+        if (!this.inStore(fullPath))
+            return;
+        if (fs.existsSync(fullPath))
+            fs.unlinkSync(fullPath);
+    }
+    // MessageStore interface compatibility (unused once all callers migrate to
+    // path-based reads). These used to compose {folderId}/{uid}.eml and they
+    // would resurrect the comingling bug if restored. Kept as throwing stubs
+    // so any accidental caller surfaces loudly rather than silently misbehave.
+    getMessagePath(_accountId, _folderId, _uid) {
+        throw new Error("FileMessageStore.getMessagePath is retired — read body_path from DB");
+    }
+    async getMessage(_accountId, _folderId, _uid) {
+        throw new Error("FileMessageStore.getMessage(folder,uid) is retired — use readByPath(body_path)");
+    }
+    async hasMessage(_accountId, _folderId, _uid) {
+        throw new Error("FileMessageStore.hasMessage(folder,uid) is retired — use hasByPath(body_path)");
+    }
+    async deleteMessage(_accountId, _folderId, _uid) {
+        throw new Error("FileMessageStore.deleteMessage(folder,uid) is retired — use unlinkByPath(body_path)");
     }
 }
 //# sourceMappingURL=file-store.js.map

package/packages/mailx-types/index.d.ts

@@ -62,7 +62,8 @@ export interface MessageEnvelope {
     accountId: string;
     folderId: number;
     folderName?: string; /** Leaf folder name; populated by cross-folder search so the UI can tag each hit */
-    uid: number; /** IMAP UID */
+    uid: number; /** IMAP UID (server-side identity; changes on move, UIDVALIDITY bump) */
+    uuid?: string; /** Stable local identity, minted once at first-sight; never changes */
     messageId: string; /** RFC Message-ID header */
     inReplyTo: string; /** For threading */
     references: string[]; /** For threading */
@@ -78,6 +79,7 @@ export interface MessageEnvelope {
     preview: string; /** First ~200 chars of body text */
     bodyPath?: string; /** Local body location: "idb:..." or "gmail:<id>" */
     providerId?: string; /** Native server id (Gmail hex id, Outlook Graph id) — bypasses UID→id pagination on body fetch */
+    pending?: boolean; /** True when a queued local action (move/flag/delete) hasn't been ACK'd by the server yet — UI renders pink */
 }
 /** Full message with body content */
 export interface Message extends MessageEnvelope {

package/todo.json

@@ -0,0 +1,13 @@
+{
+  "url": "file:///Y:/dev/email/mailx/TODO.md",
+  "size": {
+    "width": 1000,
+    "height": 1200
+  },
+  "pos": {
+    "x": 100,
+    "y": 100,
+    "screen": 1
+  },
+  "detach": true
+}