apple-mail-mcp 2.20.3 → 2.20.5

package/build/index.js

@@ -19994,6 +19994,84 @@ var init_nodemailer = __esm({
   }
 });
 
+// src/utils/callStop.ts
+function searchDeadlineMs(env = process.env) {
+  const raw = env[SEARCH_DEADLINE_ENV];
+  if (raw === void 0 || raw.trim() === "") return DEFAULT_SEARCH_DEADLINE_MS;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return DEFAULT_SEARCH_DEADLINE_MS;
+  return Math.max(MIN_SEARCH_DEADLINE_MS, Math.floor(n));
+}
+function createCallStop(timing, deadlineMs, envVar = SEARCH_DEADLINE_ENV) {
+  const controller = new AbortController();
+  const upstream = timing?.signal;
+  const onCancel = () => {
+    if (!controller.signal.aborted) controller.abort({ kind: "cancelled" });
+  };
+  if (upstream?.aborted) onCancel();
+  else upstream?.addEventListener("abort", onCancel, { once: true });
+  const startedAt = timing?.arrivedAt ?? Date.now();
+  const remaining = Math.max(0, deadlineMs - (Date.now() - startedAt));
+  const timer = setTimeout(() => {
+    if (!controller.signal.aborted) {
+      controller.abort({ kind: "deadline", deadlineMs, envVar });
+    }
+  }, remaining);
+  timer.unref?.();
+  return {
+    signal: controller.signal,
+    dispose() {
+      clearTimeout(timer);
+      upstream?.removeEventListener("abort", onCancel);
+    }
+  };
+}
+function describeStop(signal) {
+  const reason = signal?.reason;
+  if (reason && typeof reason === "object" && reason.kind === "deadline") {
+    return `the ${Math.round(reason.deadlineMs / 1e3)}s search deadline (${reason.envVar})`;
+  }
+  return "the request being cancelled";
+}
+function stoppedByDeadline(signal) {
+  const reason = signal?.reason;
+  return !!reason && typeof reason === "object" && reason.kind === "deadline";
+}
+function raceStop(work, signal) {
+  if (!signal) return work;
+  if (signal.aborted) {
+    work.catch(() => void 0);
+    return Promise.resolve(STOPPED);
+  }
+  return new Promise((resolve5, reject) => {
+    const onAbort = () => {
+      work.catch(() => void 0);
+      resolve5(STOPPED);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    work.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve5(value);
+      },
+      (error3) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error3);
+      }
+    );
+  });
+}
+var DEFAULT_SEARCH_DEADLINE_MS, MIN_SEARCH_DEADLINE_MS, SEARCH_DEADLINE_ENV, STOPPED;
+var init_callStop = __esm({
+  "src/utils/callStop.ts"() {
+    "use strict";
+    DEFAULT_SEARCH_DEADLINE_MS = 45e3;
+    MIN_SEARCH_DEADLINE_MS = 2e3;
+    SEARCH_DEADLINE_ENV = "APPLE_MAIL_MCP_SEARCH_DEADLINE_MS";
+    STOPPED = /* @__PURE__ */ Symbol("stopped");
+  }
+});
+
 // node_modules/.pnpm/pino-std-serializers@7.1.0/node_modules/pino-std-serializers/lib/err-helpers.js
 var require_err_helpers = __commonJS({
   "node_modules/.pnpm/pino-std-serializers@7.1.0/node_modules/pino-std-serializers/lib/err-helpers.js"(exports, module) {
@@ -65379,6 +65457,7 @@ __export(imapClient_exports, {
   resolveImapConfigs: () => resolveImapConfigs,
   resolveMailboxPath: () => resolveMailboxPath,
   shouldUseImap: () => shouldUseImap,
+  stoppedNote: () => stoppedNote,
   unscopedSearchOffsetError: () => unscopedSearchOffsetError
 });
 import { createHash } from "node:crypto";
@@ -65699,6 +65778,12 @@ function structuredRow(m, account, path3) {
     ...env.messageId ? { messageId: env.messageId } : {}
   };
 }
+function stoppedNote(timedOut, signal) {
+  if (timedOut.length === 0) return "";
+  return `
+
+Partial result. Stopped by ${describeStop(signal)} before finishing ${timedOut.length} mailbox(es): ${timedOut.map((m) => `"${m}"`).join(", ")}. This is NOT a confirmed "no such mail" \u2014 narrow the search with \`mailbox\` and/or \`dateFrom\`, or raise ${SEARCH_DEADLINE_ENV}.`;
+}
 function omittedNote(omitted, merged) {
   if (omitted.length === 0) return "";
   const list = omitted.map((o) => `UID ${o.uid} in "${o.mailbox}" (${o.id})`).join(", ");
@@ -65988,9 +66073,23 @@ async function run(args, listMode, deps) {
       const omittedMessages = [];
       let totalMatched = 0;
       let totalExact = true;
-      for (const path3 of paths) {
+      const timedOutMailboxes = [];
+      for (const [index, path3] of paths.entries()) {
+        if (deps.signal?.aborted) {
+          timedOutMailboxes.push(...paths.slice(index));
+          break;
+        }
         try {
-          const result = await fetchMailboxMatches(client, path3, criteria, page);
+          const outcome = await raceStop(
+            fetchMailboxMatches(client, path3, criteria, page),
+            deps.signal
+          );
+          if (outcome === STOPPED) {
+            abandonClient(client, cfg, deps);
+            timedOutMailboxes.push(...paths.slice(index));
+            break;
+          }
+          const result = outcome;
           totalMatched += result.total;
           totalExact &&= result.totalExact;
           fetched.push(...result.messages.map((message) => ({ message, path: path3 })));
@@ -66030,10 +66129,14 @@ async function run(args, listMode, deps) {
       const messages = ordered.map(
         ({ message, path: path3 }) => structuredRow(message, cfg.accountLabel, path3)
       );
-      const partial2 = failedMailboxes.length > 0 || omittedMessages.length > 0;
+      const partial2 = failedMailboxes.length > 0 || omittedMessages.length > 0 || timedOutMailboxes.length > 0;
+      const stopped = timedOutMailboxes.length > 0 ? {
+        timedOutMailboxes,
+        stoppedBy: stoppedByDeadline(deps.signal) ? "deadline" : "cancelled"
+      } : {};
       const failureNote = (failedMailboxes.length > 0 ? `
 
-Partial result. Could not search mailbox(es): ${failedMailboxes.map((path3) => `"${path3}" (${failedMailboxReasons[path3]})`).join(", ")}.` : "") + omittedNote(omittedMessages, unscopedSearch);
+Partial result. Could not search mailbox(es): ${failedMailboxes.map((path3) => `"${path3}" (${failedMailboxReasons[path3]})`).join(", ")}.` : "") + omittedNote(omittedMessages, unscopedSearch) + stoppedNote(timedOutMailboxes, deps.signal);
       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]}"`;
@@ -66045,7 +66148,8 @@ Partial result. Could not search mailbox(es): ${failedMailboxes.map((path3) => `
           partial: partial2,
           failedMailboxes,
           failedMailboxReasons,
-          omittedMessages
+          omittedMessages,
+          ...stopped
         };
       }
       const text = `Found ${rows.length} message(s) via IMAP (server-side, account ${cfg.accountLabel}, ${scope}; ${totalText} ${verb}):
@@ -66059,7 +66163,8 @@ Note: these IMAP IDs (imap:\u2026) work with get-message and the message mutatio
         partial: partial2,
         failedMailboxes,
         failedMailboxReasons,
-        omittedMessages
+        omittedMessages,
+        ...stopped
       };
     },
     true
@@ -66202,6 +66307,20 @@ async function dropPool(key) {
   await e.client.logout().catch(() => void 0);
   e.client.close?.();
 }
+function abandonClient(client, cfg, deps) {
+  if (!deps.connect) {
+    const key = poolKey(cfg);
+    const entry = pools.get(key);
+    if (entry && entry.client === client) {
+      if (entry.idle) clearTimeout(entry.idle);
+      pools.delete(key);
+    }
+  }
+  try {
+    client.close?.();
+  } catch {
+  }
+}
 async function dropAllPools() {
   await Promise.all([...pools.keys()].map((k) => dropPool(k)));
 }
@@ -67200,6 +67319,7 @@ var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED,
 var init_imapClient = __esm({
   "src/services/imapClient.ts"() {
     "use strict";
+    init_callStop();
     import_imapflow = __toESM(require_imap_flow(), 1);
     init_smtpMailer();
     init_docsUrls();
@@ -82603,6 +82723,44 @@ var READ_ONLY_BYID_TIMEOUT_MS = 15e3;
 function timedOutResolvingId(id) {
   return `AppleScript timed out resolving id ${Number(id)} \u2014 Mail.app's scripting bridge may be wedged; try health-check.`;
 }
+function timedOutScanningForId(id) {
+  return `AppleScript timed out scanning every mailbox for id ${Number(id)} \u2014 the cross-mailbox scan did not finish within ${READ_ONLY_BYID_TIMEOUT_MS / 1e3}s (very large mailboxes; if health-check also fails, Mail.app's scripting bridge may be wedged). Pass account + mailbox to read it from one mailbox, or use the message's imap: id from list-messages/search-messages.`;
+}
+function getByIdScanThreshold() {
+  const raw = process.env.APPLE_MAIL_MAX_BYID_SCAN_MAILBOX;
+  if (raw !== void 0 && raw.trim() !== "") {
+    const n = Number(raw);
+    if (Number.isFinite(n) && n >= 0) return Math.floor(n);
+  }
+  return 5e4;
+}
+var BYID_SCAN_BUDGET_SECONDS = 9;
+var BYID_COVERAGE_MARKER = "COV";
+var SCOPED_MISS_MARKER = "SCOPED";
+function describeUnscopedMiss(id, raw) {
+  const covIdx = raw.indexOf(BYID_COVERAGE_MARKER);
+  if (covIdx === -1) return raw.trim();
+  const base2 = raw.slice(0, covIdx).trim();
+  const [skippedRaw = "", budgetRaw = ""] = raw.slice(covIdx + BYID_COVERAGE_MARKER.length).split(DIAG_FIELD_SEP);
+  const skipped = skippedRaw.split(DIAG_ITEM_SEP).map((s) => s.trim()).filter(Boolean);
+  const budgetHit = budgetRaw.trim() === "true";
+  if (skipped.length === 0 && !budgetHit) return base2;
+  const parts = [`Message ${Number(id)} not found in the mailboxes scanned.`];
+  if (skipped.length > 0) {
+    parts.push(
+      `Not scanned \u2014 too large for a cross-mailbox id scan (over ${getByIdScanThreshold()} messages; APPLE_MAIL_MAX_BYID_SCAN_MAILBOX): ${skipped.join(", ")}.`
+    );
+  }
+  if (budgetHit) {
+    parts.push(
+      `The scan also stopped after its ${BYID_SCAN_BUDGET_SECONDS}s budget before reaching every mailbox.`
+    );
+  }
+  parts.push(
+    "If the message is in a mailbox that was not scanned, pass account + mailbox to read it from that mailbox directly, or use its imap: id from list-messages/search-messages."
+  );
+  return parts.join(" ");
+}
 var GROUP_SEP = "";
 var FIELD_SEP = "";
 var RECORD_SEP = "";
@@ -83108,8 +83266,9 @@ var AppleMailManager = class {
    * Items") isn't reached before the AppleScript timeout fires, so the fetch
    * returns a false "not found" (only INBOX ids, reached early, worked). Every
    * search/list/by-id result records its id→location here so a subsequent fetch
-   * opens the one right mailbox directly. A stale entry (message moved) simply
-   * misses and falls back to the full scan, so it can never wedge a lookup.
+   * opens the one right mailbox directly. A stale entry (message moved by
+   * another client) misses, is EVICTED, and the read falls back to the bounded
+   * cross-mailbox scan — see `resolveScopedById` (#270).
    */
   idLocationIndex = /* @__PURE__ */ new Map();
   /** Error from the most recent numeric message read, if it was refused. */
@@ -84209,8 +84368,12 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
   /**
    * Get a message by ID.
    *
-   * Note: Mail.app message IDs are unique per mailbox. This method searches
-   * all mailboxes in all accounts to find the message.
+   * Note: Mail.app message IDs are unique per mailbox. Resolution goes through
+   * `resolveById` — the remembered location first, then the bounded
+   * cross-mailbox scan — taking the FIRST copy found rather than refusing an id
+   * a label store repeats across INBOX / "All Mail": every caller of this reads
+   * per-message metadata (get-thread's seed subject, a mutation error's mailbox
+   * hint) that is identical across those copies.
    */
   getMessageById(id, deepAttachmentCheck = false) {
     this.lastMessageLookupError = void 0;
@@ -84220,14 +84383,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
                     if rawSrc contains "Content-Disposition: attachment" then set hasAtt to "true"
                   end try
                 end if` : "";
-    const script = buildAppLevelScript(`
-      try
-        repeat with acct in accounts
-          repeat with mb in mailboxes of acct
-            try
-              set matchingMsgs to (messages of mb whose id is ${Number(id)})
-              if (count of matchingMsgs) > 0 then
-                set msg to item 1 of matchingMsgs
+    const innerFetch = `
                 set msgSubject to subject of msg
                 set msgSender to sender of msg
                 set d to date received of msg
@@ -84237,31 +84393,20 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
                 set msgJunk to junk mail status of msg as string
                 set msgDeleted to deleted status of msg as string
                 set msgMailbox to ""
-                ${mailboxPathFragment("mb", "msgMailbox")}
-                set msgAccount to name of acct
+                try
+                  ${mailboxPathFragment("_hitMb", "msgMailbox")}
+                end try
+                set msgAccount to _hitAcct
                 set hasAtt to "false"
                 try
                   set attCount to count of mail attachments of msg
                   if attCount > 0 then set hasAtt to "true"
                 end try
                 ${deepScan}
-                return msgSubject & "${FIELD_SEP}" & msgSender & "${FIELD_SEP}" & msgDate & "${FIELD_SEP}" & msgRead & "${FIELD_SEP}" & msgFlagged & "${FIELD_SEP}" & msgJunk & "${FIELD_SEP}" & msgDeleted & "${FIELD_SEP}" & msgMailbox & "${FIELD_SEP}" & msgAccount & "${FIELD_SEP}" & hasAtt
-              end if
-            end try
-          end repeat
-        end repeat
-        return ""
-      on error errMsg
-        return ""
-      end try
-    `);
-    const result = executeAppleScript(script, { timeoutMs: READ_ONLY_BYID_TIMEOUT_MS });
-    if (!result.success || !result.output.trim()) {
-      if (result.timedOut) this.lastMessageLookupError = timedOutResolvingId(id);
-      console.error(`Failed to get message ${id}: ${result.error}`);
-      return null;
-    }
-    const parts = result.output.split(FIELD_SEP);
+                return msgSubject & "${FIELD_SEP}" & msgSender & "${FIELD_SEP}" & msgDate & "${FIELD_SEP}" & msgRead & "${FIELD_SEP}" & msgFlagged & "${FIELD_SEP}" & msgJunk & "${FIELD_SEP}" & msgDeleted & "${FIELD_SEP}" & msgMailbox & "${FIELD_SEP}" & msgAccount & "${FIELD_SEP}" & hasAtt`;
+    const output = this.resolveById(id, innerFetch, void 0, { firstHit: true });
+    if (output === null) return null;
+    const parts = output.split(FIELD_SEP);
     if (parts.length < 9) return null;
     this.rememberLocation(id.toString(), parts[8], parts[7]);
     return {
@@ -84279,47 +84424,194 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       hasAttachments: parts.length > 9 ? parts[9] === "true" : false
     };
   }
+  /**
+   * Resolve numeric `id` and run `innerAction` against it — the ONE resolution
+   * path behind every read-only by-id lookup (getMessageById,
+   * getMessageContent, getMessageHeaders, getRawSource), so the four cannot
+   * drift apart again. Returns the action's output, or null with
+   * `lastMessageLookupError` set when there is something to say (#270):
+   *
+   *  1. Scoped, when a location is known — the caller's explicit `account` +
+   *     `mailbox`, else the `idLocationIndex` entry (see `resolveScopedById`):
+   *     - explicit hint, miss → a clean "not found in <account> / <mailbox>".
+   *       NO fallback: the caller said where to look, and the cross-mailbox
+   *       scan it would fall back to is the 20-50s operation @j5pu timed.
+   *     - index entry, miss → the entry is stale (the message was moved, by
+   *       another client or in Mail itself): evict it, then fall back to (2).
+   *     - timeout on either → report it; no second 15s scan on top.
+   *  2. Unscoped: every mailbox of every account plus the local store, but
+   *     mailboxes above `getByIdScanThreshold()` are skipped and the walk stops
+   *     at `BYID_SCAN_BUDGET_SECONDS`; a miss names what was not covered.
+   */
+  resolveById(id, innerAction, hint, opts = {}) {
+    const remembered = this.idLocationIndex.get(String(id));
+    const loc = hint?.account && hint?.mailbox ? { account: hint.account, mailbox: hint.mailbox, explicit: true } : remembered ? { ...remembered, explicit: false } : void 0;
+    if (loc) {
+      const scoped = this.resolveScopedById(id, loc, innerAction);
+      if (scoped.kind === "hit") return scoped.output;
+      if (scoped.kind === "done") return null;
+    }
+    const result = executeAppleScript(this.unscopedByIdScript(id, innerAction, opts), {
+      timeoutMs: READ_ONLY_BYID_TIMEOUT_MS
+    });
+    if (!result.success || !result.output.trim()) {
+      if (!result.success) {
+        if (result.timedOut) this.lastMessageLookupError = timedOutScanningForId(id);
+        console.error(`Failed to resolve message ${id}: ${result.error}`);
+      }
+      return null;
+    }
+    if (result.output.startsWith(LOOKUP_ERROR_MARKER)) {
+      this.lastMessageLookupError = describeUnscopedMiss(
+        id,
+        result.output.slice(LOOKUP_ERROR_MARKER.length)
+      );
+      return null;
+    }
+    return result.output;
+  }
+  /**
+   * The scoped half of `resolveById`: open exactly `loc`'s mailbox and look for
+   * the id there. `hit` carries the action's output; `done` means stop with
+   * `lastMessageLookupError` set; `fallback` means the remembered location was
+   * stale and has been evicted, so the caller should try the bounded scan.
+   */
+  resolveScopedById(id, loc, innerAction) {
+    const result = executeAppleScript(
+      this.scopedByIdScript(loc.account, loc.mailbox, id, innerAction),
+      { timeoutMs: READ_ONLY_BYID_TIMEOUT_MS }
+    );
+    const where = `${loc.account} / ${loc.mailbox}`;
+    if (!result.success) {
+      console.error(`Failed to read message ${id} from ${where}: ${result.error}`);
+      if (result.timedOut) {
+        this.lastMessageLookupError = timedOutResolvingId(id);
+        return { kind: "done" };
+      }
+      if (loc.explicit) {
+        this.lastMessageLookupError = `Could not read message ${Number(id)} from ${where}: ${result.error ?? "AppleScript error"}`;
+        return { kind: "done" };
+      }
+      this.forgetLocation(id);
+      return { kind: "fallback" };
+    }
+    const scopedPrefix = LOOKUP_ERROR_MARKER + SCOPED_MISS_MARKER;
+    if (result.output.trim() && !result.output.startsWith(scopedPrefix)) {
+      return { kind: "hit", output: result.output };
+    }
+    if (!loc.explicit) {
+      this.forgetLocation(id);
+      return { kind: "fallback" };
+    }
+    const reason = result.output.startsWith(scopedPrefix) ? result.output.slice(scopedPrefix.length) : "nomessage";
+    if (reason === "nomailbox") {
+      this.lastMessageLookupError = `Mailbox "${loc.mailbox}" not found in account "${loc.account}" \u2014 message ${Number(id)} was not looked up. Check the names with list-mailboxes, or omit account/mailbox to scan every mailbox.`;
+    } else if (reason.startsWith("error:")) {
+      this.lastMessageLookupError = `Could not read message ${Number(id)} from ${where}: ${reason.slice("error:".length)}`;
+    } else {
+      this.lastMessageLookupError = `Message ${Number(id)} not found in ${where} \u2014 it may have been moved or deleted. Re-list or search to get its current id, or omit account/mailbox to scan every mailbox.`;
+    }
+    return { kind: "done" };
+  }
+  /** Drop a stale id→location entry (#270) so the next read doesn't retry it. */
+  forgetLocation(id) {
+    this.idLocationIndex.delete(String(id));
+  }
   /**
    * The unscoped by-id resolution: walk every mailbox of every account, then the
    * local store (#183), and run `innerAction` with `msg` bound when EXACTLY one
-   * mailbox holds the id — `{LOOKUP_ERROR_MARKER}` prefixes both the not-found
-   * and the ambiguous outcome. Shared by getMessageContent, getRawSource and
-   * getMessageHeaders so the three reads cannot drift apart (the pre-#224 code
-   * carried two byte-identical copies).
+   * mailbox holds the id (or on the first hit, with `firstHit`) —
+   * `{LOOKUP_ERROR_MARKER}` prefixes both the not-found and the ambiguous
+   * outcome. `_hitMb` / `_hitAcct` are bound to the hit's mailbox and account
+   * name alongside `msg`.
+   *
+   * Bounded (#270): a mailbox above `getByIdScanThreshold()` messages is
+   * skipped rather than probed, and the walk stops once it has run for
+   * `BYID_SCAN_BUDGET_SECONDS`. Either way the not-found outcome carries a
+   * `BYID_COVERAGE_MARKER` trailer naming what was not covered, so the caller
+   * can say "not found in the mailboxes scanned; these large ones were not"
+   * instead of a false flat "not found". A copy that sits only in a skipped
+   * mailbox therefore no longer counts toward the ambiguity check — harmless
+   * for these read-only lookups, whose copies are the same message.
    */
-  unscopedByIdScript(id, innerAction) {
+  unscopedByIdScript(id, innerAction, opts = {}) {
+    const threshold = getByIdScanThreshold();
+    const sizeGuard = (mbVar, acctNameExpr) => threshold > 0 ? `set _mbCount to 0
+            try
+              set _mbCount to count of messages of ${mbVar}
+            end try
+            if _mbCount > ${threshold} then
+              set _skipPath to ""
+              try
+                ${mailboxPathFragment(mbVar, "_skipPath")}
+              end try
+              set _skipped to _skipped & ${acctNameExpr} & " / " & _skipPath & " (" & (_mbCount as string) & ")${DIAG_ITEM_SEP}"
+              set _probe to false
+            end if` : "";
+    const budgetCheck = `if ((current date) - _startedAt) > ${BYID_SCAN_BUDGET_SECONDS} then
+              set _budgetHit to true
+              exit repeat
+            end if`;
+    const stopOnHit = opts.firstHit ? `if (count of _hits) > 0 then exit repeat` : "";
     return buildAppLevelScript(`
       try
         set _hits to {}
+        set _hitMbs to {}
+        set _hitAccts to {}
         set _names to ""
+        set _skipped to ""
+        set _budgetHit to false
+        set _startedAt to current date
         repeat with acct in accounts
+          if _budgetHit then exit repeat
+          ${stopOnHit}
           repeat with mb in mailboxes of acct
-            try
-              set matchingMsgs to (messages of mb whose id is ${Number(id)})
-              if (count of matchingMsgs) > 0 then
-                set end of _hits to item 1 of matchingMsgs
-                set _names to _names & (name of acct) & "/" & (name of mb) & ", "
-              end if
-            end try
+            ${budgetCheck}
+            set _probe to true
+            ${sizeGuard("mb", "(name of acct)")}
+            if _probe then
+              try
+                set matchingMsgs to (messages of mb whose id is ${Number(id)})
+                if (count of matchingMsgs) > 0 then
+                  set end of _hits to item 1 of matchingMsgs
+                  set end of _hitMbs to (contents of mb)
+                  set end of _hitAccts to (name of acct)
+                  set _names to _names & (name of acct) & "/" & (name of mb) & ", "
+                end if
+              end try
+            end if
+            ${stopOnHit}
           end repeat
         end repeat
         -- #183: local mailboxes belong to no account, so the walk above cannot
         -- reach them. Collect into the SAME _hits/_names, which means an id
         -- present both in an account and locally is now correctly reported as
-        -- ambiguous rather than silently resolving to the account copy.${localMailboxBindingFragment()}
-        repeat with mb in _mbs
-          try
-            set matchingMsgs to (messages of mb whose id is ${Number(id)})
-            if (count of matchingMsgs) > 0 then
-              set end of _hits to item 1 of matchingMsgs
-              set _names to _names & "${LOCAL_STORE_LABEL}/" & (name of mb) & ", "
+        -- ambiguous rather than silently resolving to the account copy.
+        if (not _budgetHit) and ${opts.firstHit ? "(count of _hits) is 0" : "true"} then${localMailboxBindingFragment()}
+          repeat with mb in _mbs
+            ${budgetCheck}
+            set _probe to true
+            ${sizeGuard("mb", `"${LOCAL_STORE_LABEL}"`)}
+            if _probe then
+              try
+                set matchingMsgs to (messages of mb whose id is ${Number(id)})
+                if (count of matchingMsgs) > 0 then
+                  set end of _hits to item 1 of matchingMsgs
+                  set end of _hitMbs to (contents of mb)
+                  set end of _hitAccts to "${LOCAL_STORE_LABEL}"
+                  set _names to _names & "${LOCAL_STORE_LABEL}/" & (name of mb) & ", "
+                end if
+              end try
             end if
-          end try
-        end repeat
-        if (count of _hits) is 0 then return "${LOOKUP_ERROR_MARKER}Message not found"
-        if (count of _hits) > 1 then return "${LOOKUP_ERROR_MARKER}${AMBIGUOUS_ID_PREFIX}${Number(id)} is present in more than one mailbox (" & _names & "); list or search that mailbox first so the read targets the right copy"
-        if (count of _hits) is 1 then
+            ${stopOnHit}
+          end repeat
+        end if
+        if (count of _hits) is 0 then return "${LOOKUP_ERROR_MARKER}Message not found${BYID_COVERAGE_MARKER}" & _skipped & "${DIAG_FIELD_SEP}" & (_budgetHit as string)
+        ${opts.firstHit ? "" : `if (count of _hits) > 1 then return "${LOOKUP_ERROR_MARKER}${AMBIGUOUS_ID_PREFIX}${Number(id)} is present in more than one mailbox (" & _names & "); list or search that mailbox first so the read targets the right copy"`}
+        if (count of _hits) ${opts.firstHit ? "> 0" : "is 1"} then
           set msg to item 1 of _hits
+          set _hitMb to item 1 of _hitMbs
+          set _hitAcct to item 1 of _hitAccts
           ${innerAction}
         end if
         return ""
@@ -84331,20 +84623,25 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
   /**
    * Build an app-level AppleScript that opens exactly one account+mailbox, finds
    * the message with numeric `id` in it, and runs `innerAction` (which may assume
-   * `msg` is bound). Used by the by-id fast paths (getMessageContent/getRawSource)
-   * so a message in a late-iterated large folder resolves directly instead of via
-   * the timeout-prone full-mailbox scan.
+   * `msg`, `_hitMb` and `_hitAcct` are bound). Used by the by-id fast path
+   * (`resolveScopedById`) so a message in a late-iterated large folder resolves
+   * directly instead of via the timeout-prone full-mailbox scan.
    *
    * The mailbox name is resolved through `resolveMailbox` (so an alias like
    * "Sent"→"Sent Items" or a casing mismatch like "INBOX"→"Inbox" still opens the
    * right folder), and matched case-insensitively by iterating the account's
    * mailboxes — `mailbox "INBOX" of account …` throws on accounts whose inbox is
    * actually named "Inbox", which would silently drop us back to the slow scan.
-   * Returns "" (found nothing) on any error, so the caller falls back safely.
+   *
+   * A miss is reported, not swallowed (#270): `{LOOKUP_ERROR_MARKER}
+   * {SCOPED_MISS_MARKER}` followed by `nomailbox`, `nomessage` or
+   * `error:<Mail's text>`, so the caller can return a clean "not found in
+   * <mailbox>" for an explicit hint instead of guessing.
    */
   scopedByIdScript(account, mailbox, id, innerAction) {
     const resolved = this.resolveMailbox(mailbox, account);
     const bind = isLocalStoreLabel(account) ? `${localMailboxBindingFragment()}
+        set _hitAcct to "${LOCAL_STORE_LABEL}"
         set targetMb to missing value
         ignoring case
           repeat with mb in _mbs
@@ -84356,6 +84653,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
             end if
           end repeat
         end ignoring` : `set acct to (first account whose name is "${escapeForAppleScript(account)}")
+        set _hitAcct to (name of acct)
         set targetMb to missing value
         ignoring case
           repeat with mb in mailboxes of acct
@@ -84367,19 +84665,19 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
             end if
           end repeat
         end ignoring`;
+    const miss = `${LOOKUP_ERROR_MARKER}${SCOPED_MISS_MARKER}`;
     return buildAppLevelScript(`
       try
         ${bind}
-        if targetMb is not missing value then
-          set matchingMsgs to (messages of targetMb whose id is ${Number(id)})
-          if (count of matchingMsgs) > 0 then
-            set msg to item 1 of matchingMsgs
-            ${innerAction}
-          end if
-        end if
+        if targetMb is missing value then return "${miss}nomailbox"
+        set _hitMb to (contents of targetMb)
+        set matchingMsgs to (messages of targetMb whose id is ${Number(id)})
+        if (count of matchingMsgs) is 0 then return "${miss}nomessage"
+        set msg to item 1 of matchingMsgs
+        ${innerAction}
         return ""
       on error errMsg
-        return ""
+        return "${miss}error:" & errMsg
       end try
     `);
   }
@@ -84392,6 +84690,9 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
    *   source can be MB-sized (it includes base64 attachments) and the plain-text
    *   path doesn't need it; fetching it unconditionally was both slow and, worse,
    *   returned the entire raw MIME blob mislabeled as HTML (#32).
+   * @param hint - Explicit account + mailbox (both required to take effect):
+   *   the read opens that one mailbox and, on a miss, reports "not found in
+   *   <account> / <mailbox>" without scanning anywhere else (#270).
    */
   getMessageContent(id, includeHtml = false, hint) {
     this.lastMessageLookupError = void 0;
@@ -84409,41 +84710,15 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
                 ${sourceFetch}
                 ${AS_MESSAGE_DATES_FRAGMENT}
                 return msgSubject & "${MSGID_MARKER}" & msgRfcId & "${DATES_MARKER}" & msgDates & "${CONTENT_MARKER}" & msgContent & "${HTML_MARKER}" & htmlSource`;
-    const loc = hint?.account && hint?.mailbox ? { account: hint.account, mailbox: hint.mailbox } : this.idLocationIndex.get(id.toString());
-    if (loc) {
-      const scopedScript = this.scopedByIdScript(loc.account, loc.mailbox, id, innerFetch);
-      const scoped = this.parseMessageContent(
-        id,
-        executeAppleScript(scopedScript, { timeoutMs: READ_ONLY_BYID_TIMEOUT_MS }),
-        includeHtml
-      );
-      if (scoped) return scoped;
-    }
-    const script = this.unscopedByIdScript(id, innerFetch);
-    return this.parseMessageContent(
-      id,
-      executeAppleScript(script, { timeoutMs: READ_ONLY_BYID_TIMEOUT_MS }),
-      includeHtml
-    );
+    const output = this.resolveById(id, innerFetch, hint);
+    return output === null ? null : this.parseMessageContent(id, output, includeHtml);
   }
   /**
    * Parse the marker-delimited output of a getMessageContent AppleScript into a
-   * MessageContent, or null when nothing was found / the fetch failed. Shared by
-   * the scoped fast path and the full-mailbox-scan fallback.
+   * MessageContent, or null when the payload is malformed.
    */
-  parseMessageContent(id, result, includeHtml) {
-    if (!result.success || !result.output.trim()) {
-      if (!result.success) {
-        if (result.timedOut) this.lastMessageLookupError = timedOutResolvingId(id);
-        console.error(`Failed to get message content: ${result.error}`);
-      }
-      return null;
-    }
-    if (result.output.startsWith(LOOKUP_ERROR_MARKER)) {
-      this.lastMessageLookupError = result.output.slice(LOOKUP_ERROR_MARKER.length).trim();
-      return null;
-    }
-    const htmlSplit = result.output.split(HTML_MARKER);
+  parseMessageContent(id, output, includeHtml) {
+    const htmlSplit = output.split(HTML_MARKER);
     const contentPart = htmlSplit[0];
     const rawSource = htmlSplit.length > 1 ? htmlSplit[1] : "";
     const parts = contentPart.split(CONTENT_MARKER);
@@ -84468,8 +84743,8 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
   /**
    * Fetch ONLY the raw RFC 5322 header block of a message (#224) — Mail's
    * `all headers` property — plus its `date received`, so the caller can show the
-   * arrival timestamp beside the author's `Date:` header. Same scoped-fast-path /
-   * full-scan resolution as getMessageContent; never reads the body or source.
+   * arrival timestamp beside the author's `Date:` header. Same resolution as
+   * getMessageContent (resolveById); never reads the body or source.
    * Returns null (with `lastMessageLookupError` set when Mail said why) on a miss.
    */
   getMessageHeaders(id, hint) {
@@ -84481,39 +84756,14 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
                 end try
                 ${AS_MESSAGE_DATES_FRAGMENT}
                 return msgDates & "${DATES_MARKER}" & msgHeaders`;
-    const parse4 = (result) => {
-      if (!result.success || !result.output.trim()) {
-        if (!result.success) {
-          if (result.timedOut) this.lastMessageLookupError = timedOutResolvingId(id);
-          console.error(`Failed to get message headers: ${result.error}`);
-        }
-        return null;
-      }
-      if (result.output.startsWith(LOOKUP_ERROR_MARKER)) {
-        this.lastMessageLookupError = result.output.slice(LOOKUP_ERROR_MARKER.length).trim();
-        return null;
-      }
-      const idx = result.output.indexOf(DATES_MARKER);
-      if (idx === -1) return null;
-      const { dateReceived } = parseMessageDates(result.output.slice(0, idx));
-      const raw = result.output.slice(idx + DATES_MARKER.length);
-      if (!raw.trim()) return null;
-      return { raw, ...dateReceived ? { dateReceived } : {} };
-    };
-    const loc = hint?.account && hint?.mailbox ? { account: hint.account, mailbox: hint.mailbox } : this.idLocationIndex.get(id.toString());
-    if (loc) {
-      const scoped = parse4(
-        executeAppleScript(this.scopedByIdScript(loc.account, loc.mailbox, id, innerFetch), {
-          timeoutMs: READ_ONLY_BYID_TIMEOUT_MS
-        })
-      );
-      if (scoped) return scoped;
-    }
-    return parse4(
-      executeAppleScript(this.unscopedByIdScript(id, innerFetch), {
-        timeoutMs: READ_ONLY_BYID_TIMEOUT_MS
-      })
-    );
+    const output = this.resolveById(id, innerFetch, hint);
+    if (output === null) return null;
+    const idx = output.indexOf(DATES_MARKER);
+    if (idx === -1) return null;
+    const { dateReceived } = parseMessageDates(output.slice(0, idx));
+    const raw = output.slice(idx + DATES_MARKER.length);
+    if (!raw.trim()) return null;
+    return { raw, ...dateReceived ? { dateReceived } : {} };
   }
   /**
    * Get the raw MIME source of a message.
@@ -84527,38 +84777,11 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
    * that budget; a call still running past it is a wedged scripting bridge,
    * not legitimate transfer time, so there is no case where the old 120s
    * ceiling was buying a real result a shorter one would have missed.
+   * Same resolution as getMessageContent (resolveById).
    */
   getRawSource(id, hint) {
     this.lastMessageLookupError = void 0;
-    const loc = hint?.account && hint?.mailbox ? { account: hint.account, mailbox: hint.mailbox } : this.idLocationIndex.get(id.toString());
-    if (loc) {
-      const scopedScript = this.scopedByIdScript(
-        loc.account,
-        loc.mailbox,
-        id,
-        "return source of msg"
-      );
-      const scoped = executeAppleScript(scopedScript, { timeoutMs: READ_ONLY_BYID_TIMEOUT_MS });
-      if (scoped.success && scoped.output.trim() && !scoped.output.startsWith(LOOKUP_ERROR_MARKER)) {
-        return scoped.output;
-      }
-      if (scoped.success && scoped.output.startsWith(LOOKUP_ERROR_MARKER)) {
-        this.lastMessageLookupError = scoped.output.slice(LOOKUP_ERROR_MARKER.length).trim();
-      } else if (!scoped.success && scoped.timedOut) {
-        this.lastMessageLookupError = timedOutResolvingId(id);
-      }
-    }
-    const script = this.unscopedByIdScript(id, "return source of msg");
-    const result = executeAppleScript(script, { timeoutMs: READ_ONLY_BYID_TIMEOUT_MS });
-    if (!result.success || !result.output.trim()) {
-      if (result.timedOut) this.lastMessageLookupError = timedOutResolvingId(id);
-      return null;
-    }
-    if (result.output.startsWith(LOOKUP_ERROR_MARKER)) {
-      this.lastMessageLookupError = result.output.slice(LOOKUP_ERROR_MARKER.length).trim();
-      return null;
-    }
-    return result.output;
+    return this.resolveById(id, "return source of msg", hint);
   }
   /**
    * List messages in a mailbox.
@@ -87497,10 +87720,14 @@ function currentCallTiming() {
   return callTiming.getStore();
 }
 function withErrorHandling(handler, errorPrefix) {
-  return async (params) => {
+  return async (params, extra) => {
     const arrivedAt = Date.now();
+    const signal = extra?.signal;
     return serializeAppleScript(async () => {
-      const timing = { arrivedAt, queueWaitMs: Date.now() - arrivedAt };
+      if (signal?.aborted) {
+        return errorResponse(`${errorPrefix}: request was cancelled before it started`);
+      }
+      const timing = { arrivedAt, queueWaitMs: Date.now() - arrivedAt, signal };
       return callTiming.run(timing, async () => {
         try {
           return await handler(params);
@@ -87530,10 +87757,12 @@ async function readOriginal(deps, id, cfg) {
     return { original, plainText: extractTextBody(source.raw) };
   }
   const raw = deps.mail.getRawSource(id);
-  if (!raw)
+  if (!raw) {
+    const why = deps.mail.consumeLastMessageLookupError?.();
     throw new Error(
-      "Cannot read the original message source. Re-list the intended mailbox and retry with its message id."
+      `Cannot read the original message source${why ? ` (${why})` : ""}. Re-list the intended mailbox and retry with its message id.`
     );
+  }
   const content = deps.mail.getMessageContent(id);
   return { original: parseOriginalHeaders(raw), plainText: content?.plainText ?? null };
 }
@@ -87759,6 +87988,9 @@ function unlistableStoreError(account, error3, knownAccounts) {
   return parts.join("\n\n");
 }
 
+// src/index.ts
+init_callStop();
+
 // src/tools/batchResults.ts
 async function hybridBatchCounts(ids, appleFn, imapFn) {
   const distinctIds = [...new Set(ids)];
@@ -87937,12 +88169,17 @@ function mergeMessages(imapRows, appleRows, limit) {
 }
 async function fanOutImapMessages(args, kind, deps = {}, configs = resolveImapConfigs()) {
   const rows = [];
+  const timedOutMailboxes = [];
   const accountsQueried = [];
   const accountsFailed = [];
   const failedMailboxes = [];
   const failedMailboxReasons = {};
   const omittedMessages = [];
   for (const config2 of configs) {
+    if (deps.signal?.aborted) {
+      timedOutMailboxes.push(`${config2.accountLabel} / *`);
+      continue;
+    }
     const perAccountArgs = { ...args, account: void 0 };
     try {
       const res = kind === "search" ? await imapSearchMessages(perAccountArgs, { ...deps, config: config2 }) : await imapListMessages(perAccountArgs, { ...deps, config: config2 });
@@ -87954,6 +88191,9 @@ async function fanOutImapMessages(args, kind, deps = {}, configs = resolveImapCo
       for (const [mailbox, reason] of Object.entries(res.failedMailboxReasons)) {
         failedMailboxReasons[`${config2.accountLabel} / ${mailbox}`] = reason;
       }
+      timedOutMailboxes.push(
+        ...(res.timedOutMailboxes ?? []).map((mailbox) => `${config2.accountLabel} / ${mailbox}`)
+      );
       omittedMessages.push(
         ...(res.omittedMessages ?? []).map((o) => ({
           ...o,
@@ -87971,7 +88211,8 @@ async function fanOutImapMessages(args, kind, deps = {}, configs = resolveImapCo
     accountsFailed,
     failedMailboxes,
     failedMailboxReasons,
-    omittedMessages
+    omittedMessages,
+    timedOutMailboxes
   };
 }
 function configMatchesAccount(config2, account) {
@@ -88589,7 +88830,11 @@ var LIST_OUTPUT_SCHEMA = {
   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()
+  omittedMessages: external_exports.array(external_exports.object({ id: external_exports.string(), mailbox: external_exports.string(), uid: external_exports.number(), reason: external_exports.string() })).optional(),
+  // Mailboxes a cancelled or out-of-time search-messages never finished (#276),
+  // and why. Non-empty implies `partial: true`.
+  timedOutMailboxes: external_exports.array(external_exports.string()).optional(),
+  stoppedBy: external_exports.enum(["deadline", "cancelled"]).optional()
 };
 var BATCH_COUNT_OUTPUT_SCHEMA = {
   ok: external_exports.boolean().optional(),
@@ -88664,11 +88909,12 @@ function appleScanForAccounts(accounts, scan) {
   }
   return { rows, diagnostics };
 }
-function mergedMessageResponse(fan, apple, limit, verb) {
+function mergedMessageResponse(fan, apple, limit, verb, stopSignal) {
   const merged = mergeMessages(fan.rows, apple.rows, limit);
+  const timedOutMailboxes = fan.timedOutMailboxes ?? [];
   const diagnostics = {
     ...apple.diagnostics,
-    partial: apple.diagnostics.partial || fan.accountsFailed.length > 0 || fan.failedMailboxes.length > 0 || fan.omittedMessages.length > 0,
+    partial: apple.diagnostics.partial || fan.accountsFailed.length > 0 || fan.failedMailboxes.length > 0 || fan.omittedMessages.length > 0 || timedOutMailboxes.length > 0,
     timedOutAccounts: [...apple.diagnostics.timedOutAccounts, ...fan.accountsFailed],
     notSearchedMailboxes: [...apple.diagnostics.notSearchedMailboxes, ...fan.failedMailboxes]
   };
@@ -88681,9 +88927,13 @@ function mergedMessageResponse(fan, apple, limit, verb) {
     timedOutAccounts: diagnostics.timedOutAccounts,
     failedMailboxes: fan.failedMailboxes,
     failedMailboxReasons: fan.failedMailboxReasons,
-    omittedMessages: fan.omittedMessages
+    omittedMessages: fan.omittedMessages,
+    ...timedOutMailboxes.length > 0 ? {
+      timedOutMailboxes,
+      stoppedBy: stoppedByDeadline(stopSignal) ? "deadline" : "cancelled"
+    } : {}
   };
-  const coverageBlock = partialCoverageBlock(diagnostics) + omittedNote(fan.omittedMessages, true);
+  const coverageBlock = partialCoverageBlock(diagnostics) + omittedNote(fan.omittedMessages, true) + stoppedNote(timedOutMailboxes, stopSignal);
   if (merged.length === 0) {
     const base2 = diagnostics.partial ? `No messages found in the portions that were ${verb === "matched" ? "searched" : "listed"}.` : "No messages found";
     return successResponse(`${base2}${coverageBlock}`, structured);
@@ -88730,7 +88980,7 @@ function collectForensics(tool, args) {
 registerTool(
   "search-messages",
   {
-    description: "Use when: finding messages by query/sender/subject/date/read/flag filters and you need their ids for follow-up operations.\nReturns: matching messages with id, date, subject, sender, and read state (plus partial-coverage diagnostics when some mailboxes were skipped).\nDo not use when: you want a plain mailbox listing without filters (use list-messages), already have an id and want the body (use get-message), or want a whole conversation (use get-thread).\nPrefer this first to obtain the message ids that get-message/mark-as-read/delete-message/move-message and the batch tools require.",
+    description: "Use when: finding messages by query/sender/subject/date/read/flag filters and you need their ids for follow-up operations.\nReturns: matching messages with id, date, subject, sender, and read state (plus partial-coverage diagnostics when some mailboxes were skipped). An IMAP search stops at its deadline (APPLE_MAIL_MCP_SEARCH_DEADLINE_MS, default 45s) or when the request is cancelled, returning the matches found so far with partial: true and timedOutMailboxes \u2014 narrow with mailbox/dateFrom rather than repeating it.\nDo not use when: you want a plain mailbox listing without filters (use list-messages), already have an id and want the body (use get-message), or want a whole conversation (use get-thread).\nPrefer this first to obtain the message ids that get-message/mark-as-read/delete-message/move-message and the batch tools require.",
     inputSchema: {
       query: external_exports.string().optional().describe("Text to search for in subject or sender"),
       body: external_exports.string().optional().describe(
@@ -88773,6 +89023,15 @@ registerTool(
         if (tooDeep) return errorResponse(tooDeep);
       }
       if (shouldUseImap(account)) {
+        const stop = createCallStop(currentCallTiming(), searchDeadlineMs());
+        try {
+          return await searchViaImap(stop.signal);
+        } finally {
+          stop.dispose();
+        }
+      }
+      return searchViaAppleScript();
+      async function searchViaImap(signal) {
         const imapArgs = {
           query,
           body,
@@ -88787,14 +89046,15 @@ registerTool(
           isFlagged
         };
         if (account !== void 0) {
-          const r = await imapSearchMessages({ ...imapArgs, account });
+          const r = await imapSearchMessages({ ...imapArgs, account }, { signal });
           return successResponse(r.text, {
             messages: r.messages,
             count: r.count,
             partial: r.partial,
             failedMailboxes: r.failedMailboxes,
             failedMailboxReasons: r.failedMailboxReasons,
-            omittedMessages: r.omittedMessages
+            omittedMessages: r.omittedMessages,
+            ...r.timedOutMailboxes?.length ? { timedOutMailboxes: r.timedOutMailboxes, stoppedBy: r.stoppedBy } : {}
           });
         }
         const { appleScriptOnly } = partitionAccountsForCounts(
@@ -88806,7 +89066,7 @@ registerTool(
             `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");
+        const fan = await fanOutImapMessages(imapArgs, "search", { signal });
         if (body) {
           const apple2 = {
             rows: [],
@@ -88818,7 +89078,18 @@ registerTool(
               )
             }
           };
-          return mergedMessageResponse(fan, apple2, limit, "matched");
+          return mergedMessageResponse(fan, apple2, limit, "matched", signal);
+        }
+        if (signal.aborted && appleScriptOnly.length > 0) {
+          const apple2 = {
+            rows: [],
+            diagnostics: {
+              ...emptyDiagnostics(),
+              partial: true,
+              timedOutAccounts: appleScriptOnly.map((a) => a.name)
+            }
+          };
+          return mergedMessageResponse(fan, apple2, limit, "matched", signal);
         }
         const apple = appleScanForAccounts(
           appleScriptOnly,
@@ -88835,51 +89106,53 @@ registerTool(
             isFlagged
           )
         );
-        return mergedMessageResponse(fan, apple, limit, "matched");
+        return mergedMessageResponse(fan, apple, limit, "matched", signal);
       }
-      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.`
+      function searchViaAppleScript() {
+        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.`
+          );
+        }
+        const { messages, diagnostics } = mailManager.searchMessagesWithDiagnostics(
+          query,
+          mailbox,
+          account,
+          limit,
+          dateFrom,
+          dateTo,
+          from,
+          subject,
+          isRead,
+          isFlagged
         );
-      }
-      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.`
+        const coverageBlock = partialCoverageBlock(diagnostics);
+        const structured = {
+          messages: messages.map(messageSummary),
+          count: messages.length,
+          partial: diagnostics.partial,
+          skippedLargeMailboxes: diagnostics.skippedLargeMailboxes,
+          notSearchedMailboxes: diagnostics.notSearchedMailboxes,
+          timedOutAccounts: diagnostics.timedOutAccounts
+        };
+        if (messages.length === 0) {
+          const base2 = diagnostics.partial ? "No messages found in the portions that were searched." : "No messages found matching criteria";
+          return successResponse(`${base2}${coverageBlock}`, structured);
+        }
+        const messageList = messages.map(
+          (m) => `  - ID: ${m.id} | ${m.dateReceived.toLocaleDateString()} | ${m.subject} (from: ${m.sender}) [${m.isRead ? "read" : "unread"}]`
+        ).join("\n");
+        return successResponse(
+          `Found ${messages.length} message(s):
+${messageList}${coverageBlock}`,
+          structured
         );
       }
-      const { messages, diagnostics } = mailManager.searchMessagesWithDiagnostics(
-        query,
-        mailbox,
-        account,
-        limit,
-        dateFrom,
-        dateTo,
-        from,
-        subject,
-        isRead,
-        isFlagged
-      );
-      const coverageBlock = partialCoverageBlock(diagnostics);
-      const structured = {
-        messages: messages.map(messageSummary),
-        count: messages.length,
-        partial: diagnostics.partial,
-        skippedLargeMailboxes: diagnostics.skippedLargeMailboxes,
-        notSearchedMailboxes: diagnostics.notSearchedMailboxes,
-        timedOutAccounts: diagnostics.timedOutAccounts
-      };
-      if (messages.length === 0) {
-        const base2 = diagnostics.partial ? "No messages found in the portions that were searched." : "No messages found matching criteria";
-        return successResponse(`${base2}${coverageBlock}`, structured);
-      }
-      const messageList = messages.map(
-        (m) => `  - ID: ${m.id} | ${m.dateReceived.toLocaleDateString()} | ${m.subject} (from: ${m.sender}) [${m.isRead ? "read" : "unread"}]`
-      ).join("\n");
-      return successResponse(
-        `Found ${messages.length} message(s):
-${messageList}${coverageBlock}`,
-        structured
-      );
     },
     "Error searching messages"
   )