apple-mail-mcp 2.10.32 → 2.11.0

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:
 
@@ -1399,6 +1441,7 @@ batch of only `imap:` ids returns no `countDelta` rather than a fabricated one.
 | `APPLE_MAIL_MCP_AUDIT_LOG` | *(off)* | Absolute path to an NDJSON file. Setting it enables the audit log **and** the collateral diff below |
 | `APPLE_MAIL_MCP_AUDIT_SUBJECTS` | `0` | Set `1` to also record message **subjects**. Separate, deliberate second opt-in — see Privacy |
 | `APPLE_MAIL_MCP_AUDIT_SNAPSHOT_MAX` | `2000` | Skip the collateral snapshot for mailboxes larger than this many messages. `0` disables the snapshot entirely |
+| `APPLE_MAIL_MCP_AUDIT_SNAPSHOT_CHUNK` | `250` | How many messages the collateral snapshot reads from Mail per request. Lower it if Mail declines slices on a very large mailbox |
 
 When set, each destructive operation appends **one JSON object per line**
 containing: timestamp, tool name, server version, the arguments it was called
@@ -1451,12 +1494,52 @@ exceed AppleScript's 2^29 integer range (where Mail hands them back as
 compared in the raw form, a message you explicitly asked to delete would be
 reported here as collateral.
 
-This costs one bulk property read per snapshot and is O(mailbox size), so it is
-bounded by `APPLE_MAIL_MCP_AUDIT_SNAPSHOT_MAX`. When the bound bites, the record
-says so explicitly (`"snapshot": "skipped"` with a reason) rather than omitting
-the field — a silently skipped snapshot would read as "nothing collateral
-happened", which is worse than no snapshot at all. `countDelta` is unaffected by
-the skip and still reconciles the counts.
+This is O(mailbox size), so it is bounded by `APPLE_MAIL_MCP_AUDIT_SNAPSHOT_MAX`.
+When the bound bites, the record says so explicitly (`"snapshot": "skipped"` with
+a reason) rather than omitting the field — a silently skipped snapshot would read
+as "nothing collateral happened", which is worse than no snapshot at all.
+`countDelta` is unaffected by the skip and still reconciles the counts.
+
+#### Partial snapshots on large mailboxes
+
+The mailbox is read in `APPLE_MAIL_MCP_AUDIT_SNAPSHOT_CHUNK`-sized slices, each
+retried once on its own. It used to be a single whole-mailbox read, which meant
+Mail declining that one request lost the **entire** diff — and the bigger the
+mailbox, the more likely that was. The mechanism that attributes collateral
+damage was therefore least reliable exactly when the blast radius was largest.
+
+When a slice still will not read, the snapshot is reported as `partial` and it
+**names its own gap**:
+
+```json
+{
+  "snapshot": "partial",
+  "unobserved": [{ "phase": "after", "ranges": "251-500" }],
+  "appeared": [],
+  "skipReason": "Mail would not read 251-500 (after) of this mailbox, so the snapshot has a hole in it. …"
+}
+```
+
+Each half of the diff is withheld when the snapshot that could **refute** it has
+a hole, because a wrong name here is worse than a missing one:
+
+| Hole in | `disappeared` / `unrequested` | `appeared` |
+|---------|-------------------------------|------------|
+| neither (`"ok"`) | reported | reported |
+| `before` | reported (an undercount — a message never read before cannot be missed after) | withheld |
+| `after` | **withheld** — a message absent from a partial `after` may merely be unread, and naming it would present an innocent message as evidence of data loss | reported |
+| both | withheld | withheld |
+
+**An absent field means "not computable", never "empty".** Check
+`"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

@@ -78791,7 +78791,10 @@ import { appendFileSync } from "node:fs";
 var AUDIT_LOG_ENV = "APPLE_MAIL_MCP_AUDIT_LOG";
 var AUDIT_SUBJECTS_ENV = "APPLE_MAIL_MCP_AUDIT_SUBJECTS";
 var AUDIT_SNAPSHOT_MAX_ENV = "APPLE_MAIL_MCP_AUDIT_SNAPSHOT_MAX";
+var AUDIT_SNAPSHOT_CHUNK_ENV = "APPLE_MAIL_MCP_AUDIT_SNAPSHOT_CHUNK";
 var DEFAULT_SNAPSHOT_MAX = 2e3;
+var DEFAULT_SNAPSHOT_CHUNK = 250;
+var SNAPSHOT_SLICE_ATTEMPTS = 2;
 function isOn(raw) {
   return /^(1|true|yes|on)$/i.test((raw ?? "").trim());
 }
@@ -78812,6 +78815,13 @@ function auditSnapshotMax() {
   if (!Number.isFinite(n) || n < 0) return DEFAULT_SNAPSHOT_MAX;
   return Math.floor(n);
 }
+function auditSnapshotChunk() {
+  const raw = process.env[AUDIT_SNAPSHOT_CHUNK_ENV]?.trim();
+  if (raw === void 0 || raw === "") return DEFAULT_SNAPSHOT_CHUNK;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 1) return DEFAULT_SNAPSHOT_CHUNK;
+  return Math.floor(n);
+}
 function writeAuditRecord(record2) {
   const path = auditLogPath();
   if (!path) return;
@@ -78844,17 +78854,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
@@ -79132,6 +79133,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}`;
 }
