apple-mail-mcp 2.19.16 → 2.19.18

package/README.md

@@ -280,19 +280,27 @@ human reader; the same information is also returned as structured fields on
 `search-messages` and `list-messages`, so a caller can tell _"nothing matched"_
 apart from _"I did not look everywhere"_ without parsing the text:
 
-| Field                   | Type     | Meaning                                                                                                                                                                            |
-| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `partial`               | boolean  | Coverage was incomplete — **the result is not a confirmed "no such mail"**. True whenever any field below is non-empty.                                                            |
-| `skippedLargeMailboxes` | string[] | Mailboxes never scanned because their message count exceeded `APPLE_MAIL_MAX_SEARCH_MAILBOX`, formatted `"Account / Mailbox (count)"` — e.g. `"iCloud / Archive (90694)"`.         |
-| `notSearchedMailboxes`  | string[] | Mailboxes that _were_ reached but timed out or errored mid-scan, formatted `"Account / Mailbox"`. Also carries the IMAP path's `failedMailboxes`.                                  |
-| `timedOutAccounts`      | string[] | Accounts whose whole-account AppleScript was killed by the per-account time budget — nothing from that account was searched.                                                       |
-| `failedMailboxes`       | string[] | IMAP-backend mailboxes that errored. These are merged into `notSearchedMailboxes` as well; read that field unless you need to attribute the failure to the IMAP path specifically. |
+| Field                   | Type     | Meaning                                                                                                                                                                                                                                                                                                               |
+| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `partial`               | boolean  | Coverage was incomplete — **the result is not a confirmed "no such mail"**. True whenever any field below is non-empty.                                                                                                                                                                                               |
+| `skippedLargeMailboxes` | string[] | Mailboxes never scanned because their message count exceeded `APPLE_MAIL_MAX_SEARCH_MAILBOX`, formatted `"Account / Mailbox (count)"` — e.g. `"iCloud / Archive (90694)"`.                                                                                                                                            |
+| `notSearchedMailboxes`  | string[] | Mailboxes that _were_ reached but timed out or errored mid-scan, formatted `"Account / Mailbox"`. Also carries the IMAP path's `failedMailboxes`.                                                                                                                                                                     |
+| `timedOutAccounts`      | string[] | Accounts whose whole-account AppleScript was killed by the per-account time budget — nothing from that account was searched.                                                                                                                                                                                          |
+| `failedMailboxes`       | string[] | IMAP-backend mailboxes that errored. These are merged into `notSearchedMailboxes` as well; read that field unless you need to attribute the failure to the IMAP path specifically.                                                                                                                                    |
+| `failedMailboxReasons`  | object   | The IMAP server's own error text for each entry in `failedMailboxes`, keyed the same way.                                                                                                                                                                                                                             |
+| `omittedMessages`       | object[] | IMAP messages that belong on the page but whose `FETCH` response could not be read even with a reduced item set — `{ id, mailbox, uid, reason }`. The page is short by exactly these; the `id` still works with `get-message` / `get-message-headers`. ([#256](https://github.com/sweetrb/apple-mail-mcp/issues/256)) |
 
 Treat a non-empty `skippedLargeMailboxes` as actionable rather than
 informational: re-run scoped to the named mailbox with a `dateFrom`/`dateTo`
 window, or configure the [IMAP backend](#imap-backend--opt-in), which searches
-those mailboxes server-side. All five fields are optional and are omitted when
-coverage was complete.
+those mailboxes server-side. The list fields are optional and are omitted (or
+empty) when coverage was complete.
+
+A row the IMAP backend could only read with a reduced item set (its full
+`BODYSTRUCTURE`, or its whole `FETCH` response, was unparseable — e.g. a message
+forwarded as an attachment many levels deep) is still returned, with a
+`metadataIncomplete` note saying what was missing; its `hasAttachments` is then
+inferred from the top-level `Content-Type`.
 
 ---
 
@@ -826,7 +834,7 @@ Reply to an existing message.
 | Parameter   | Type    | Required | Description                                                                                    |
 | ----------- | ------- | -------- | ---------------------------------------------------------------------------------------------- |
 | `id`        | string  | Yes      | Message ID to reply to                                                                         |
-| `body`      | string  | Yes      | Reply body (plain text; HTML tags such as `<br>` are not rendered)                              |
+| `body`      | string  | Yes      | Reply body (plain text; HTML tags such as `<br>` are not rendered)                             |
 | `replyAll`  | boolean | No       | Reply to all recipients (default: false)                                                       |
 | `send`      | boolean | No       | Send immediately (default: true, false = save as draft)                                        |
 | `transport` | string  | No       | `smtp` or `applescript`; omitted prefers configured SMTP when sending. Drafts use AppleScript. |
@@ -1081,17 +1089,31 @@ Matching ignores letter case **and Unicode normalization form**: a typed
 precomposed `México` (NFC) finds a mailbox the server stores decomposed (NFD —
 common for folders created on a Mac, and what iCloud keeps), and the server's
 own stored spelling is what gets selected. Two mailboxes whose names differ
-*only* in case or normalization look identical in any listing, so a name that
+_only_ in case or normalization look identical in any listing, so a name that
 matches both is refused with an error saying so — rename one of them. For the
 same reason `create-mailbox` treats a normalization-equivalent existing name as
 already existing, and `rename-mailbox` refuses to create such a twin.
 
 **Messages awaiting expunge are not listed.** On IMAP accounts, search,
-list, thread and mail-stats queries only match messages *not* flagged
+list, thread and mail-stats queries only match messages _not_ flagged
 `\Deleted` (IMAP `UNDELETED`). iCloud keeps flagged-but-never-expunged
 messages out of its message counts yet still returns them from `UID SEARCH`,
 which made a filter-less `list-messages` fail on such a mailbox before 2.19.16.
 
+**Very large IMAP mailboxes are read newest-first in bounded windows**
+([#256](https://github.com/sweetrb/apple-mail-mcp/issues/256)). Above 10,000
+messages, a filter-less `list-messages`/`search-messages` pages by message
+sequence number from the top of the mailbox — it fetches UIDs and flags for
+just enough of the newest messages to fill `limit` + `offset` (skipping
+`\Deleted` ones) and full rows for the page alone, so `limit: 1` on a
+793,614-message mailbox costs one small `FETCH`, not a whole-mailbox `SEARCH`.
+A filtered search there runs the same criteria over newest-first sequence
+windows (5,000 messages, growing to 50,000) and stops once the page is full;
+the reported total then reads `at least N` unless the walk reached the bottom
+of the mailbox. A `SEARCH` or `FETCH` that fails names the mailbox, its size and
+the server's own reason (or a likely timeout) instead of reporting "no
+messages".
+
 **Mail's local "On My Mac" mailboxes** are not children of any account — they
 hang off the application — so they are reported under the synthetic account label
 **`On My Mac`**. An unscoped call includes them (listed last); `account="On My

package/build/cli.js

@@ -58045,6 +58045,7 @@ var imapClient_exports = {};
 __export(imapClient_exports, {
   HEADER_WINDOW_BYTES: () => HEADER_WINDOW_BYTES,
   IMAP_ENV: () => IMAP_ENV,
+  LARGE_MAILBOX_MESSAGES: () => LARGE_MAILBOX_MESSAGES,
   MAX_COMPOSE_SOURCE_BYTES: () => MAX_COMPOSE_SOURCE_BYTES,
   MAX_RFC822_FILE_BYTES: () => MAX_RFC822_FILE_BYTES,
   MAX_RFC822_INLINE_BYTES: () => MAX_RFC822_INLINE_BYTES,
@@ -58091,6 +58092,7 @@ __export(imapClient_exports, {
   mailFlagColorIndex: () => mailFlagColorIndex,
   matchMailbox: () => matchMailbox,
   normalizeMessageId: () => normalizeMessageId,
+  omittedNote: () => omittedNote,
   resolveImapConfig: () => resolveImapConfig,
   resolveImapConfigs: () => resolveImapConfigs,
   resolveMailboxPath: () => resolveMailboxPath,
@@ -58401,7 +58403,12 @@ function structuredRow(m, account, path) {
     // a caller from "no attachments", so every IMAP-sourced message claimed to
     // have none. Falls back to false only when the fetch carried no
     // BODYSTRUCTURE at all.
-    hasAttachments: bodyStructureHasAttachments(m.bodyStructure),
+    // A row read without BODYSTRUCTURE (#256 follow-up) judges by its top-level
+    // Content-Type instead, and says so in `metadataIncomplete`.
+    hasAttachments: m.bodyStructure ? bodyStructureHasAttachments(m.bodyStructure) : m.degraded ? contentTypeSuggestsAttachments(m) : false,
+    ...m.degraded ? {
+      metadataIncomplete: m.degraded === "bodystructure" ? "BODYSTRUCTURE unreadable; hasAttachments inferred from Content-Type" : "FETCH response unreadable; row rebuilt from raw headers, hasAttachments inferred from Content-Type"
+    } : {},
     // Message-ID (when the envelope carries it) is the strongest cross-/intra-
     // backend dedup key for the multi-account merge (imapMultiAccount.ts). The
     // AppleScript path does not expose it, so cross-backend dedup falls back to
@@ -58409,6 +58416,13 @@ function structuredRow(m, account, path) {
     ...env.messageId ? { messageId: env.messageId } : {}
   };
 }
+function omittedNote(omitted, merged) {
+  if (omitted.length === 0) return "";
+  const list = omitted.map((o) => `UID ${o.uid} in "${o.mailbox}" (${o.id})`).join(", ");
+  return `
+
+Partial result. ${omitted.length} message(s) ${merged ? "that may belong" : "that belong"} on this page could not be read and are not listed: ${list}. Reason: ${[...new Set(omitted.map((o) => o.reason))].join("; ")}. get-message or get-message-headers with those ids may still read them.`;
+}
 function describeMailboxFailure(error) {
   const raw = errText(error);
   const oneLine = raw.split("\n")[0].trim();
@@ -58428,44 +58442,215 @@ function messageIdentity(entry) {
   const messageId = raw.replace(/^<+|>+$/g, "").trim().toLowerCase();
   return messageId ? `mid:${messageId}` : `${entry.path}\0${entry.message.uid}`;
 }
-async function fetchMailboxMatches(client, path, criteria, newestCount) {
-  const lock = await client.getMailboxLock(path);
+function isUnfiltered(criteria) {
+  const keys = Object.keys(criteria);
+  return keys.length === 1 && criteria.deleted === false;
+}
+async function statusMessageCount(client, path) {
   try {
-    const found = await client.search(criteria, { uid: true });
-    const uids = Array.isArray(found) ? found : [];
-    if (uids.length === 0 || newestCount === 0) return { messages: [], total: uids.length };
-    const status = await client.status(path, { messages: true });
-    if (typeof status.messages === "number" && uids.length > status.messages) {
+    const st = await client.status(path, { messages: true });
+    return typeof st.messages === "number" && st.messages >= 0 ? st.messages : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function searchUids(client, path, criteria, size) {
+  client.takeLastCommandError?.();
+  const found = await client.search(criteria, { uid: true });
+  if (Array.isArray(found)) return found;
+  const cause = client.takeLastCommandError?.();
+  const sized = size === void 0 ? "" : ` (${size.toLocaleString("en-US")} messages)`;
+  throw new Error(
+    `IMAP SEARCH on "${path}"${sized} failed: ` + (cause ? errText(cause) : "the server rejected it or the connection dropped before it answered (on a mailbox this size, usually a server-side timeout)")
+  );
+}
+function mergeFetched(into, msg) {
+  const prev = into.get(msg.uid);
+  if (!prev) {
+    into.set(msg.uid, msg);
+    return;
+  }
+  const merged = { ...prev };
+  for (const [key, value] of Object.entries(msg)) {
+    if (value !== void 0 && value !== null)
+      merged[key] = value;
+  }
+  into.set(msg.uid, merged);
+}
+async function fetchInto(client, uids, query, into) {
+  const wanted = new Set(uids);
+  for await (const msg of client.fetch(uids.join(","), query, { uid: true })) {
+    if (typeof msg?.uid === "number" && wanted.has(msg.uid)) mergeFetched(into, msg);
+  }
+}
+function fetchedHeaders(m) {
+  return m.headers ? parseHeaderBlock(decodeHeaderBytes(asBuffer(m.headers))) : void 0;
+}
+function envelopeFromHeaders(m) {
+  const h = fetchedHeaders(m);
+  if (!h || h.headers.length === 0) return void 0;
+  const env = {};
+  if (h.subject) env.subject = h.subject;
+  if (h.from) {
+    const angle = h.from.match(/^\s*"?([^"<]*?)"?\s*<([^>]+)>/);
+    env.from = angle ? [{ ...angle[1].trim() ? { name: angle[1].trim() } : {}, address: angle[2].trim() }] : [{ address: h.from.trim() }];
+  }
+  if (h.messageId) env.messageId = `<${h.messageId}>`;
+  if (h.inReplyTo) env.inReplyTo = `<${h.inReplyTo}>`;
+  if (h.dateHeader) env.date = h.dateHeader;
+  return env;
+}
+function contentTypeSuggestsAttachments(m) {
+  const type = fetchedHeaders(m)?.headers.find((h) => h.name.toLowerCase() === "content-type");
+  return /^\s*multipart\/mixed\b/i.test(type?.value ?? "");
+}
+async function fetchRows(client, uids) {
+  if (uids.length === 0) return { messages: [], omitted: [] };
+  const byUid = /* @__PURE__ */ new Map();
+  const causes = [];
+  const noteCause = () => {
+    const err = client.takeLastCommandError?.();
+    if (err !== void 0) {
+      const text = describeMailboxFailure(err);
+      if (!causes.includes(text)) causes.push(text);
+    }
+  };
+  const missing = () => uids.filter((uid) => !byUid.get(uid)?.envelope);
+  client.takeLastCommandError?.();
+  await fetchInto(client, uids, ROW_QUERY, byUid);
+  noteCause();
+  let gap = missing();
+  if (gap.length > 0) {
+    await fetchInto(client, gap, ROW_QUERY, byUid);
+    noteCause();
+    gap = missing();
+  }
+  if (gap.length > 0) {
+    const reduced = /* @__PURE__ */ new Map();
+    await fetchInto(client, gap, ROW_QUERY_NO_STRUCTURE, reduced);
+    noteCause();
+    for (const msg of reduced.values()) {
+      if (!msg.envelope) continue;
+      mergeFetched(byUid, { ...msg, degraded: "bodystructure" });
+    }
+    gap = missing();
+  }
+  if (gap.length > 0) {
+    for (const uid of gap) {
+      const bare = /* @__PURE__ */ new Map();
+      await fetchInto(client, [uid], ROW_QUERY_HEADERS_ONLY, bare);
+      noteCause();
+      const msg = bare.get(uid);
+      const envelope = msg ? envelopeFromHeaders(msg) : void 0;
+      if (msg && envelope) {
+        mergeFetched(byUid, { ...msg, envelope, degraded: "envelope" });
+      }
+    }
+    gap = missing();
+  }
+  const omitted = new Set(gap);
+  return {
+    messages: uids.filter((uid) => !omitted.has(uid)).map((uid) => byUid.get(uid)).filter((message) => message !== void 0),
+    omitted: gap,
+    ...causes.length > 0 ? { cause: causes.join("; ") } : {}
+  };
+}
+function pageRows(fetch) {
+  return {
+    messages: fetch.messages,
+    omitted: fetch.omitted,
+    ...fetch.omitted.length > 0 ? { omittedReason: omissionReason(fetch) } : {}
+  };
+}
+function omissionReason(fetch) {
+  return "the server's FETCH response for this message could not be read, even without BODYSTRUCTURE or ENVELOPE" + (fetch.cause ? ` (${fetch.cause})` : "");
+}
+async function walkWindows(exists, page, firstWindow, readWindow) {
+  const wanted = page.skip + page.take;
+  const uids = [];
+  let seen = 0;
+  let matched = 0;
+  let hi = exists;
+  let width = Math.max(1, Math.min(firstWindow, MAX_WINDOW));
+  while (hi >= 1 && seen < wanted) {
+    const lo = Math.max(1, hi - width + 1);
+    const live = (await readWindow(lo, hi === exists ? "*" : hi, hi - lo + 1)).slice().sort((a, b) => b - a);
+    matched += live.length;
+    for (const uid of live) {
+      if (seen >= wanted) break;
+      if (seen >= page.skip) uids.push(uid);
+      seen++;
+    }
+    hi = lo - 1;
+    width = Math.min(width * 4, MAX_WINDOW);
+  }
+  return { uids, matched, exhausted: hi < 1 };
+}
+async function listLargeMailbox(client, exists, page) {
+  let deletedSeen = 0;
+  const walk = await walkWindows(
+    exists,
+    page,
+    // Room for a few ghosts on the first read without a second round trip.
+    page.skip + page.take + 64,
+    async (lo, hi) => {
+      const live = [];
+      for await (const msg of client.fetch(`${lo}:${hi}`, { uid: true, flags: true })) {
+        if (msg.flags?.has("\\Deleted")) deletedSeen++;
+        else live.push(msg.uid);
+      }
+      return live;
+    }
+  );
+  return {
+    ...pageRows(await fetchRows(client, walk.uids)),
+    total: Math.max(0, exists - deletedSeen),
+    totalExact: true
+  };
+}
+async function searchLargeMailbox(client, path, criteria, exists, page) {
+  const walk = await walkWindows(exists, page, FIRST_SEARCH_WINDOW, async (lo, hi, width) => {
+    const found = await searchUids(client, path, { ...criteria, seq: `${lo}:${hi}` }, exists);
+    if (found.length > width) {
       throw new Error(
-        `IMAP SEARCH on "${path}" reported ${uids.length} matches, more than the mailbox's own ${status.messages} messages \u2014 discarding as corrupted rather than trusting it (see #246).`
+        `IMAP SEARCH on "${path}" reported ${found.length} matches in a ${width}-message window \u2014 discarding as corrupted rather than trusting it (see #246).`
       );
     }
-    const newest = uids.slice().reverse().slice(0, newestCount);
-    const byUid = /* @__PURE__ */ new Map();
-    for await (const msg of client.fetch(
-      newest.join(","),
-      // BODYSTRUCTURE rides along so `hasAttachments` is computed rather
-      // than assumed. Measured on 50 real messages: ~390ms -> ~465ms for
-      // the fetch (~17%), same single round trip, no extra request.
-      //
-      // INTERNALDATE rides along for the same reason, and is why `dateReceived`
-      // can finally mean what it says: imapflow's `envelope.date` is built from
-      // the header block, so it IS the `Date:` header, not arrival time.
-      //
-      // The `Date:` header itself (BODY.PEEK[HEADER.FIELDS (DATE)]) rides in the
-      // SAME FETCH command, so a date the server's ENVELOPE parser rejected can
-      // still be recovered (#234). Measured on 50 real messages, 6 alternating
-      // runs: median ~334ms without vs ~315ms with — inside the noise — for ~44
-      // bytes per message. Too cheap to hide behind an opt-in.
-      { envelope: true, flags: true, bodyStructure: true, internalDate: true, headers: ["date"] },
-      { uid: true }
-    )) {
-      byUid.set(msg.uid, msg);
+    return found;
+  });
+  return {
+    ...pageRows(await fetchRows(client, walk.uids)),
+    total: walk.matched,
+    totalExact: walk.exhausted
+  };
+}
+async function fetchMailboxMatches(client, path, criteria, page) {
+  const lock = await client.getMailboxLock(path);
+  try {
+    const exists = await statusMessageCount(client, path);
+    if (exists === 0) return { messages: [], omitted: [], total: 0, totalExact: true };
+    if (exists !== void 0 && exists > LARGE_MAILBOX_MESSAGES) {
+      try {
+        return isUnfiltered(criteria) ? await listLargeMailbox(client, exists, page) : await searchLargeMailbox(client, path, criteria, exists, page);
+      } catch (error) {
+        const detail = errText(error);
+        throw new Error(
+          detail.includes(`"${path}" (`) ? detail : `reading the newest messages of "${path}" (${exists.toLocaleString("en-US")} messages) failed: ${detail}`
+        );
+      }
     }
-    return {
-      messages: newest.map((uid) => byUid.get(uid)).filter((message) => message !== void 0),
-      total: uids.length
-    };
+    const uids = await searchUids(client, path, criteria, exists);
+    if (uids.length === 0 || page.take === 0) {
+      return { messages: [], omitted: [], total: uids.length, totalExact: true };
+    }
+    const messages = exists ?? (await client.status(path, { messages: true })).messages ?? void 0;
+    if (typeof messages === "number" && uids.length > messages) {
+      throw new Error(
+        `IMAP SEARCH on "${path}" reported ${uids.length} matches, more than the mailbox's own ${messages} messages \u2014 discarding as corrupted rather than trusting it (see #246).`
+      );
+    }
+    const newest = uids.slice().reverse().slice(page.skip, page.skip + page.take);
+    return { ...pageRows(await fetchRows(client, newest)), total: uids.length, totalExact: true };
   } finally {
     lock.release();
   }
@@ -58494,16 +58679,27 @@ async function run(args, listMode, deps) {
       const limit = args.limit ?? 50;
       const offset = args.offset ?? 0;
       const criteria = buildCriteria(args, listMode);
-      const newestPerMailbox = offset + limit;
+      const page = unscopedSearch ? { skip: 0, take: offset + limit } : { skip: offset, take: limit };
       const fetched = [];
       const failedMailboxes = [];
       const failedMailboxReasons = {};
+      const omittedMessages = [];
       let totalMatched = 0;
+      let totalExact = true;
       for (const path of paths) {
         try {
-          const result = await fetchMailboxMatches(client, path, criteria, newestPerMailbox);
+          const result = await fetchMailboxMatches(client, path, criteria, page);
           totalMatched += result.total;
+          totalExact &&= result.totalExact;
           fetched.push(...result.messages.map((message) => ({ message, path })));
+          for (const uid of result.omitted) {
+            omittedMessages.push({
+              id: encodeImapId(cfg.accountLabel, path, uid),
+              mailbox: path,
+              uid,
+              reason: result.omittedReason ?? "the server's FETCH response could not be read"
+            });
+          }
         } catch (error) {
           failedMailboxes.push(path);
           failedMailboxReasons[path] = describeMailboxFailure(error);
@@ -58527,18 +58723,17 @@ async function run(args, listMode, deps) {
           if (!unique.has(key)) unique.set(key, entry);
         }
         ordered = [...unique.values()].slice(offset, offset + limit);
-      } else {
-        ordered = fetched.slice(offset, offset + limit);
       }
       const rows = ordered.map(({ message, path }) => formatRow(message, cfg.accountLabel, path));
       const messages = ordered.map(
         ({ message, path }) => structuredRow(message, cfg.accountLabel, path)
       );
-      const partial = failedMailboxes.length > 0;
-      const failureNote = partial ? `
+      const partial = failedMailboxes.length > 0 || omittedMessages.length > 0;
+      const failureNote = (failedMailboxes.length > 0 ? `
 
-Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"${path}" (${failedMailboxReasons[path]})`).join(", ")}.` : "";
+Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"${path}" (${failedMailboxReasons[path]})`).join(", ")}.` : "") + omittedNote(omittedMessages, unscopedSearch);
       const verb = listMode ? "listed" : "matched";
+      const totalText = totalExact ? `${totalMatched} total` : `at least ${totalMatched} total`;
       const scope = unscopedSearch ? allMailboxCount === 1 ? `mailbox "${paths[0]}"` : `${allMailboxCount} selectable mailboxes` : `mailbox "${paths[0]}"`;
       if (messages.length === 0) {
         return {
@@ -58547,10 +58742,11 @@ Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"
           count: 0,
           partial,
           failedMailboxes,
-          failedMailboxReasons
+          failedMailboxReasons,
+          omittedMessages
         };
       }
-      const text = `Found ${rows.length} message(s) via IMAP (server-side, account ${cfg.accountLabel}, ${scope}; ${totalMatched} total ${verb}):
+      const text = `Found ${rows.length} message(s) via IMAP (server-side, account ${cfg.accountLabel}, ${scope}; ${totalText} ${verb}):
 ` + rows.join("\n") + `
 
 Note: these IMAP IDs (imap:\u2026) work with get-message and the message mutations (mark/flag/move/delete-message), which route back to IMAP.` + failureNote;
@@ -58560,7 +58756,8 @@ Note: these IMAP IDs (imap:\u2026) work with get-message and the message mutatio
         count: messages.length,
         partial,
         failedMailboxes,
-        failedMailboxReasons
+        failedMailboxReasons,
+        omittedMessages
       };
     },
     true
@@ -59520,31 +59717,21 @@ async function imapThread(id, deps = {}, limit = 50) {
         }
         if (uidSet.size <= 1) return null;
         const uids = [...uidSet].slice(0, limit);
-        const msgs = [];
-        for await (const msg of client.fetch(
-          uids.join(","),
-          // Same reason as the list/search fetch: get-thread emits structured
-          // rows too, so it needs BODYSTRUCTURE or its hasAttachments would
-          // silently disagree with the same message seen via search.
-          // INTERNALDATE and the Date: header ride along for the same reason as
-          // the list/search fetch: the per-message date is recovered and
-          // sanity-checked exactly as a row's dateSent is (#234).
-          {
-            envelope: true,
-            flags: true,
-            bodyStructure: true,
-            internalDate: true,
-            headers: ["date"]
-          },
-          { uid: true }
-        )) {
-          msgs.push(msg);
-        }
+        const rows = await fetchRows(client, uids);
+        const msgs = rows.messages.slice();
+        const omittedMessages = rows.omitted.map((uid) => ({
+          id: encodeImapId(ref.account, ref.path, uid),
+          mailbox: ref.path,
+          uid,
+          reason: omissionReason(rows)
+        }));
         msgs.sort((a, b) => dateMs(a) - dateMs(b));
         const subject = seed.envelope?.subject || "(no subject)";
         const structured = {
           subject,
           count: msgs.length,
+          partial: omittedMessages.length > 0,
+          omittedMessages,
           messages: msgs.map((m) => ({
             id: encodeImapId(ref.account, ref.path, m.uid),
             subject: m.envelope?.subject || "(no subject)",
@@ -59559,7 +59746,7 @@ async function imapThread(id, deps = {}, limit = 50) {
           }))
         };
         const text = `Thread "${subject}" \u2014 ${msgs.length} message(s) via IMAP (References-linked, oldest first):
-` + msgs.map((m) => formatRow(m, ref.account, ref.path)).join("\n");
+` + msgs.map((m) => formatRow(m, ref.account, ref.path)).join("\n") + omittedNote(omittedMessages, false);
         return { count: msgs.length, text, structured };
       } finally {
         lock.release();
@@ -59568,7 +59755,7 @@ async function imapThread(id, deps = {}, limit = 50) {
     true
   );
 }
-var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
+var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
 var init_imapClient = __esm({
   "src/services/imapClient.ts"() {
     "use strict";
@@ -59594,7 +59781,24 @@ var init_imapClient = __esm({
       accounts: "APPLE_MAIL_MCP_IMAP_ACCOUNTS"
     };
     defaultConnect = async (cfg) => {
-      const client = new import_imapflow.ImapFlow(buildImapConnectionOptions(cfg));
+      let lastCommandError;
+      const keepErr = (entry) => {
+        if (entry && typeof entry === "object" && "err" in entry) {
+          lastCommandError = entry.err;
+        }
+      };
+      const noop = () => void 0;
+      const client = new import_imapflow.ImapFlow({
+        ...buildImapConnectionOptions(cfg),
+        logger: { trace: noop, debug: noop, info: noop, warn: keepErr, error: keepErr, fatal: keepErr }
+      });
+      Object.assign(client, {
+        takeLastCommandError: () => {
+          const err = lastCommandError;
+          lastCommandError = void 0;
+          return err;
+        }
+      });
       client.on("error", () => {
       });
       try {
@@ -59622,6 +59826,27 @@ var init_imapClient = __esm({
       starred: "\\flagged"
     };
     NOT_DELETED = { deleted: false };
+    LARGE_MAILBOX_MESSAGES = 1e4;
+    FIRST_SEARCH_WINDOW = 5e3;
+    MAX_WINDOW = 5e4;
+    ROW_QUERY = {
+      envelope: true,
+      flags: true,
+      bodyStructure: true,
+      internalDate: true,
+      headers: ["date"]
+    };
+    ROW_QUERY_NO_STRUCTURE = {
+      envelope: true,
+      flags: true,
+      internalDate: true,
+      headers: ["date", "content-type"]
+    };
+    ROW_QUERY_HEADERS_ONLY = {
+      flags: true,
+      internalDate: true,
+      headers: ["date", "from", "subject", "message-id", "in-reply-to", "content-type"]
+    };
     poolConnect = defaultConnect;
     pools = /* @__PURE__ */ new Map();
     connecting = /* @__PURE__ */ new Map();

package/build/index.js

@@ -65374,6 +65374,7 @@ var imapClient_exports = {};
 __export(imapClient_exports, {
   HEADER_WINDOW_BYTES: () => HEADER_WINDOW_BYTES,
   IMAP_ENV: () => IMAP_ENV,
+  LARGE_MAILBOX_MESSAGES: () => LARGE_MAILBOX_MESSAGES,
   MAX_COMPOSE_SOURCE_BYTES: () => MAX_COMPOSE_SOURCE_BYTES,
   MAX_RFC822_FILE_BYTES: () => MAX_RFC822_FILE_BYTES,
   MAX_RFC822_INLINE_BYTES: () => MAX_RFC822_INLINE_BYTES,
@@ -65420,6 +65421,7 @@ __export(imapClient_exports, {
   mailFlagColorIndex: () => mailFlagColorIndex,
   matchMailbox: () => matchMailbox,
   normalizeMessageId: () => normalizeMessageId,
+  omittedNote: () => omittedNote,
   resolveImapConfig: () => resolveImapConfig,
   resolveImapConfigs: () => resolveImapConfigs,
   resolveMailboxPath: () => resolveMailboxPath,
@@ -65730,7 +65732,12 @@ function structuredRow(m, account, path) {
     // a caller from "no attachments", so every IMAP-sourced message claimed to
     // have none. Falls back to false only when the fetch carried no
     // BODYSTRUCTURE at all.
-    hasAttachments: bodyStructureHasAttachments(m.bodyStructure),
+    // A row read without BODYSTRUCTURE (#256 follow-up) judges by its top-level
+    // Content-Type instead, and says so in `metadataIncomplete`.
+    hasAttachments: m.bodyStructure ? bodyStructureHasAttachments(m.bodyStructure) : m.degraded ? contentTypeSuggestsAttachments(m) : false,
+    ...m.degraded ? {
+      metadataIncomplete: m.degraded === "bodystructure" ? "BODYSTRUCTURE unreadable; hasAttachments inferred from Content-Type" : "FETCH response unreadable; row rebuilt from raw headers, hasAttachments inferred from Content-Type"
+    } : {},
     // Message-ID (when the envelope carries it) is the strongest cross-/intra-
     // backend dedup key for the multi-account merge (imapMultiAccount.ts). The
     // AppleScript path does not expose it, so cross-backend dedup falls back to
@@ -65738,6 +65745,13 @@ function structuredRow(m, account, path) {
     ...env.messageId ? { messageId: env.messageId } : {}
   };
 }
+function omittedNote(omitted, merged) {
+  if (omitted.length === 0) return "";
+  const list = omitted.map((o) => `UID ${o.uid} in "${o.mailbox}" (${o.id})`).join(", ");
+  return `
+
+Partial result. ${omitted.length} message(s) ${merged ? "that may belong" : "that belong"} on this page could not be read and are not listed: ${list}. Reason: ${[...new Set(omitted.map((o) => o.reason))].join("; ")}. get-message or get-message-headers with those ids may still read them.`;
+}
 function describeMailboxFailure(error2) {
   const raw = errText(error2);
   const oneLine = raw.split("\n")[0].trim();
@@ -65757,44 +65771,215 @@ function messageIdentity(entry) {
   const messageId = raw.replace(/^<+|>+$/g, "").trim().toLowerCase();
   return messageId ? `mid:${messageId}` : `${entry.path}\0${entry.message.uid}`;
 }
-async function fetchMailboxMatches(client, path, criteria, newestCount) {
-  const lock = await client.getMailboxLock(path);
+function isUnfiltered(criteria) {
+  const keys = Object.keys(criteria);
+  return keys.length === 1 && criteria.deleted === false;
+}
+async function statusMessageCount(client, path) {
   try {
-    const found = await client.search(criteria, { uid: true });
-    const uids = Array.isArray(found) ? found : [];
-    if (uids.length === 0 || newestCount === 0) return { messages: [], total: uids.length };
-    const status = await client.status(path, { messages: true });
-    if (typeof status.messages === "number" && uids.length > status.messages) {
+    const st = await client.status(path, { messages: true });
+    return typeof st.messages === "number" && st.messages >= 0 ? st.messages : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function searchUids(client, path, criteria, size) {
+  client.takeLastCommandError?.();
+  const found = await client.search(criteria, { uid: true });
+  if (Array.isArray(found)) return found;
+  const cause = client.takeLastCommandError?.();
+  const sized = size === void 0 ? "" : ` (${size.toLocaleString("en-US")} messages)`;
+  throw new Error(
+    `IMAP SEARCH on "${path}"${sized} failed: ` + (cause ? errText(cause) : "the server rejected it or the connection dropped before it answered (on a mailbox this size, usually a server-side timeout)")
+  );
+}
+function mergeFetched(into, msg) {
+  const prev = into.get(msg.uid);
+  if (!prev) {
+    into.set(msg.uid, msg);
+    return;
+  }
+  const merged = { ...prev };
+  for (const [key, value] of Object.entries(msg)) {
+    if (value !== void 0 && value !== null)
+      merged[key] = value;
+  }
+  into.set(msg.uid, merged);
+}
+async function fetchInto(client, uids, query, into) {
+  const wanted = new Set(uids);
+  for await (const msg of client.fetch(uids.join(","), query, { uid: true })) {
+    if (typeof msg?.uid === "number" && wanted.has(msg.uid)) mergeFetched(into, msg);
+  }
+}
+function fetchedHeaders(m) {
+  return m.headers ? parseHeaderBlock(decodeHeaderBytes(asBuffer(m.headers))) : void 0;
+}
+function envelopeFromHeaders(m) {
+  const h = fetchedHeaders(m);
+  if (!h || h.headers.length === 0) return void 0;
+  const env = {};
+  if (h.subject) env.subject = h.subject;
+  if (h.from) {
+    const angle = h.from.match(/^\s*"?([^"<]*?)"?\s*<([^>]+)>/);
+    env.from = angle ? [{ ...angle[1].trim() ? { name: angle[1].trim() } : {}, address: angle[2].trim() }] : [{ address: h.from.trim() }];
+  }
+  if (h.messageId) env.messageId = `<${h.messageId}>`;
+  if (h.inReplyTo) env.inReplyTo = `<${h.inReplyTo}>`;
+  if (h.dateHeader) env.date = h.dateHeader;
+  return env;
+}
+function contentTypeSuggestsAttachments(m) {
+  const type = fetchedHeaders(m)?.headers.find((h) => h.name.toLowerCase() === "content-type");
+  return /^\s*multipart\/mixed\b/i.test(type?.value ?? "");
+}
+async function fetchRows(client, uids) {
+  if (uids.length === 0) return { messages: [], omitted: [] };
+  const byUid = /* @__PURE__ */ new Map();
+  const causes = [];
+  const noteCause = () => {
+    const err = client.takeLastCommandError?.();
+    if (err !== void 0) {
+      const text = describeMailboxFailure(err);
+      if (!causes.includes(text)) causes.push(text);
+    }
+  };
+  const missing = () => uids.filter((uid) => !byUid.get(uid)?.envelope);
+  client.takeLastCommandError?.();
+  await fetchInto(client, uids, ROW_QUERY, byUid);
+  noteCause();
+  let gap = missing();
+  if (gap.length > 0) {
+    await fetchInto(client, gap, ROW_QUERY, byUid);
+    noteCause();
+    gap = missing();
+  }
+  if (gap.length > 0) {
+    const reduced = /* @__PURE__ */ new Map();
+    await fetchInto(client, gap, ROW_QUERY_NO_STRUCTURE, reduced);
+    noteCause();
+    for (const msg of reduced.values()) {
+      if (!msg.envelope) continue;
+      mergeFetched(byUid, { ...msg, degraded: "bodystructure" });
+    }
+    gap = missing();
+  }
+  if (gap.length > 0) {
+    for (const uid of gap) {
+      const bare = /* @__PURE__ */ new Map();
+      await fetchInto(client, [uid], ROW_QUERY_HEADERS_ONLY, bare);
+      noteCause();
+      const msg = bare.get(uid);
+      const envelope = msg ? envelopeFromHeaders(msg) : void 0;
+      if (msg && envelope) {
+        mergeFetched(byUid, { ...msg, envelope, degraded: "envelope" });
+      }
+    }
+    gap = missing();
+  }
+  const omitted = new Set(gap);
+  return {
+    messages: uids.filter((uid) => !omitted.has(uid)).map((uid) => byUid.get(uid)).filter((message) => message !== void 0),
+    omitted: gap,
+    ...causes.length > 0 ? { cause: causes.join("; ") } : {}
+  };
+}
+function pageRows(fetch) {
+  return {
+    messages: fetch.messages,
+    omitted: fetch.omitted,
+    ...fetch.omitted.length > 0 ? { omittedReason: omissionReason(fetch) } : {}
+  };
+}
+function omissionReason(fetch) {
+  return "the server's FETCH response for this message could not be read, even without BODYSTRUCTURE or ENVELOPE" + (fetch.cause ? ` (${fetch.cause})` : "");
+}
+async function walkWindows(exists, page, firstWindow, readWindow) {
+  const wanted = page.skip + page.take;
+  const uids = [];
+  let seen = 0;
+  let matched = 0;
+  let hi = exists;
+  let width = Math.max(1, Math.min(firstWindow, MAX_WINDOW));
+  while (hi >= 1 && seen < wanted) {
+    const lo = Math.max(1, hi - width + 1);
+    const live = (await readWindow(lo, hi === exists ? "*" : hi, hi - lo + 1)).slice().sort((a, b) => b - a);
+    matched += live.length;
+    for (const uid of live) {
+      if (seen >= wanted) break;
+      if (seen >= page.skip) uids.push(uid);
+      seen++;
+    }
+    hi = lo - 1;
+    width = Math.min(width * 4, MAX_WINDOW);
+  }
+  return { uids, matched, exhausted: hi < 1 };
+}
+async function listLargeMailbox(client, exists, page) {
+  let deletedSeen = 0;
+  const walk = await walkWindows(
+    exists,
+    page,
+    // Room for a few ghosts on the first read without a second round trip.
+    page.skip + page.take + 64,
+    async (lo, hi) => {
+      const live = [];
+      for await (const msg of client.fetch(`${lo}:${hi}`, { uid: true, flags: true })) {
+        if (msg.flags?.has("\\Deleted")) deletedSeen++;
+        else live.push(msg.uid);
+      }
+      return live;
+    }
+  );
+  return {
+    ...pageRows(await fetchRows(client, walk.uids)),
+    total: Math.max(0, exists - deletedSeen),
+    totalExact: true
+  };
+}
+async function searchLargeMailbox(client, path, criteria, exists, page) {
+  const walk = await walkWindows(exists, page, FIRST_SEARCH_WINDOW, async (lo, hi, width) => {
+    const found = await searchUids(client, path, { ...criteria, seq: `${lo}:${hi}` }, exists);
+    if (found.length > width) {
       throw new Error(
-        `IMAP SEARCH on "${path}" reported ${uids.length} matches, more than the mailbox's own ${status.messages} messages \u2014 discarding as corrupted rather than trusting it (see #246).`
+        `IMAP SEARCH on "${path}" reported ${found.length} matches in a ${width}-message window \u2014 discarding as corrupted rather than trusting it (see #246).`
       );
     }
-    const newest = uids.slice().reverse().slice(0, newestCount);
-    const byUid = /* @__PURE__ */ new Map();
-    for await (const msg of client.fetch(
-      newest.join(","),
-      // BODYSTRUCTURE rides along so `hasAttachments` is computed rather
-      // than assumed. Measured on 50 real messages: ~390ms -> ~465ms for
-      // the fetch (~17%), same single round trip, no extra request.
-      //
-      // INTERNALDATE rides along for the same reason, and is why `dateReceived`
-      // can finally mean what it says: imapflow's `envelope.date` is built from
-      // the header block, so it IS the `Date:` header, not arrival time.
-      //
-      // The `Date:` header itself (BODY.PEEK[HEADER.FIELDS (DATE)]) rides in the
-      // SAME FETCH command, so a date the server's ENVELOPE parser rejected can
-      // still be recovered (#234). Measured on 50 real messages, 6 alternating
-      // runs: median ~334ms without vs ~315ms with — inside the noise — for ~44
-      // bytes per message. Too cheap to hide behind an opt-in.
-      { envelope: true, flags: true, bodyStructure: true, internalDate: true, headers: ["date"] },
-      { uid: true }
-    )) {
-      byUid.set(msg.uid, msg);
+    return found;
+  });
+  return {
+    ...pageRows(await fetchRows(client, walk.uids)),
+    total: walk.matched,
+    totalExact: walk.exhausted
+  };
+}
+async function fetchMailboxMatches(client, path, criteria, page) {
+  const lock = await client.getMailboxLock(path);
+  try {
+    const exists = await statusMessageCount(client, path);
+    if (exists === 0) return { messages: [], omitted: [], total: 0, totalExact: true };
+    if (exists !== void 0 && exists > LARGE_MAILBOX_MESSAGES) {
+      try {
+        return isUnfiltered(criteria) ? await listLargeMailbox(client, exists, page) : await searchLargeMailbox(client, path, criteria, exists, page);
+      } catch (error2) {
+        const detail = errText(error2);
+        throw new Error(
+          detail.includes(`"${path}" (`) ? detail : `reading the newest messages of "${path}" (${exists.toLocaleString("en-US")} messages) failed: ${detail}`
+        );
+      }
     }
-    return {
-      messages: newest.map((uid) => byUid.get(uid)).filter((message) => message !== void 0),
-      total: uids.length
-    };
+    const uids = await searchUids(client, path, criteria, exists);
+    if (uids.length === 0 || page.take === 0) {
+      return { messages: [], omitted: [], total: uids.length, totalExact: true };
+    }
+    const messages = exists ?? (await client.status(path, { messages: true })).messages ?? void 0;
+    if (typeof messages === "number" && uids.length > messages) {
+      throw new Error(
+        `IMAP SEARCH on "${path}" reported ${uids.length} matches, more than the mailbox's own ${messages} messages \u2014 discarding as corrupted rather than trusting it (see #246).`
+      );
+    }
+    const newest = uids.slice().reverse().slice(page.skip, page.skip + page.take);
+    return { ...pageRows(await fetchRows(client, newest)), total: uids.length, totalExact: true };
   } finally {
     lock.release();
   }
@@ -65823,16 +66008,27 @@ async function run(args, listMode, deps) {
       const limit = args.limit ?? 50;
       const offset = args.offset ?? 0;
       const criteria = buildCriteria(args, listMode);
-      const newestPerMailbox = offset + limit;
+      const page = unscopedSearch ? { skip: 0, take: offset + limit } : { skip: offset, take: limit };
       const fetched = [];
       const failedMailboxes = [];
       const failedMailboxReasons = {};
+      const omittedMessages = [];
       let totalMatched = 0;
+      let totalExact = true;
       for (const path of paths) {
         try {
-          const result = await fetchMailboxMatches(client, path, criteria, newestPerMailbox);
+          const result = await fetchMailboxMatches(client, path, criteria, page);
           totalMatched += result.total;
+          totalExact &&= result.totalExact;
           fetched.push(...result.messages.map((message) => ({ message, path })));
+          for (const uid of result.omitted) {
+            omittedMessages.push({
+              id: encodeImapId(cfg.accountLabel, path, uid),
+              mailbox: path,
+              uid,
+              reason: result.omittedReason ?? "the server's FETCH response could not be read"
+            });
+          }
         } catch (error2) {
           failedMailboxes.push(path);
           failedMailboxReasons[path] = describeMailboxFailure(error2);
@@ -65856,18 +66052,17 @@ async function run(args, listMode, deps) {
           if (!unique.has(key)) unique.set(key, entry);
         }
         ordered = [...unique.values()].slice(offset, offset + limit);
-      } else {
-        ordered = fetched.slice(offset, offset + limit);
       }
       const rows = ordered.map(({ message, path }) => formatRow(message, cfg.accountLabel, path));
       const messages = ordered.map(
         ({ message, path }) => structuredRow(message, cfg.accountLabel, path)
       );
-      const partial2 = failedMailboxes.length > 0;
-      const failureNote = partial2 ? `
+      const partial2 = failedMailboxes.length > 0 || omittedMessages.length > 0;
+      const failureNote = (failedMailboxes.length > 0 ? `
 
-Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"${path}" (${failedMailboxReasons[path]})`).join(", ")}.` : "";
+Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"${path}" (${failedMailboxReasons[path]})`).join(", ")}.` : "") + omittedNote(omittedMessages, unscopedSearch);
       const verb = listMode ? "listed" : "matched";
+      const totalText = totalExact ? `${totalMatched} total` : `at least ${totalMatched} total`;
       const scope = unscopedSearch ? allMailboxCount === 1 ? `mailbox "${paths[0]}"` : `${allMailboxCount} selectable mailboxes` : `mailbox "${paths[0]}"`;
       if (messages.length === 0) {
         return {
@@ -65876,10 +66071,11 @@ Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"
           count: 0,
           partial: partial2,
           failedMailboxes,
-          failedMailboxReasons
+          failedMailboxReasons,
+          omittedMessages
         };
       }
-      const text = `Found ${rows.length} message(s) via IMAP (server-side, account ${cfg.accountLabel}, ${scope}; ${totalMatched} total ${verb}):
+      const text = `Found ${rows.length} message(s) via IMAP (server-side, account ${cfg.accountLabel}, ${scope}; ${totalText} ${verb}):
 ` + rows.join("\n") + `
 
 Note: these IMAP IDs (imap:\u2026) work with get-message and the message mutations (mark/flag/move/delete-message), which route back to IMAP.` + failureNote;
@@ -65889,7 +66085,8 @@ Note: these IMAP IDs (imap:\u2026) work with get-message and the message mutatio
         count: messages.length,
         partial: partial2,
         failedMailboxes,
-        failedMailboxReasons
+        failedMailboxReasons,
+        omittedMessages
       };
     },
     true
@@ -66849,31 +67046,21 @@ async function imapThread(id, deps = {}, limit = 50) {
         }
         if (uidSet.size <= 1) return null;
         const uids = [...uidSet].slice(0, limit);
-        const msgs = [];
-        for await (const msg of client.fetch(
-          uids.join(","),
-          // Same reason as the list/search fetch: get-thread emits structured
-          // rows too, so it needs BODYSTRUCTURE or its hasAttachments would
-          // silently disagree with the same message seen via search.
-          // INTERNALDATE and the Date: header ride along for the same reason as
-          // the list/search fetch: the per-message date is recovered and
-          // sanity-checked exactly as a row's dateSent is (#234).
-          {
-            envelope: true,
-            flags: true,
-            bodyStructure: true,
-            internalDate: true,
-            headers: ["date"]
-          },
-          { uid: true }
-        )) {
-          msgs.push(msg);
-        }
+        const rows = await fetchRows(client, uids);
+        const msgs = rows.messages.slice();
+        const omittedMessages = rows.omitted.map((uid) => ({
+          id: encodeImapId(ref.account, ref.path, uid),
+          mailbox: ref.path,
+          uid,
+          reason: omissionReason(rows)
+        }));
         msgs.sort((a, b) => dateMs(a) - dateMs(b));
         const subject = seed.envelope?.subject || "(no subject)";
         const structured = {
           subject,
           count: msgs.length,
+          partial: omittedMessages.length > 0,
+          omittedMessages,
           messages: msgs.map((m) => ({
             id: encodeImapId(ref.account, ref.path, m.uid),
             subject: m.envelope?.subject || "(no subject)",
@@ -66888,7 +67075,7 @@ async function imapThread(id, deps = {}, limit = 50) {
           }))
         };
         const text = `Thread "${subject}" \u2014 ${msgs.length} message(s) via IMAP (References-linked, oldest first):
-` + msgs.map((m) => formatRow(m, ref.account, ref.path)).join("\n");
+` + msgs.map((m) => formatRow(m, ref.account, ref.path)).join("\n") + omittedNote(omittedMessages, false);
         return { count: msgs.length, text, structured };
       } finally {
         lock.release();
@@ -66897,7 +67084,7 @@ async function imapThread(id, deps = {}, limit = 50) {
     true
   );
 }
-var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
+var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
 var init_imapClient = __esm({
   "src/services/imapClient.ts"() {
     "use strict";
@@ -66923,7 +67110,24 @@ var init_imapClient = __esm({
       accounts: "APPLE_MAIL_MCP_IMAP_ACCOUNTS"
     };
     defaultConnect = async (cfg) => {
-      const client = new import_imapflow.ImapFlow(buildImapConnectionOptions(cfg));
+      let lastCommandError;
+      const keepErr = (entry) => {
+        if (entry && typeof entry === "object" && "err" in entry) {
+          lastCommandError = entry.err;
+        }
+      };
+      const noop = () => void 0;
+      const client = new import_imapflow.ImapFlow({
+        ...buildImapConnectionOptions(cfg),
+        logger: { trace: noop, debug: noop, info: noop, warn: keepErr, error: keepErr, fatal: keepErr }
+      });
+      Object.assign(client, {
+        takeLastCommandError: () => {
+          const err = lastCommandError;
+          lastCommandError = void 0;
+          return err;
+        }
+      });
       client.on("error", () => {
       });
       try {
@@ -66951,6 +67155,27 @@ var init_imapClient = __esm({
       starred: "\\flagged"
     };
     NOT_DELETED = { deleted: false };
+    LARGE_MAILBOX_MESSAGES = 1e4;
+    FIRST_SEARCH_WINDOW = 5e3;
+    MAX_WINDOW = 5e4;
+    ROW_QUERY = {
+      envelope: true,
+      flags: true,
+      bodyStructure: true,
+      internalDate: true,
+      headers: ["date"]
+    };
+    ROW_QUERY_NO_STRUCTURE = {
+      envelope: true,
+      flags: true,
+      internalDate: true,
+      headers: ["date", "content-type"]
+    };
+    ROW_QUERY_HEADERS_ONLY = {
+      flags: true,
+      internalDate: true,
+      headers: ["date", "from", "subject", "message-id", "in-reply-to", "content-type"]
+    };
     poolConnect = defaultConnect;
     pools = /* @__PURE__ */ new Map();
     connecting = /* @__PURE__ */ new Map();
@@ -87452,6 +87677,7 @@ async function fanOutImapMessages(args, kind, deps = {}, configs = resolveImapCo
   const accountsFailed = [];
   const failedMailboxes = [];
   const failedMailboxReasons = {};
+  const omittedMessages = [];
   for (const config2 of configs) {
     const perAccountArgs = { ...args, account: void 0 };
     try {
@@ -87464,12 +87690,25 @@ async function fanOutImapMessages(args, kind, deps = {}, configs = resolveImapCo
       for (const [mailbox, reason] of Object.entries(res.failedMailboxReasons)) {
         failedMailboxReasons[`${config2.accountLabel} / ${mailbox}`] = reason;
       }
+      omittedMessages.push(
+        ...(res.omittedMessages ?? []).map((o) => ({
+          ...o,
+          mailbox: `${config2.accountLabel} / ${o.mailbox}`
+        }))
+      );
     } catch (e) {
       accountsFailed.push(config2.accountLabel);
       console.error(`IMAP fan-out failed for account "${config2.accountLabel}": ${String(e)}`);
     }
   }
-  return { rows, accountsQueried, accountsFailed, failedMailboxes, failedMailboxReasons };
+  return {
+    rows,
+    accountsQueried,
+    accountsFailed,
+    failedMailboxes,
+    failedMailboxReasons,
+    omittedMessages
+  };
 }
 function configMatchesAccount(config2, account) {
   const name = account.name.trim().toLowerCase();
@@ -88072,7 +88311,10 @@ var LIST_OUTPUT_SCHEMA = {
   failedMailboxes: external_exports.array(external_exports.string()).optional(),
   // Underlying error text per entry in `failedMailboxes`, same keys (#246
   // follow-up) — declared so a client can rely on it rather than parse text.
-  failedMailboxReasons: external_exports.record(external_exports.string(), external_exports.string()).optional()
+  failedMailboxReasons: external_exports.record(external_exports.string(), external_exports.string()).optional(),
+  // Messages that belong on the page but could not be read, each with its
+  // imap: id and why (#256 follow-up). Non-empty implies `partial: true`.
+  omittedMessages: external_exports.array(external_exports.object({ id: external_exports.string(), mailbox: external_exports.string(), uid: external_exports.number(), reason: external_exports.string() })).optional()
 };
 var BATCH_COUNT_OUTPUT_SCHEMA = {
   ok: external_exports.boolean().optional(),
@@ -88151,7 +88393,7 @@ function mergedMessageResponse(fan, apple, limit, verb) {
   const merged = mergeMessages(fan.rows, apple.rows, limit);
   const diagnostics = {
     ...apple.diagnostics,
-    partial: apple.diagnostics.partial || fan.accountsFailed.length > 0 || fan.failedMailboxes.length > 0,
+    partial: apple.diagnostics.partial || fan.accountsFailed.length > 0 || fan.failedMailboxes.length > 0 || fan.omittedMessages.length > 0,
     timedOutAccounts: [...apple.diagnostics.timedOutAccounts, ...fan.accountsFailed],
     notSearchedMailboxes: [...apple.diagnostics.notSearchedMailboxes, ...fan.failedMailboxes]
   };
@@ -88163,9 +88405,10 @@ function mergedMessageResponse(fan, apple, limit, verb) {
     notSearchedMailboxes: diagnostics.notSearchedMailboxes,
     timedOutAccounts: diagnostics.timedOutAccounts,
     failedMailboxes: fan.failedMailboxes,
-    failedMailboxReasons: fan.failedMailboxReasons
+    failedMailboxReasons: fan.failedMailboxReasons,
+    omittedMessages: fan.omittedMessages
   };
-  const coverageBlock = partialCoverageBlock(diagnostics);
+  const coverageBlock = partialCoverageBlock(diagnostics) + omittedNote(fan.omittedMessages, true);
   if (merged.length === 0) {
     const base = diagnostics.partial ? `No messages found in the portions that were ${verb === "matched" ? "searched" : "listed"}.` : "No messages found";
     return successResponse(`${base}${coverageBlock}`, structured);
@@ -88266,7 +88509,8 @@ registerTool(
             count: r.count,
             partial: r.partial,
             failedMailboxes: r.failedMailboxes,
-            failedMailboxReasons: r.failedMailboxReasons
+            failedMailboxReasons: r.failedMailboxReasons,
+            omittedMessages: r.omittedMessages
           });
         }
         const fan = await fanOutImapMessages(imapArgs, "search");
@@ -88620,7 +88864,9 @@ registerTool(
       messages: external_exports.array(MESSAGE_ROW_SCHEMA).optional(),
       count: external_exports.number().optional(),
       partial: external_exports.boolean().optional(),
-      failedMailboxes: external_exports.array(external_exports.string()).optional()
+      failedMailboxes: external_exports.array(external_exports.string()).optional(),
+      failedMailboxReasons: LIST_OUTPUT_SCHEMA.failedMailboxReasons,
+      omittedMessages: LIST_OUTPUT_SCHEMA.omittedMessages
     }
   },
   withErrorHandling(async ({ id, account, mailbox, limit = 50 }) => {
@@ -88650,7 +88896,8 @@ ${r.text}`, {
           count: r.count,
           partial: r.partial,
           failedMailboxes: r.failedMailboxes,
-          failedMailboxReasons: r.failedMailboxReasons
+          failedMailboxReasons: r.failedMailboxReasons,
+          omittedMessages: r.omittedMessages
         });
       }
       const fan = await fanOutImapMessages({ subject: base, mailbox, limit }, "search");
@@ -88675,20 +88922,21 @@ ${r.text}`, {
       const orderedRows = mergedNewestFirst.slice().reverse().sort(
         (a, b) => (a.dateReceived ? new Date(a.dateReceived).getTime() : 0) - (b.dateReceived ? new Date(b.dateReceived).getTime() : 0)
       );
-      const partial2 = apple.diagnostics.partial || fan.accountsFailed.length > 0 || fan.failedMailboxes.length > 0;
+      const partial2 = apple.diagnostics.partial || fan.accountsFailed.length > 0 || fan.failedMailboxes.length > 0 || fan.omittedMessages.length > 0;
       const coverage = partialCoverageBlock({
         ...apple.diagnostics,
         partial: partial2,
         timedOutAccounts: [...apple.diagnostics.timedOutAccounts, ...fan.accountsFailed],
         notSearchedMailboxes: [...apple.diagnostics.notSearchedMailboxes, ...fan.failedMailboxes]
-      });
+      }) + omittedNote(fan.omittedMessages, true);
       const structured2 = {
         subject: base,
         messages: orderedRows,
         count: orderedRows.length,
         partial: partial2,
         failedMailboxes: fan.failedMailboxes,
-        failedMailboxReasons: fan.failedMailboxReasons
+        failedMailboxReasons: fan.failedMailboxReasons,
+        omittedMessages: fan.omittedMessages
       };
       if (orderedRows.length === 0) {
         return successResponse(`No messages found in thread "${base}".${coverage}`, structured2);
@@ -88753,7 +89001,8 @@ registerTool(
           count: r.count,
           partial: r.partial,
           failedMailboxes: r.failedMailboxes,
-          failedMailboxReasons: r.failedMailboxReasons
+          failedMailboxReasons: r.failedMailboxReasons,
+          omittedMessages: r.omittedMessages
         });
       }
       const fan = await fanOutImapMessages({ mailbox, limit, offset, from, unreadOnly }, "list");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-mail-mcp",
-  "version": "2.19.16",
+  "version": "2.19.18",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",