apple-mail-mcp 2.10.33 → 2.11.1

package/README.md

@@ -1319,14 +1319,26 @@ returns the comparison in `structuredContent`:
 }
 ```
 
-`status` is deliberately four-valued rather than a pass/fail flag:
+`status` is deliberately not a pass/fail flag:
 
 | `status` | Meaning | Warns? |
 |----------|---------|--------|
 | `match` | Exactly as many messages left the mailbox as the operation acted on. | No |
 | `over` | **More** left than were operated on. Messages are unaccounted for. | **Yes** |
-| `under` | **Fewer** left than expected. | No |
-| `unknown` | No comparison was possible: either Mail would not report a count (`before`/`after` null) or there is no predictable expectation (`expected` null — see the self-move rule below). | No |
+| `unknown` | No comparison this server is willing to assert. `unknownReason` says which of four situations produced it. | No |
+
+`unknownReason` distinguishes four cases that are *not* interchangeable:
+
+| `unknownReason` | Meaning |
+|-----------------|---------|
+| `count-unreadable` | Mail would not report a count at all (`before`/`after` null). |
+| `no-expectation` | No expectation is predictable, so no comparison exists — a move whose destination **is** the source mailbox. |
+| `count-did-not-move` | The count did not move. On a store that flags deletions instead of removing them this is the **ordinary, correct** reading for an operation that fully succeeded. |
+| `count-partial` | The count moved, but by less than the operation accounted for. A flag-only store cannot produce this, which is why it is worth telling apart. |
+
+> **`under` was removed in 2.11.0.** It used to mean "fewer left than expected"
+> and was documented as routine. Field evidence retired it — see
+> [Why `observed` is a lower bound](#why-observed-is-a-lower-bound-155).
 
 #### What an `over` warning does and does not tell you
 
@@ -1346,7 +1358,7 @@ trusted:
 **Concurrent departure is the benign cause to rule out first**, and the warning
 text says so. What the asymmetry argument actually buys is the other half:
 concurrent *arrivals* cannot produce `over`, because a message arriving
-mid-operation *raises* the after-count and biases the reading toward `under`.
+mid-operation *raises* the after-count and biases the reading short.
 That is why `over` is the interesting direction — a strong signal, not a proof.
 
 Setting `APPLE_MAIL_MCP_AUDIT_LOG` is what settles which one you have: the
@@ -1354,12 +1366,42 @@ collateral diff below **names** the messages that disappeared, and "the
 newsletter my rule files every morning" is a very different report from a message
 nothing should have touched.
 
-`under`, by contrast, is routine: an account that flags deletions rather than
-removing them leaves the message in place and the count does not move, and a
-Gmail label mailbox can behave the same way while the delete genuinely succeeded.
-A warning that fires on every ordinary Gmail delete would be ignored exactly when
-it matters, so `under` is **reported** in `countDelta` (with a `note` explaining
-it) and never warned about.
+#### Why `observed` is a lower bound (#155)
+
+**`observed` is the movement of Mail's count. It is a lower bound on how many
+messages left, not a count of how many left.**
+
+On iCloud, @scottstern0325 ran the check that settled this: for two batches
+reporting `observed: 0`, the messages were located **in Trash**, matched by
+`date received` + sender against the audit log's pre-image. The deletes had
+happened. Mail's count had not caught up. Across four readings — 0 of 4, 0 of 1
+(a *single-id* delete), 15 of 16, and 14 of 15 — the shortfall bore no relation
+to batch size, which is what a lagging count looks like and not what a
+store-behaviour rule looks like.
+
+So a short reading is not evidence about your operation. **The per-id outcomes
+are what report success; this number is not. Do not retry on the strength of
+it** — that is how a message gets deleted twice.
+
+Two things follow:
+
+- A count that does not move at all is still the ordinary reading on a store that
+  flags deletions instead of removing them (Gmail label mailboxes, IMAP accounts
+  with "move deleted messages to Trash" off). It reports
+  `unknownReason: "count-did-not-move"` and says so, and it is never warned about
+  — a warning that fires on every ordinary Gmail delete would be ignored exactly
+  when it matters.
+- **To confirm where messages went, match them at the destination by `date
+  received` plus sender — not by the numeric ids you passed.** Ids are renumbered
+  by the move and do not survive it.
+
+**Removed in 2.11.0: the "reported success with no observed effect" warning.**
+Shipped in 2.10.30, it fired when the count was flat, the snapshot read cleanly
+and nothing had disappeared. Its premise was that the snapshot corroborated the
+count — but both are read back-to-back in the same script, and the record that
+prompted it turns out to have had *both* instruments stale at once. It therefore
+fired on stores that had done exactly what they were asked. It is gone rather
+than narrowed; `over` is the only surviving assertion.
 
 Three more honesty rules:
 
@@ -1489,8 +1531,15 @@ a hole, because a wrong name here is worse than a missing one:
 | both | withheld | withheld |
 
 **An absent field means "not computable", never "empty".** Check
-`"snapshot": "ok"` before reading `disappeared` as a clean bill of health — the
-false-ok warning does exactly that, so a `partial` snapshot never triggers it.
+`"snapshot": "ok"` before reading `disappeared` as a clean bill of health.
+
+> ⚠️ **`"ok"` is necessary, not sufficient.** The enumeration's range is bounded
+> by Mail's own message count, and #155 established that count can lag the
+> mutation. A count reading **low** truncates the enumeration silently — the
+> unread tail is never requested, so it never registers as a failed slice and the
+> status still says `"ok"` — and messages past that bound would then look like
+> they disappeared. Until that is fixed, treat a `disappeared` entry as a lead to
+> check, not a proof.
 
 ### Privacy, and what the file costs you
 

package/build/index.js

@@ -78071,11 +78071,17 @@ function sleep(ms) {
     }
   }
 }
+var PERMISSION_DENIED_PATTERN = /not authorized|not permitted|access.*denied/i;
+var PERMISSION_DENIED_MESSAGE = "Permission denied. Grant automation access in System Settings > Privacy & Security > Automation.";
+function isPermissionDenied(error2) {
+  if (!error2) return false;
+  return PERMISSION_DENIED_PATTERN.test(error2) || error2.includes(PERMISSION_DENIED_MESSAGE);
+}
 var ERROR_MAPPINGS = [
   // Permission errors
   {
-    pattern: /not authorized|not permitted|access.*denied/i,
-    message: "Permission denied. Grant automation access in System Settings > Privacy & Security > Automation."
+    pattern: PERMISSION_DENIED_PATTERN,
+    message: PERMISSION_DENIED_MESSAGE
   },
   // Application not running
   {
@@ -78854,17 +78860,8 @@ function countDeltaWarning(d) {
   const where = d.account ? `"${d.mailbox}" in account "${d.account}"` : `"${d.mailbox}"`;
   return `\u26A0\uFE0F Effect mismatch in ${where}: ${d.observed} message(s) left the mailbox but only ${d.expected} were operated on (count ${d.before} \u2192 ${d.after}). ${extra} message(s) are unaccounted for. Anything else removing mail from this mailbox at the same moment \u2014 a Mail rule, a server-side filter, another client, an IMAP expunge \u2014 reads the same way, so rule that out first. If nothing else was touching it, this is the signature of https://github.com/sweetrb/apple-mail-mcp/issues/155 \u2014 please report it there, and set ${AUDIT_LOG_ENV}=/path/to/audit.ndjson to capture which messages disappeared.`;
 }
