apple-mail-mcp 2.19.17 → 2.19.19

package/README.md

@@ -240,6 +240,7 @@ Search for messages matching criteria. Searches all accounts by default.
 | `dateFrom`  | string  | No       | Start date filter (e.g., "January 1, 2026")                                                                                               |
 | `dateTo`    | string  | No       | End date filter (e.g., "March 1, 2026")                                                                                                   |
 | `limit`     | number  | No       | Max results, 1–500 (default: 50)                                                                                                          |
+| `offset`    | number  | No       | Newest matches to skip, ≥ 0 (for pagination). IMAP accounts only; without a `mailbox`, `offset` + `limit` may not exceed 5,000            |
 
 **Returns:** List of matching messages with ID, date, subject, sender, and read state.
 
@@ -280,19 +281,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`.
 
 ---
 
@@ -1095,14 +1104,23 @@ 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`.
+sequence number: page `offset` of `limit` is sequence numbers
+`N-offset-limit+1 .. N-offset`, so it fetches UIDs and flags for that range
+alone (plus a small margin; `\Deleted` ones are skipped and the page topped up
+from below) and full rows for the page. The cost is the page, not the offset:
+`limit: 1` at offset 790,000 of a 793,614-message mailbox is one ~33-message
+`FETCH`, not a whole-mailbox `SEARCH` or a walk over every skipped message.
+Offsets count sequence positions. iCloud keeps messages awaiting expunge out of
+the sequence space, so there they are exact; on a server that keeps them in it,
+a page shifts by the number of such messages above it (they are never
+returned).
 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
+of the mailbox. A filtered search's deep `offset` has no such shortcut — which
+messages match is only known by searching the skipped windows — so its cost
+still grows with the offset (in 50,000-message `SEARCH` windows); narrow it
+with `dateTo` instead. 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".
 

package/build/cli.js