@@ -79402,10 +79405,24 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
    * into a SNAP record — the before/after pair the collateral diff subtracts.
    *
    * Empty string when the audit log is off or the snapshot is disabled, so the
-   * whole layer costs literally nothing by default. The two property reads are
-   * BULK (`id of messages of mb`, `message id of messages of mb`) — two Apple
-   * Events for the whole mailbox rather than two per message — and the joining
-   * is pure in-memory AppleScript.
+   * whole layer costs literally nothing by default. The property reads are BULK
+   * (`id of messages i thru j of mb`) — two Apple Events per SLICE rather than
+   * two per message — and the joining is pure in-memory AppleScript.
+   *
+   * ## Why it is sliced rather than one whole-mailbox read (#176)
+   *
+   * This used to be a single `id of messages of mb` pair. When Mail declined
+   * that request the entire snapshot came back `unavailable`, and the cost of
+   * the request grows with the mailbox — so the one mechanism that can attribute
+   * an unrequested departure was least reliable exactly when the batch and the
+   * mailbox, and therefore the blast radius, were largest. That correlation was
+   * the defect, not any individual failure.
+   *
+   * Now the mailbox is read in `APPLE_MAIL_MCP_AUDIT_SNAPSHOT_CHUNK`-sized
+   * slices; each slice is retried once on its own; and a slice that still will
+   * not read costs only its own range. The unreadable ranges are emitted in
+   * their own field, so the diff can report a PARTIAL snapshot that names its
+   * own gap instead of an all-or-nothing `unavailable`.
    *
    * Above `APPLE_MAIL_MCP_AUDIT_SNAPSHOT_MAX` messages the snapshot is skipped,
    * and the skip is EMITTED as a record with its reason. A silently skipped
