@bobfrankston/mailx-imap 0.1.167 → 0.1.170

package/index.d.ts

@@ -237,6 +237,7 @@ export declare class ImapManager extends EventEmitter {
         slow?: boolean;
         lane?: string;
         timeoutMs?: number;
+        priority?: boolean;
     }): Promise<T>;
     /** Drain the next queued task on EVERY lane for the account. Lanes run
      *  concurrently — each on its own connection — and the per-lane running

package/index.js

@@ -7,7 +7,7 @@ import { createAutoImapConfig, CompatImapClient } from "@bobfrankston/iflow-dire
 import { authenticateOAuth, clearReauthBackoff } from "@bobfrankston/oauthsupport";
 import { parseSerial, fixCharsetDeclString, storeBus } from "@bobfrankston/mailx-store";
 import { loadSettings, getConfigDir, getHistoryDays, getPrefetch, tokenDirName } from "@bobfrankston/mailx-settings";
-import { isJunkPreviewText } from "@bobfrankston/mailx-types";
+import { isJunkPreviewText, logIfChanged } from "@bobfrankston/mailx-types";
 import { EventEmitter } from "node:events";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -874,7 +874,19 @@ export class ImapManager extends EventEmitter {
                     reject(e);
                 }
             };
-            queue.tasks.push(task);
+            // A task the user is waiting on goes to the FRONT of its lane.
+            // Lanes are strictly sequential, so without this a click-time body
+            // fetch sits behind whatever background work was queued first and
+            // can only start after all of it — Bob 2026-08-29: "if I look at a
+            // letter while sync things get confused … viewing the body should
+            // get priority instead of waiting for sync". It cannot preempt the
+            // command already in flight (an IMAP command cannot be cancelled
+            // without dropping the connection), but it no longer waits for the
+            // whole backlog.
+            if (opts.priority)
+                queue.tasks.unshift(task);
+            else
+                queue.tasks.push(task);
             this.drainOpsQueue(accountId);
         });
     }
@@ -2405,10 +2417,13 @@ export class ImapManager extends EventEmitter {
                     && statusMessageCount !== null
                     && serverUidsArr.length === statusMessageCount;
                 if (serverUidsArr.length === 0 && localUidsAll.length > 0 && !authoritative) {
-                    console.log(`  [sync] ${accountId}/${folder.path}: reconcile skipped — server UID list empty but local has ${localUidsAll.length} (treating as transient)`);
+                    // Same line every cycle for a folder stuck in this state —
+                    // logIfChanged prints the first one, each change, and an
+                    // hourly restatement. (Claude Code 2026-08-29)
+                    logIfChanged(`${accountId}/${folder.path}:reconcile`, `  [sync] ${accountId}/${folder.path}: reconcile skipped — server UID list empty but local has ${localUidsAll.length} (treating as transient)`);
                 }
                 else if (!authoritative && localUids.length > 0 && toDelete.length / localUids.length > 0.5) {
-                    console.log(`  [sync] ${accountId}/${folder.path}: reconcile REFUSED — would delete ${toDelete.length}/${localUids.length} (${Math.round(toDelete.length / localUids.length * 100)}%) — probably a sync bug, skipping`);
+                    logIfChanged(`${accountId}/${folder.path}:reconcile`, `  [sync] ${accountId}/${folder.path}: reconcile REFUSED — would delete ${toDelete.length}/${localUids.length} (${Math.round(toDelete.length / localUids.length * 100)}%) — probably a sync bug, skipping`);
                 }
                 else if (toDelete.length > 0) {
                     // DEFERRED DELETE — DO NOT delete immediately. Server-side
@@ -2888,10 +2903,10 @@ export class ImapManager extends EventEmitter {
             const serverUids = new Set(serverUidsArr);
             const localUids = this.db.getUidsForFolder(accountId, folder.id);
             if (serverUidsArr._truncated) {
-                console.log(`  [api] ${accountId}/${folder.path}: reconcile skipped — server list truncated (${serverUidsArr.length} ids)`);
+                logIfChanged(`${accountId}/${folder.path}:api-reconcile`, `  [api] ${accountId}/${folder.path}: reconcile skipped — server list truncated (${serverUidsArr.length} ids)`);
             }
             else if (serverUidsArr.length === 0 && localUids.length > 0) {
-                console.log(`  [api] ${accountId}/${folder.path}: reconcile skipped — server list empty but local has ${localUids.length}`);
+                logIfChanged(`${accountId}/${folder.path}:api-reconcile`, `  [api] ${accountId}/${folder.path}: reconcile skipped — server list empty but local has ${localUids.length}`);
             }
             else {
                 const toDelete = localUids.filter(uid => !serverUids.has(uid));
@@ -2925,7 +2940,7 @@ export class ImapManager extends EventEmitter {
                     }
                 }
                 if (!confirmed) {
-                    console.log(`  [api] ${accountId}/${folder.path}: reconcile refused — would delete ${toDelete.length}/${localUids.length} (${Math.round(toDelete.length / localUids.length * 100)}%) — probably a sync bug, skipping`);
+                    logIfChanged(`${accountId}/${folder.path}:api-reconcile`, `  [api] ${accountId}/${folder.path}: reconcile refused — would delete ${toDelete.length}/${localUids.length} (${Math.round(toDelete.length / localUids.length * 100)}%) — probably a sync bug, skipping`);
                 }
                 else {
                     for (const uid of toDelete) {
@@ -3511,10 +3526,41 @@ export class ImapManager extends EventEmitter {
                         this.syncFolder(accountId, inbox.id).catch(e => console.error(`  [idle] expunge reconcile failed: ${e.message}`));
                     }, 2000);
                 };
+                // A flag changed on a message we already have — someone starred
+                // or read it on another client. The server pushes it during
+                // IDLE as an unsolicited FETCH; before v1.2.296 that was
+                // dropped, so a star set on the phone reached the desktop only
+                // on the next periodic sync of INBOX. Measured on Bob's own
+                // log that was a median of 5 minutes and up to 20 (Bob
+                // 2026-08-29: "how long should it take for a * on the phone to
+                // get to my desktop?").
+                //
+                // The push says WHICH flags but by sequence number, which this
+                // connection cannot map to a UID reliably — so it triggers the
+                // folder's normal QRESYNC pass, which asks the server for
+                // exactly what changed since our modseq and took 53 ms in the
+                // same log. Debounced: marking ten messages read on the phone
+                // arrives as ten pushes.
+                let flagTimer = null;
+                const onFlagChange = () => {
+                    if (flagTimer)
+                        clearTimeout(flagTimer);
+                    flagTimer = setTimeout(() => {
+                        flagTimer = null;
+                        // Our own STOREs bounce straight back as flag pushes;
+                        // the local store already has those.
+                        if (this.db.getPendingSyncActions(accountId).length > 0)
+                            return;
+                        const inbox = this.db.getFolders(accountId).find(f => f.specialUse === "inbox");
+                        if (!inbox)
+                            return;
+                        this.syncFolder(accountId, inbox.id).catch(e => console.error(`  [idle] flag-change sync failed: ${e.message}`));
+                    }, 1500);
+                };
                 const stop = await watchClient.watchMailbox("INBOX", (newCount) => {
                     console.log(`  [idle] ${accountId}: ${newCount} new message(s)`);
                     this.syncInboxNewOnly(accountId).catch(e => console.error(`  [idle] sync error: ${e.message}`));
-                }, { notifySpec, onMailboxStatus, onExpunge });
+                }, { notifySpec, onMailboxStatus, onExpunge, onFlagChange });
                 this.watchers.set(accountId, async () => {
                     await stop();
                     await watchClient.logout();
@@ -3728,6 +3774,13 @@ export class ImapManager extends EventEmitter {
         // IMAP: fast lane on the ops queue. One try; if the socket is stale,
         // withConnection's discard-on-error logic drops the client so the
         // next attempt (caller-driven retry) gets a fresh one.
+        //
+        // An interactive fetch (`force`) jumps the lane queue and gets a
+        // tighter cap: the reader is staring at a blank pane, and 90 s of
+        // silence followed by a banner is the worst of both. 30 s is long
+        // enough for a big body on a slow server and short enough that a
+        // wedged lane becomes a RETRYABLE timeout while the reader is still
+        // looking at the message.
         try {
             const raw = await this.withConnection(accountId, async (client) => {
                 const msg = await client.fetchMessageByUid(folder.path, uid, { source: true });
@@ -3736,7 +3789,7 @@ export class ImapManager extends EventEmitter {
                 if (!msg.source)
                     return null;
                 return Buffer.from(msg.source, "utf-8");
-            });
+            }, force ? { priority: true, timeoutMs: 30_000 } : {});
             if (!raw)
                 return null;
             const bodyPath = await this.bodyStore.putMessage(accountId, folderId, uid, raw);
@@ -3751,8 +3804,19 @@ export class ImapManager extends EventEmitter {
             if (e?.isNotFound)
                 throw e;
             console.error(`  Body fetch error (${accountId}/${uid}): ${e?.message || e}`);
-            // Record so the next view / prefetch backs off instead of
-            // re-attempting a hanging fetch and re-congesting the queue.
+            // A lane timeout / dropped socket says nothing about whether this
+            // message HAS a body. Swallowing it into `null` told the caller
+            // "the server has no body for this" — the reconciler classifies
+            // that as non-transient, skips its retry budget, and banners.
+            // That is the "eventually reports an error rather than retrying"
+            // Bob hit (2026-08-29). Rethrow instead, so the reconciler's
+            // transient test sees the word "timeout" and retries with backoff.
+            const transient = /timeout|discarding client|connection|not connected|ECONN|ETIMEDOUT|ENOTFOUND|socket/i
+                .test(String(e?.message || ""));
+            if (transient)
+                throw e;
+            // A genuine "no body here" — arm the backoff so prefetch and the
+            // next view don't re-attempt a fetch the server won't satisfy.
             try {
                 this.markPrefetchEmpty(accountId, folderId, uid);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-imap",
-  "version": "0.1.167",
+  "version": "0.1.170",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
@@ -9,10 +9,10 @@
   },
   "license": "ISC",
   "dependencies": {
-    "@bobfrankston/mailx-types": "^0.1.73",
-    "@bobfrankston/mailx-settings": "^0.1.70",
-    "@bobfrankston/mailx-store": "^0.1.107",
-    "@bobfrankston/iflow-direct": "^0.1.65",
+    "@bobfrankston/mailx-types": "^0.1.76",
+    "@bobfrankston/mailx-settings": "^0.1.73",
+    "@bobfrankston/mailx-store": "^0.1.109",
+    "@bobfrankston/iflow-direct": "^0.1.68",
     "@bobfrankston/tcp-transport": "^0.1.8",
     "@bobfrankston/smtp-direct": "^0.1.9",
     "@bobfrankston/mailx-sync": "^0.1.29",
@@ -37,10 +37,10 @@
   },
   ".transformedSnapshot": {
     "dependencies": {
-      "@bobfrankston/mailx-types": "^0.1.73",
-      "@bobfrankston/mailx-settings": "^0.1.70",
-      "@bobfrankston/mailx-store": "^0.1.107",
-      "@bobfrankston/iflow-direct": "^0.1.65",
+      "@bobfrankston/mailx-types": "^0.1.76",
+      "@bobfrankston/mailx-settings": "^0.1.73",
+      "@bobfrankston/mailx-store": "^0.1.109",
+      "@bobfrankston/iflow-direct": "^0.1.68",
       "@bobfrankston/tcp-transport": "^0.1.8",
       "@bobfrankston/smtp-direct": "^0.1.9",
       "@bobfrankston/mailx-sync": "^0.1.29",