@@ -58049,6 +58049,7 @@ __export(imapClient_exports, {
   MAX_COMPOSE_SOURCE_BYTES: () => MAX_COMPOSE_SOURCE_BYTES,
   MAX_RFC822_FILE_BYTES: () => MAX_RFC822_FILE_BYTES,
   MAX_RFC822_INLINE_BYTES: () => MAX_RFC822_INLINE_BYTES,
+  MAX_UNSCOPED_SEARCH_DEPTH: () => MAX_UNSCOPED_SEARCH_DEPTH,
   __resetPool: () => __resetPool,
   __setPoolConnect: () => __setPoolConnect,
   bodyStructureHasAttachments: () => bodyStructureHasAttachments,
@@ -58092,10 +58093,12 @@ __export(imapClient_exports, {
   mailFlagColorIndex: () => mailFlagColorIndex,
   matchMailbox: () => matchMailbox,
   normalizeMessageId: () => normalizeMessageId,
+  omittedNote: () => omittedNote,
   resolveImapConfig: () => resolveImapConfig,
   resolveImapConfigs: () => resolveImapConfigs,
   resolveMailboxPath: () => resolveMailboxPath,
-  shouldUseImap: () => shouldUseImap
+  shouldUseImap: () => shouldUseImap,
+  unscopedSearchOffsetError: () => unscopedSearchOffsetError
 });
 import { createHash } from "node:crypto";
 function encodeImapId(account, path, uid) {
@@ -58402,7 +58405,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
@@ -58410,6 +58418,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();
@@ -58429,6 +58444,10 @@ function messageIdentity(entry) {
   const messageId = raw.replace(/^<+|>+$/g, "").trim().toLowerCase();
   return messageId ? `mid:${messageId}` : `${entry.path}\0${entry.message.uid}`;
 }
+function unscopedSearchOffsetError(offset, limit) {
+  if (offset <= 0 || offset + limit <= MAX_UNSCOPED_SEARCH_DEPTH) return void 0;
+  return `search-messages without a mailbox merges every mailbox's newest offset+limit matches, so it pages at most ${MAX_UNSCOPED_SEARCH_DEPTH.toLocaleString("en-US")} deep (offset ${offset} + limit ${limit} asked). Name a mailbox (e.g. the account's All Mail or Archive) to page deeper, or narrow the search with dateTo.`;
+}
 function isUnfiltered(criteria) {
   const keys = Object.keys(criteria);
   return keys.length === 1 && criteria.deleted === false;
@@ -58451,41 +58470,117 @@ async function searchUids(client, path, criteria, size) {
     `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 [];
+  if (uids.length === 0) return { messages: [], omitted: [] };
   const byUid = /* @__PURE__ */ new Map();
-  for await (const msg of client.fetch(
-    uids.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 uids.map((uid) => byUid.get(uid)).filter((message) => message !== void 0);
+  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) {
+async function walkWindows(top, page, firstWindow, readWindow, openTop = true) {
   const wanted = page.skip + page.take;
   const uids = [];
   let seen = 0;
   let matched = 0;
-  let hi = exists;
+  let hi = top;
   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);
+    const live = (await readWindow(lo, hi === top && openTop ? "*" : hi, hi - lo + 1)).slice().sort((a, b) => b - a);
     matched += live.length;
     for (const uid of live) {
       if (seen >= wanted) break;
@@ -58497,13 +58592,21 @@ async function walkWindows(exists, page, firstWindow, readWindow) {
   }
   return { uids, matched, exhausted: hi < 1 };
 }
+function sequenceTop(client, statusCount) {
+  const mb = client.mailbox;
+  const exists = mb && typeof mb.exists === "number" && mb.exists >= 0 ? mb.exists : void 0;
+  return exists ?? statusCount;
+}
 async function listLargeMailbox(client, exists, page) {
+  const top = sequenceTop(client, exists) - page.skip;
+  if (top < 1 || page.take === 0) {
+    return { messages: [], omitted: [], total: exists, totalExact: true };
+  }
   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,
+    top,
+    { skip: 0, take: page.take },
+    page.take + DELETED_MARGIN,
     async (lo, hi) => {
       const live = [];
       for await (const msg of client.fetch(`${lo}:${hi}`, { uid: true, flags: true })) {
@@ -58511,10 +58614,13 @@ async function listLargeMailbox(client, exists, page) {
         else live.push(msg.uid);
       }
       return live;
-    }
+    },
+    // From the very top the first window is `lo:*`, as before; below it the
+    // range is exact.
+    page.skip === 0
   );
   return {
-    messages: await fetchRows(client, walk.uids),
+    ...pageRows(await fetchRows(client, walk.uids)),
     total: Math.max(0, exists - deletedSeen),
     totalExact: true
   };
@@ -58530,7 +58636,7 @@ async function searchLargeMailbox(client, path, criteria, exists, page) {
     return found;
   });
   return {
-    messages: await fetchRows(client, walk.uids),
+    ...pageRows(await fetchRows(client, walk.uids)),
     total: walk.matched,
     totalExact: walk.exhausted
   };
@@ -58539,7 +58645,7 @@ 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: [], total: 0, totalExact: true };
+    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);
@@ -58552,7 +58658,7 @@ async function fetchMailboxMatches(client, path, criteria, page) {
     }
     const uids = await searchUids(client, path, criteria, exists);
     if (uids.length === 0 || page.take === 0) {
-      return { messages: [], total: uids.length, totalExact: true };
+      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) {
@@ -58561,7 +58667,7 @@ async function fetchMailboxMatches(client, path, criteria, page) {
       );
     }
     const newest = uids.slice().reverse().slice(page.skip, page.skip + page.take);
-    return { messages: await fetchRows(client, newest), total: uids.length, totalExact: true };
+    return { ...pageRows(await fetchRows(client, newest)), total: uids.length, totalExact: true };
   } finally {
     lock.release();
   }
@@ -58589,11 +58695,16 @@ async function run(args, listMode, deps) {
       }
       const limit = args.limit ?? 50;
       const offset = args.offset ?? 0;
+      if (unscopedSearch) {
+        const tooDeep = unscopedSearchOffsetError(offset, limit);
+        if (tooDeep) throw new Error(tooDeep);
+      }
       const criteria = buildCriteria(args, listMode);
       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) {
@@ -58602,6 +58713,14 @@ async function run(args, listMode, deps) {
           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);
@@ -58630,10 +58749,10 @@ async function run(args, listMode, deps) {
       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]}"`;
@@ -58644,7 +58763,8 @@ 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}; ${totalText} ${verb}):
@@ -58657,7 +58777,8 @@ Note: these IMAP IDs (imap:\u2026) work with get-message and the message mutatio
         count: messages.length,
         partial,
         failedMailboxes,
-        failedMailboxReasons
+        failedMailboxReasons,
+        omittedMessages
       };
     },
     true
@@ -59617,31 +59738,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)",
@@ -59656,7 +59767,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();
@@ -59665,7 +59776,7 @@ async function imapThread(id, deps = {}, limit = 50) {
     true
   );
 }