-function falseOkWarning(d, collateral) {
-  if (d.status !== "under" || d.expected === null) return null;
-  if (d.observed !== 0 || d.expected <= 0) return null;
-  if (!collateral || collateral.snapshot !== "ok") return null;
-  if ((collateral.disappeared?.length ?? 0) !== 0) return null;
-  const where = d.account ? `"${d.mailbox}" in account "${d.account}"` : `"${d.mailbox}"`;
-  return `\u26A0\uFE0F Reported success with no observed effect in ${where}: ${d.expected} message(s) were operated on and reported ok, but the mailbox count did not move (${d.before} \u2192 ${d.after}) and the collateral snapshot \u2014 which read this mailbox successfully \u2014 shows no message left it. Either the operation silently did nothing, or Mail's count and listing are both stale and the messages did move. Check the destination (Trash for a delete) before assuming either: if they are there, this is a measurement-timing bug; if they are still in the source mailbox minutes later, the operation failed while reporting success. Please report at https://github.com/sweetrb/apple-mail-mcp/issues/155 with ${AUDIT_LOG_ENV}=/path/to/audit.ndjson set.`;
-}
 function reconciliationWarnings(report) {
-  const collateralFor = (d) => report.collateral.find((c) => c.account === d.account && c.mailbox === d.mailbox);
-  return report.countDeltas.flatMap((d) => [countDeltaWarning(d), falseOkWarning(d, collateralFor(d))]).filter((w) => w !== null);
+  return report.countDeltas.map((d) => countDeltaWarning(d)).filter((w) => w !== null);
 }
 
 // src/services/appleMailManager.ts