@@ -79422,46 +79439,77 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
   snapshotFragment(phase, acctExpr, mbExpr, countVar, mbVar = "_tmb") {
     const max = auditSnapshotMax();
     if (!isAuditEnabled() || max <= 0) return "";
+    const chunk = auditSnapshotChunk();
     return `
         set _sStatus to "ok"
         set _sPayload to ""
-        set _sIds to {}
-        set _sMids to {}
+        set _sMiss to ""
+        set _sPairs to {}
+        set _sChunk to ${chunk}
         if ${countVar} < 0 then
           set _sStatus to "unavailable"
         else if ${countVar} > ${max} then
           set _sStatus to "skipped"
           set _sPayload to "mailbox holds " & (${countVar} as string) & " messages, above ${AUDIT_SNAPSHOT_MAX_ENV}=${max}"
         else
-          try
-            set _sIds to (id of messages of ${mbVar})
-            set _sMids to (message id of messages of ${mbVar})
-          on error
-            set _sStatus to "unavailable"
-          end try
-          if _sStatus is "ok" then
-            if (count of _sIds) is not (count of _sMids) then
+          set _sLo to 1
+          repeat while _sLo <= ${countVar}
+            set _sHi to _sLo + _sChunk - 1
+            if _sHi > ${countVar} then set _sHi to ${countVar}
+            set _sGot to false
+            repeat with _sTry from 1 to ${SNAPSHOT_SLICE_ATTEMPTS}
+              set _sIds to {}
+              set _sMids to {}
+              -- A slice is staged into _sBuf and merged only once it has been
+              -- read IN FULL. Appending as we go would leave a slice that threw
+              -- halfway both partially recorded AND marked unread, and the
+              -- retry would then record its messages a second time.
+              set _sBuf to {}
+              try
+                set _sIds to (id of messages _sLo thru _sHi of ${mbVar})
+                set _sMids to (message id of messages _sLo thru _sHi of ${mbVar})
+                if (class of _sIds) is not list then set _sIds to {_sIds}
+                if (class of _sMids) is not list then set _sMids to {_sMids}
+                if (count of _sIds) is (count of _sMids) then
+                  repeat with _q from 1 to (count of _sIds)
+                    set _sOne to ""
+                    try
+                      set _zSnapMid to ((item _q of _sMids) as string)${this.sanitizeFragment("_zSnapMid", "                      ")}
+                      set _sOne to ((item _q of _sIds) as string) & "${SNAP_PAIR}" & _zSnapMid
+                    on error
+                      set _sOne to ((item _q of _sIds) as string) & "${SNAP_PAIR}"
+                    end try
+                    set end of _sBuf to _sOne
+                  end repeat
+                  set _sGot to true
+                end if
+              end try
+              if _sGot then
+                repeat with _sB in _sBuf
+                  set end of _sPairs to (contents of _sB)
+                end repeat
+                exit repeat
+              end if
+            end repeat
+            if not _sGot then
+              if _sMiss is not "" then set _sMiss to _sMiss & ","
+              set _sMiss to _sMiss & (_sLo as string) & "-" & (_sHi as string)
+            end if
+            set _sLo to _sHi + 1
+          end repeat
+          if _sMiss is not "" then
+            if (count of _sPairs) is 0 then
               set _sStatus to "unavailable"
             else
-              set _sPairs to {}
-              repeat with _q from 1 to (count of _sIds)
-                set _sOne to ""
-                try
-                  set _zSnapMid to ((item _q of _sMids) as string)${this.sanitizeFragment("_zSnapMid", "                  ")}
-                  set _sOne to ((item _q of _sIds) as string) & "${SNAP_PAIR}" & _zSnapMid
-                on error
-                  set _sOne to ((item _q of _sIds) as string) & "${SNAP_PAIR}"
-                end try
-                set end of _sPairs to _sOne
-              end repeat
-              set _sTid to AppleScript's text item delimiters
-              set AppleScript's text item delimiters to "${SNAP_ITEM}"
-              set _sPayload to _sPairs as string
-              set AppleScript's text item delimiters to _sTid
+              set _sStatus to "partial"
             end if
           end if
+          set _sTid to AppleScript's text item delimiters
+          set AppleScript's text item delimiters to "${SNAP_ITEM}"
+          set _sPayload to _sPairs as string
+          set AppleScript's text item delimiters to _sTid
         end if
-        set _out to _out & "${SNAP_TAG}${FIELD_SEP}" & ${acctExpr} & "${FIELD_SEP}" & ${mbExpr} & "${FIELD_SEP}${phase}${FIELD_SEP}" & _sStatus & "${FIELD_SEP}" & _sPayload & "${RECORD_SEP}"`;
+        set _out to _out & "${SNAP_TAG}${FIELD_SEP}" & ${acctExpr} & "${FIELD_SEP}" & ${mbExpr} & "${FIELD_SEP}${phase}${FIELD_SEP}" & _sStatus & "${FIELD_SEP}" & _sPayload & "${FIELD_SEP}" & _sMiss & "${RECORD_SEP}"`;
   }
   /**
    * AppleScript capturing the message the op is ABOUT to touch into `_pre`,
@@ -79527,7 +79575,8 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
           mailbox: f[2] ?? "",
           phase: f[3] === "after" ? "after" : "before",
           status: f[4] ?? "",
-          payload: f[5] ?? ""
+          payload: f[5] ?? "",
+          miss: f[6] ?? ""
         });
         continue;
       }
@@ -79623,10 +79672,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,
@@ -79635,11 +79698,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 = [];
@@ -79677,8 +79740,9 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         });
         continue;
       }
-      if (b.status !== "ok" || a.status !== "ok") {
-        const bad = b.status !== "ok" ? b : a;
+      const dead = (s) => s.status !== "ok" && s.status !== "partial";
+      if (dead(b) || dead(a)) {
+        const bad = dead(b) ? b : a;
         collateral.push({
           account: g.account,
           mailbox: g.mailbox,
@@ -79696,13 +79760,30 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       const unrequested = disappeared.filter(
         (e) => !requestedNumericIds.has(canonicalNumericId(e.id))
       );
+      const holes = [b, a].filter((s) => s.miss !== "").map((s) => ({ phase: s.phase, ranges: s.miss }));
+      if (holes.length === 0) {
+        collateral.push({
+          account: g.account,
+          mailbox: g.mailbox,
+          snapshot: "ok",
+          disappeared,
+          unrequested,
+          appeared
+        });
+        continue;
+      }
+      const derivable = [
+        a.miss === "" ? `what left the ${beforeEntries.length} message(s) read before it` : null,
+        b.miss === "" ? "what arrived during it" : null
+      ].filter((s) => s !== null);
       collateral.push({
         account: g.account,
         mailbox: g.mailbox,
-        snapshot: "ok",
-        disappeared,
-        unrequested,
-        appeared
+        snapshot: "partial",
+        skipReason: `Mail would not read ${holes.map((h) => `${h.ranges} (${h.phase})`).join(", ")} of this mailbox, so the snapshot has a hole in it. ` + (derivable.length > 0 ? `Still derivable and reported: ${derivable.join(" and ")}. ` : `Neither half of the diff is derivable from it. `) + `Anything the unread range could refute is omitted rather than guessed \u2014 an absent field here means "not computable", not "empty".`,
+        unobserved: holes,
+        ...a.miss === "" ? { disappeared, unrequested } : {},
+        ...b.miss === "" ? { appeared } : {}
       });
     }
     return { countDeltas, preImages, outcomes: parsed.outcomes, collateral };
@@ -85229,7 +85310,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();
@@ -86387,7 +86471,7 @@ registerTool(
 registerTool(
   "fetch-attachment",
   {
-    description: "Use when: retrieving an attachment's raw bytes inline as base64 (by message id and attachmentName), e.g. to process its contents without touching disk.\nReturns: the attachment's bytes base64-encoded, with its size and (for IMAP) MIME type.\nDo not use when: you don't know the attachment name (use list-attachments first) or you just want it saved to disk (use save-attachment).",
+    description: "Use when: retrieving an attachment's raw bytes inline as base64 (by message id and attachmentName), e.g. to process its contents without keeping a file.\nReturns: the attachment's bytes base64-encoded, with its size and (for IMAP) MIME type.\nDo not use when: you don't know the attachment name (use list-attachments first) or you just want it saved to disk (use save-attachment).\nSafety: leaves no file behind, but the AppleScript path is not disk-free \u2014 Mail writes the attachment into a private temp directory, which is read back and then deleted. Needs no Full Disk Access either way: Mail performs that write under the Automation grant, and this server never reads the mail store itself.",
     inputSchema: {
       id: MESSAGE_ID_SCHEMA,
       attachmentName: external_exports.string().min(1, "Attachment name is required")

package/package.json

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