-var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, 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, MAX_UNSCOPED_SEARCH_DEPTH, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, DELETED_MARGIN, 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";
@@ -59739,6 +59850,26 @@ var init_imapClient = __esm({
     LARGE_MAILBOX_MESSAGES = 1e4;
     FIRST_SEARCH_WINDOW = 5e3;
     MAX_WINDOW = 5e4;
+    MAX_UNSCOPED_SEARCH_DEPTH = 5e3;
+    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"]
+    };
+    DELETED_MARGIN = 32;
     poolConnect = defaultConnect;
     pools = /* @__PURE__ */ new Map();
     connecting = /* @__PURE__ */ new Map();

package/build/index.js

@@ -65378,6 +65378,7 @@ __export(imapClient_exports, {
   MAX_COMPOSE_SOURCE_BYTES: () => MAX_COMPOSE_SOURCE_BYTES,
   MAX_RFC822_FILE_BYTES: () => MAX_RFC822_FILE_BYTES,
   MAX_RFC822_INLINE_BYTES: () => MAX_RFC822_INLINE_BYTES,
+  MAX_UNSCOPED_SEARCH_DEPTH: () => MAX_UNSCOPED_SEARCH_DEPTH,
   __resetPool: () => __resetPool,
   __setPoolConnect: () => __setPoolConnect,
   bodyStructureHasAttachments: () => bodyStructureHasAttachments,
@@ -65421,10 +65422,12 @@ __export(imapClient_exports, {
   mailFlagColorIndex: () => mailFlagColorIndex,
   matchMailbox: () => matchMailbox,
   normalizeMessageId: () => normalizeMessageId,
+  omittedNote: () => omittedNote,
   resolveImapConfig: () => resolveImapConfig,
   resolveImapConfigs: () => resolveImapConfigs,
   resolveMailboxPath: () => resolveMailboxPath,
-  shouldUseImap: () => shouldUseImap
+  shouldUseImap: () => shouldUseImap,
+  unscopedSearchOffsetError: () => unscopedSearchOffsetError
 });
 import { createHash } from "node:crypto";
 function encodeImapId(account, path, uid) {
@@ -65731,7 +65734,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
@@ -65739,6 +65747,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();
@@ -65758,6 +65773,10 @@ function messageIdentity(entry) {
   const messageId = raw.replace(/^<+|>+$/g, "").trim().toLowerCase();
   return messageId ? `mid:${messageId}` : `${entry.path}\0${entry.message.uid}`;
 }
+function unscopedSearchOffsetError(offset, limit) {
+  if (offset <= 0 || offset + limit <= MAX_UNSCOPED_SEARCH_DEPTH) return void 0;
+  return `search-messages without a mailbox merges every mailbox's newest offset+limit matches, so it pages at most ${MAX_UNSCOPED_SEARCH_DEPTH.toLocaleString("en-US")} deep (offset ${offset} + limit ${limit} asked). Name a mailbox (e.g. the account's All Mail or Archive) to page deeper, or narrow the search with dateTo.`;
+}
 function isUnfiltered(criteria) {
   const keys = Object.keys(criteria);
   return keys.length === 1 && criteria.deleted === false;
@@ -65780,41 +65799,117 @@ async function searchUids(client, path, criteria, size) {
     `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 [];
+  if (uids.length === 0) return { messages: [], omitted: [] };
   const byUid = /* @__PURE__ */ new Map();
-  for await (const msg of client.fetch(
-    uids.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 uids.map((uid) => byUid.get(uid)).filter((message) => message !== void 0);
-}
-async function walkWindows(exists, page, firstWindow, readWindow) {
+  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(top, page, firstWindow, readWindow, openTop = true) {
   const wanted = page.skip + page.take;
   const uids = [];
   let seen = 0;
   let matched = 0;
-  let hi = exists;
+  let hi = top;
   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);
+    const live = (await readWindow(lo, hi === top && openTop ? "*" : hi, hi - lo + 1)).slice().sort((a, b) => b - a);
     matched += live.length;
     for (const uid of live) {
       if (seen >= wanted) break;
@@ -65826,13 +65921,21 @@ async function walkWindows(exists, page, firstWindow, readWindow) {
   }
   return { uids, matched, exhausted: hi < 1 };
 }
+function sequenceTop(client, statusCount) {
+  const mb = client.mailbox;
+  const exists = mb && typeof mb.exists === "number" && mb.exists >= 0 ? mb.exists : void 0;
+  return exists ?? statusCount;
+}
 async function listLargeMailbox(client, exists, page) {
+  const top = sequenceTop(client, exists) - page.skip;
+  if (top < 1 || page.take === 0) {
+    return { messages: [], omitted: [], total: exists, totalExact: true };
+  }
   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,
+    top,
+    { skip: 0, take: page.take },
+    page.take + DELETED_MARGIN,
     async (lo, hi) => {
       const live = [];
       for await (const msg of client.fetch(`${lo}:${hi}`, { uid: true, flags: true })) {
@@ -65840,10 +65943,13 @@ async function listLargeMailbox(client, exists, page) {
         else live.push(msg.uid);
       }
       return live;
-    }
+    },
+    // From the very top the first window is `lo:*`, as before; below it the
+    // range is exact.
+    page.skip === 0
   );
   return {
-    messages: await fetchRows(client, walk.uids),
+    ...pageRows(await fetchRows(client, walk.uids)),
     total: Math.max(0, exists - deletedSeen),
     totalExact: true
   };
@@ -65859,7 +65965,7 @@ async function searchLargeMailbox(client, path, criteria, exists, page) {
     return found;
   });
   return {
-    messages: await fetchRows(client, walk.uids),
+    ...pageRows(await fetchRows(client, walk.uids)),
     total: walk.matched,
     totalExact: walk.exhausted
   };
@@ -65868,7 +65974,7 @@ 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: [], total: 0, totalExact: true };
+    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);
@@ -65881,7 +65987,7 @@ async function fetchMailboxMatches(client, path, criteria, page) {
     }
     const uids = await searchUids(client, path, criteria, exists);
     if (uids.length === 0 || page.take === 0) {
-      return { messages: [], total: uids.length, totalExact: true };
+      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) {
@@ -65890,7 +65996,7 @@ async function fetchMailboxMatches(client, path, criteria, page) {
       );
     }
     const newest = uids.slice().reverse().slice(page.skip, page.skip + page.take);
-    return { messages: await fetchRows(client, newest), total: uids.length, totalExact: true };
+    return { ...pageRows(await fetchRows(client, newest)), total: uids.length, totalExact: true };
   } finally {
     lock.release();
   }
@@ -65918,11 +66024,16 @@ async function run(args, listMode, deps) {
       }
       const limit = args.limit ?? 50;
       const offset = args.offset ?? 0;
+      if (unscopedSearch) {
+        const tooDeep = unscopedSearchOffsetError(offset, limit);
+        if (tooDeep) throw new Error(tooDeep);
+      }
       const criteria = buildCriteria(args, listMode);
       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) {
@@ -65931,6 +66042,14 @@ async function run(args, listMode, deps) {
           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);
@@ -65959,10 +66078,10 @@ async function run(args, listMode, deps) {
       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]}"`;
@@ -65973,7 +66092,8 @@ 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}; ${totalText} ${verb}):
@@ -65986,7 +66106,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
@@ -66946,31 +67067,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)",
@@ -66985,7 +67096,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();
@@ -66994,7 +67105,7 @@ async function imapThread(id, deps = {}, limit = 50) {
     true
   );
 }
-var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, 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, MAX_UNSCOPED_SEARCH_DEPTH, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, DELETED_MARGIN, 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";
@@ -67068,6 +67179,26 @@ var init_imapClient = __esm({
     LARGE_MAILBOX_MESSAGES = 1e4;
     FIRST_SEARCH_WINDOW = 5e3;
     MAX_WINDOW = 5e4;
+    MAX_UNSCOPED_SEARCH_DEPTH = 5e3;
+    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"]
+    };
+    DELETED_MARGIN = 32;
     poolConnect = defaultConnect;
     pools = /* @__PURE__ */ new Map();
     connecting = /* @__PURE__ */ new Map();
@@ -87569,6 +87700,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 {
@@ -87581,12 +87713,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();
@@ -88189,7 +88334,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(),
@@ -88268,7 +88416,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]
   };
@@ -88280,9 +88428,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);
@@ -88345,7 +88494,10 @@ registerTool(
       isFlagged: external_exports.boolean().optional().describe("Filter by flagged status"),
       dateFrom: DATE_FILTER_SCHEMA.describe("Start date filter (e.g., 'January 1, 2026')"),
       dateTo: DATE_FILTER_SCHEMA.describe("End date filter (e.g., 'March 1, 2026')"),
-      limit: external_exports.number().int().min(1).max(500).optional().describe("Maximum number of results (default: 50, max: 500)")
+      limit: external_exports.number().int().min(1).max(500).optional().describe("Maximum number of results (default: 50, max: 500)"),
+      offset: external_exports.number().int().min(0).optional().describe(
+        "Number of newest matches to skip (for pagination; IMAP accounts only). Without a mailbox, offset + limit may not exceed 5,000 \u2014 name a mailbox to page deeper."
+      )
     },
     outputSchema: LIST_OUTPUT_SCHEMA
   },