@@ -79142,6 +79139,8 @@ function canonicalNumericId(raw) {
   return Number.isFinite(n) ? String(n) : trimmed;
 }
 var SELF_MOVE_NOTE = "Destination is the source mailbox, so no message should leave it. What Mail does to the count when a message is re-filed into the mailbox it already occupies is unspecified, so there is no expected delta to compare against: this mailbox is reported without a comparison and is never warned about.";
+var COUNT_UNMOVED_NOTE = `Mail's count did not move. This is the ordinary reading on a store that flags deletions instead of removing them (Gmail label mailboxes and IMAP accounts with "move deleted messages to Trash" off), where the message stays put and the operation still fully succeeded. It can also mean Mail's count simply had not caught up yet. The per-id outcomes are what report success; this number is not, so do not retry on the strength of it.`;
+var COUNT_PARTIAL_NOTE = `Mail's count moved by less than this operation accounted for. That is a LOWER BOUND on what left, not a count of what left: Mail has been observed reporting a stale count for a delete it had already performed (issue #155), and new mail arriving mid-operation reads the same way. No claim is made either way. To confirm where the messages went, match them at the destination by "date received" plus sender \u2014 NOT by the numeric ids you passed, which are renumbered by the move and do not survive it.`;
 function snapshotKey(entry) {
   return `${entry.id}\0${entry.messageId}`;
 }
@@ -79679,10 +79678,24 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       const observed = readable ? m.before - m.after : null;
       const note = noteFor(m.account, m.mailbox);
       let status;
-      if (!readable || m.expected === null) status = "unknown";
-      else if (observed === m.expected) status = "match";
-      else if ((observed ?? 0) > m.expected) status = "over";
-      else status = "under";
+      let unknownReason;
+      if (!readable) {
+        status = "unknown";
+        unknownReason = "count-unreadable";
+      } else if (m.expected === null) {
+        status = "unknown";
+        unknownReason = "no-expectation";
+      } else if (observed === m.expected) {
+        status = "match";
+      } else if ((observed ?? 0) > m.expected) {
+        status = "over";
+      } else if (observed === 0) {
+        status = "unknown";
+        unknownReason = "count-did-not-move";
+      } else {
+        status = "unknown";
+        unknownReason = "count-partial";
+      }
       return {
         account: m.account,
         mailbox: m.mailbox,
@@ -79691,11 +79704,11 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         expected: m.expected,
         observed,
         status,
+        ...unknownReason ? { unknownReason } : {},
         ...note ? { note } : {},
-        ...status === "unknown" && readable === false ? { note: note ?? "Mail did not report a message count for this mailbox" } : {},
-        ...status === "under" && !note ? {
-          note: "Fewer messages left the mailbox than were operated on. This is normal on a store that flags deletions instead of removing them (and when new mail arrives mid-operation), so it is reported but not warned about."
-        } : {}
+        ...unknownReason === "count-unreadable" ? { note: note ?? "Mail did not report a message count for this mailbox" } : {},
+        ...unknownReason === "count-did-not-move" && !note ? { note: COUNT_UNMOVED_NOTE } : {},
+        ...unknownReason === "count-partial" && !note ? { note: COUNT_PARTIAL_NOTE } : {}
       };
     });
     const preImages = [];
@@ -82834,7 +82847,7 @@ ${actionStmts.join("\n")}
         message: "Mail.app is accessible"
       });
     } else {
-      const errorHint = mailCheck.error?.includes("not authorized") ? " (check System Settings > Privacy & Security > Automation)" : "";
+      const errorHint = isPermissionDenied(mailCheck.error) ? " (check System Settings > Privacy & Security > Automation)" : "";
       checks.push({
         name: "mail_app",
         passed: false,
@@ -82850,7 +82863,7 @@ ${actionStmts.join("\n")}
         message: "AppleScript automation permissions granted"
       });
     } else {
-      const isPermError = permCheck.error?.includes("not authorized") || permCheck.error?.includes("not permitted");
+      const isPermError = isPermissionDenied(permCheck.error);
       checks.push({
         name: "permissions",
         passed: !isPermError,
@@ -83674,7 +83687,12 @@ function structuredRow(m, account, path) {
     flagColorIndex: mailFlagColorIndex(m.flags),
     mailbox: path,
     account,
-    hasAttachments: false,
+    // Derived from BODYSTRUCTURE, which the list/search fetch now requests.
+    // This was hardcoded `false` from 2.2.0 until 2.11.1 — indistinguishable to
+    // 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),
     // 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
@@ -83705,7 +83723,10 @@ async function run(args, listMode, deps) {
         const byUid = /* @__PURE__ */ new Map();
         for await (const msg of client.fetch(
           newest.join(","),
-          { envelope: true, flags: true },
+          // 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.
+          { envelope: true, flags: true, bodyStructure: true },
           { uid: true }
         )) {
           byUid.set(msg.uid, msg);
@@ -84199,7 +84220,8 @@ function collectAttachments(node, out = []) {
   if (!node) return out;
   const filename = node.dispositionParameters?.filename || node.parameters?.name;
   const disposition = node.disposition?.toLowerCase();
-  const isAttachment = !!node.part && (disposition === "attachment" || !!filename && disposition !== "inline");
+  const isEmbeddedByReference = disposition === "inline" && !!node.id;
+  const isAttachment = !!node.part && (disposition === "attachment" || !!filename && !isEmbeddedByReference);
   if (isAttachment) {
     out.push({
       part: node.part,
@@ -84211,6 +84233,9 @@ function collectAttachments(node, out = []) {
   for (const child of node.childNodes ?? []) collectAttachments(child, out);
   return out;
 }
+function bodyStructureHasAttachments(node) {
+  return !!node && collectAttachments(node).length > 0;
+}
 async function streamToBuffer(content, maxBytes) {
   const chunks = [];
   let total = 0;
@@ -84382,7 +84407,10 @@ async function imapThread(id, deps = {}, limit = 50) {
         const msgs = [];
         for await (const msg of client.fetch(
           uids.join(","),
-          { envelope: true, flags: true },
+          // 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.
+          { envelope: true, flags: true, bodyStructure: true },
           { uid: true }
         )) {
           msgs.push(msg);
@@ -85303,7 +85331,10 @@ var COUNT_DELTA_OUTPUT_SCHEMA = external_exports.array(
     // `status: "unknown"`, and never with a warning.
     expected: external_exports.number().nullable().optional(),
     observed: external_exports.number().nullable().optional(),
-    status: external_exports.enum(["match", "over", "under", "unknown"]).optional(),
+    status: external_exports.enum(["match", "over", "unknown"]).optional(),
+    // Declared explicitly: the SDK stamps additionalProperties:false on a bare
+    // zod shape, so an undeclared key makes the CLIENT reject the result.
+    unknownReason: external_exports.enum(["count-unreadable", "no-expectation", "count-did-not-move", "count-partial"]).optional(),
     note: external_exports.string().optional()
   })
 ).optional();

package/package.json

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