@@ -88356,6 +88508,7 @@ registerTool(
       mailbox,
       account,
       limit = 50,
+      offset = 0,
       dateFrom,
       dateTo,
       from,
@@ -88363,12 +88516,17 @@ registerTool(
       isRead,
       isFlagged
     }) => {
+      if (offset > 0 && !mailbox) {
+        const tooDeep = unscopedSearchOffsetError(offset, limit);
+        if (tooDeep) return errorResponse(tooDeep);
+      }
       if (shouldUseImap(account)) {
         const imapArgs = {
           query,
           body,
           mailbox,
           limit,
+          offset,
           dateFrom,
           dateTo,
           from,
@@ -88383,14 +88541,20 @@ 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");
         const { appleScriptOnly } = partitionAccountsForCounts(
           mailManager.listAccounts(),
           resolveImapConfigs()
         );
+        if (offset > 0 && appleScriptOnly.length > 0 && !body) {
+          return errorResponse(
+            `offset is supported only on IMAP accounts, and ${appleScriptOnly.map((a) => `"${a.name}"`).join(", ")} ${appleScriptOnly.length === 1 ? "is" : "are"} AppleScript-only. Pass an IMAP account to page, or omit offset.`
+          );
+        }
+        const fan = await fanOutImapMessages(imapArgs, "search");
         if (body) {
           const apple2 = {
             rows: [],
@@ -88421,6 +88585,11 @@ registerTool(
         );
         return mergedMessageResponse(fan, apple, limit, "matched");
       }
+      if (offset > 0) {
+        return errorResponse(
+          `offset is supported only on IMAP accounts; IMAP is not configured for ${account ? `account "${account}"` : "any account"}. Omit offset, or narrow the search with dateFrom/dateTo instead.`
+        );
+      }
       if (body) {
         return errorResponse(
           `Body search requires the IMAP backend, which is not configured for ${account ? `account "${account}"` : "any account"}. Configure IMAP (see the IMAP backend section of the README) or search by query/subject/from instead.`
@@ -88737,7 +88906,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 }) => {
@@ -88767,7 +88938,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");
@@ -88792,20 +88964,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);
@@ -88870,7 +89043,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.17",
+  "version": "2.19.19",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",