apple-tools-mcp 3.2.1 → 3.2.3

package/README.md

@@ -66,7 +66,7 @@ Then open **System Settings → Privacy & Security → Accessibility** and turn
 
 The command does real work so the prompts can appear. It opens a Mail compose window and throws it away (nothing is sent), lists Messages accounts (nothing is sent), creates and deletes a throwaway contact, lists calendars without creating events, and checks System Events. It exits with an error until Mail, Messages, Contacts, Calendar, and System Events are all allowed.
 
-`dry_run` on `mail_send` or `messages_send` does not talk to those apps, so a dry run will not pop the prompts and will not tell you whether Automation is allowed. A real send that hangs after you denied Mail is an Automation denial, not "Mail could not be reached."
+`dry_run` on `mail_send` or `messages_send` does not talk to those apps, so a dry run will not pop the prompts and will not tell you whether Automation is allowed. A timeout alone does not prove an Automation denial; only an explicit permission error does.
 
 If you clicked **Don't Allow**, macOS will not ask again. Open **System Settings → Privacy & Security → Automation**, turn the switch on for that node and that app, then run `apple-tools-mcp permissions` again.
 
@@ -308,6 +308,10 @@ Every write tool accepts:
 
 Deletes need `confirm: true`: `mail_trash`, `calendar_remove`, `contacts_remove`, and `contacts_edit` when it clears every email or phone. These take one id per call, except `mail_trash`, which also takes a list (`message_ids`).
 
+`mail_send` supports a stable `idempotency_key` per intended delivery. Reuse it after a disconnect or timeout. An accepted send is replayed without sending again; changed content with the same key is refused. Without a key, identical accepted content is suppressed without expiry. Use a new key for an intentional repeat. Uncertain sends remain blocked without expiry: check Sent and Outbox before making any new delivery. A missing Sent result alone cannot prove a queued send will not complete. Claims persist across processes/restarts in the private `~/.apple-tools-mcp/mail-send-claims` directory, containing only SHA-256 hashes and outcome metadata. Dry runs create no claims. Only explicit pre-send failures allow a retry.
+
+A bridge request that expires before execution is rejected. After a handoff with an unknown outcome, local fallback is suppressed. The System Events preflight allows 10 seconds (12-second process cap); timeout reports `probe_timeout` and unknown permission status, separately from an explicit permission denial.
+
 Sends to more than one person need `confirm: true`: `mail_send` and `mail_forward` when To, Cc, and Bcc add up to more than one address, `mail_reply` with `reply_all: true`, and `messages_send` to several people or to a group chat. A single recipient sends on the first call. `mail_draft` never sends, so it does not need that confirm.
 
 A dry run or a call that still needs confirm does not deliver anything. The result is `ok: false`, `planned: true`, `delivered: false`, and the client may mark it as an error. The text says `DRY RUN` or `CONFIRMATION REQUIRED`. Run it again with `dry_run` false, and with `confirm: true` when the tool asked for it.
@@ -320,7 +324,7 @@ A missing or malformed id or recipient is refused. Calendar times are local date
 
 | Tool | Arguments | Confirm |
 |------|-----------|---------|
-| `mail_send` | `to[]` (required), `cc[]`, `bcc[]`, `subject` (required), `body` (required), `body_format` (`plain` or `html`) | when recipients > 1 |
+| `mail_send` | `to[]` (required), `cc[]`, `bcc[]`, `subject` (required), `body` (required), `body_format` (`plain` or `html`), `idempotency_key` | when recipients > 1 |
 | `mail_draft` | `to[]` (required), `cc[]`, `bcc[]`, `subject`, `body`, `body_format` | no (saved to Drafts) |
 | `mail_reply` | `message_id` or `file_path`, `body` (required), `reply_all`, `save_as_draft` | when `reply_all` is true |
 | `mail_forward` | `message_id` or `file_path`, `to[]` (required), `body`, `save_as_draft` | when recipients > 1 |

package/indexer.js

@@ -13,7 +13,7 @@ import {
   unfoldRfc822Headers,
   stripSubjectPrefixes
 } from "./lib/validators.js";
-import { safeSqlite3Json, safeOsascript, safeFind } from "./lib/shell.js";
+import { safeSqlite3Json, safeSqlite3JsonAsync, safeOsascript, safeFindAsync } from "./lib/shell.js";
 import { indexUnavailableMessage } from "./lib/indexGate.js";
 import { createLanceTableCache, LANCE_CONNECT_OPTIONS } from "./lib/lancedbTables.js";
 import { createMessageContactMatcher } from "./lib/messageContact.js";
@@ -362,7 +362,8 @@ async function findAllEmlxFiles() {
   // "*.emlx" also matches "*.partial.emlx"
   // Let permission/IO errors propagate so indexEmails does not persist a
   // timestamp for an empty scan and skip real mail forever.
-  return safeFind(MAIL_DIR, { name: "*.emlx", type: "f" });
+  // Async: the daemon keeps answering writer.sock while a slow scan runs.
+  return safeFindAsync(MAIL_DIR, { name: "*.emlx", type: "f" });
 }
 
 // Fast incremental scan - uses find with -mtime filter (more reliable than mdfind/Spotlight)
@@ -380,7 +381,7 @@ async function findNewEmlxFiles(sinceTimestamp) {
 
     // Use find with -mtime instead of mdfind for reliability
     // find is more reliable than Spotlight which can have stale/incomplete indexes
-    const files = safeFind(MAIL_DIR, { name: "*.emlx", type: "f", mtime: `-${daysAgo}` });
+    const files = await safeFindAsync(MAIL_DIR, { name: "*.emlx", type: "f", mtime: `-${daysAgo}` });
     console.error(`find found ${files.length} new/modified emails in last ${daysAgo} days`);
     return files;
   } catch (e) {
@@ -563,7 +564,7 @@ function extractTextFromAttributedBody(buffer) {
   }
 }
 
-function getMessages(sinceTimestamp = null) {
+async function getMessages(sinceTimestamp = null) {
   try {
     // Enhanced query to get chat info, group chat detection, and attachments
     // Include attributedBody for messages where text is NULL (newer macOS format)
@@ -599,7 +600,7 @@ function getMessages(sinceTimestamp = null) {
         ${dateFilter}
       ORDER BY m.date DESC
     `;
-    const results = safeSqlite3Json(MESSAGES_DB, query, { timeout: 60000 });
+    const results = await safeSqlite3JsonAsync(MESSAGES_DB, query, { timeout: 60000 });
     if (!Array.isArray(results)) {
       throw new Error("Unexpected sqlite3 result for messages");
     }
@@ -668,7 +669,7 @@ function getParticipantStatus(status) {
   return statusMap[status] || "unknown";
 }
 
-function getCalendarEvents() {
+async function getCalendarEvents() {
   // NOTE: We index ALL calendar events, not filtered by date
   // Calendar events don't have a "file modification time" like emails do,
   // so we can't use the mdfind + DAYS_BACK approach.
@@ -718,12 +719,12 @@ function getCalendarEvents() {
       WHERE p.entity_type = 0
     `;
 
-  return withCalendarCopy((dbPath) => {
-    const rows = safeSqlite3Json(dbPath, query, { timeout: 30000 });
+  return withCalendarCopyAsync(async (dbPath) => {
+    const rows = await safeSqlite3JsonAsync(dbPath, query, { timeout: 30000 });
 
     let attendeesMap = new Map();
     try {
-      const attendeesRows = safeSqlite3Json(dbPath, attendeesQuery, { timeout: 10000 });
+      const attendeesRows = await safeSqlite3JsonAsync(dbPath, attendeesQuery, { timeout: 10000 });
 
       for (const att of attendeesRows) {
         if (!attendeesMap.has(att.owner_id)) {
@@ -1165,7 +1166,7 @@ export async function indexMessages(forceFullScan = false) {
   // Use incremental scan if we have a previous timestamp
   let messages;
   try {
-    messages = getMessages(lastMessageIndexTime);
+    messages = await getMessages(lastMessageIndexTime);
   } catch (e) {
     console.error(`Messages source read failed; skipping this cycle so the lookback timestamp is not advanced: ${e.message}`);
     return { indexed: 0, added: 0, error: e.message };
@@ -1311,7 +1312,7 @@ export async function indexCalendar() {
 
   let events;
   try {
-    events = getCalendarEvents();
+    events = await getCalendarEvents();
   } catch (e) {
     // Do not treat a source-read failure as "zero events" — that would mark
     // every indexed row stale and delete the calendar index.
@@ -1791,34 +1792,54 @@ export function buildEventsOnDateQuery(startMac, endMac, { includeUid = true } =
 
 // Copy Calendar.sqlitedb (+ wal/shm) to /tmp for one query, then delete the copies.
 // Calendar.app holds a lock on the live db; sqlite can read a snapshot copy.
-function withCalendarCopy(fn) {
+function copyCalendarDb() {
   const id = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   const tmpDb = path.join("/tmp", `${CALENDAR_TMP_PREFIX}${id}.sqlitedb`);
-  const tmpWal = `${tmpDb}-wal`;
-  const tmpShm = `${tmpDb}-shm`;
-  const srcWal = `${CALENDAR_DB}-wal`;
-  const srcShm = `${CALENDAR_DB}-shm`;
-
+  const files = [tmpDb, `${tmpDb}-wal`, `${tmpDb}-shm`];
+  const cleanup = () => {
+    for (const file of files) {
+      try {
+        fs.unlinkSync(file);
+      } catch {
+        // already gone or never created
+      }
+    }
+  };
   try {
     if (!fs.existsSync(CALENDAR_DB)) {
       throw new Error("Calendar database not found");
     }
     fs.copyFileSync(CALENDAR_DB, tmpDb);
-    if (fs.existsSync(srcWal)) {
-      fs.copyFileSync(srcWal, tmpWal);
+    if (fs.existsSync(`${CALENDAR_DB}-wal`)) {
+      fs.copyFileSync(`${CALENDAR_DB}-wal`, files[1]);
     }
-    if (fs.existsSync(srcShm)) {
-      fs.copyFileSync(srcShm, tmpShm);
+    if (fs.existsSync(`${CALENDAR_DB}-shm`)) {
+      fs.copyFileSync(`${CALENDAR_DB}-shm`, files[2]);
     }
+  } catch (e) {
+    cleanup();
+    throw e;
+  }
+  return { tmpDb, cleanup };
+}
+
+// Index-cycle variant: the sqlite3 reads inside fn are awaited, so the
+// daemon's event loop (and writer.sock) stays free while they run.
+async function withCalendarCopyAsync(fn) {
+  const { tmpDb, cleanup } = copyCalendarDb();
+  try {
+    return await fn(tmpDb);
+  } finally {
+    cleanup();
+  }
+}
+
+function withCalendarCopy(fn) {
+  const { tmpDb, cleanup } = copyCalendarDb();
+  try {
     return fn(tmpDb);
   } finally {
-    for (const file of [tmpDb, tmpWal, tmpShm]) {
-      try {
-        fs.unlinkSync(file);
-      } catch {
-        // already gone or never created
-      }
-    }
+    cleanup();
   }
 }
 

package/lib/httpAuth.js

@@ -8,12 +8,13 @@
  * a bearer token.
  *
  * The token is a random secret generated once and stored in the macOS
- * Keychain — never in a config file, the repo, or logs after the first
- * (one-time, clearly labeled) print. There is no external account, no
+ * Keychain — never in a config file, the repo, argv, or logs.
+ * Print it only with the explicit http-token command. There is no external account, no
  * OAuth flow, and no cost: it's a self-issued password, like an SSH key.
  */
 
 import crypto from "crypto";
+import { writeKeychainSecret } from "./keychainWrite.js";
 import { execFileSync as defaultExecFileSync } from "child_process";
 
 export const KEYCHAIN_SERVICE = "apple-tools-mcp-http";
@@ -34,11 +35,7 @@ function readFromKeychain(exec) {
 }
 
 function writeToKeychain(exec, token) {
-  exec(
-    "/usr/bin/security",
-    ["add-generic-password", "-s", KEYCHAIN_SERVICE, "-a", KEYCHAIN_ACCOUNT, "-w", token, "-U"],
-    { stdio: ["ignore", "ignore", "pipe"] }
-  );
+  writeKeychainSecret(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT, token, exec);
 }
 
 function generateToken(randomBytes) {
@@ -71,13 +68,8 @@ export function loadOrCreateHttpAuthToken(options = {}) {
 
   const token = generateToken(randomBytes);
   writeToKeychain(exec, token);
-  log("============================================================");
-  log("Generated a new HTTP auth token (shown once, stored in Keychain):");
-  log(token);
-  log("Use this as a Bearer token when configuring remote MCP clients,");
-  log("e.g. claude mcp add ... -H \"Authorization: Bearer " + token + "\"");
-  log("Retrieve it again later with: apple-tools-mcp http-token");
-  log("============================================================");
+  log("Generated a new HTTP auth token and stored it in Keychain.");
+  log("Retrieve it with: apple-tools-mcp http-token");
   return { token, generated: true };
 }
 

package/lib/keychainWrite.js

@@ -0,0 +1,17 @@
+import { execFileSync } from "node:child_process";
+
+/** The security utility parses one stdin line; credential bytes never enter process argv. */
+export function writeKeychainSecret(service, account, value, exec = execFileSync) {
+  try {
+    const quote = (text) => {
+      if (!text || /[\r\n\0]/.test(text)) throw new Error("Invalid Keychain field");
+      return '"' + text.replace(/\\/g, "\\\\").replace(/"/g, '\\"') + '"';
+    };
+    const command = "add-generic-password -U -s " + quote(service) + " -a " + quote(account) + " -w " + quote(value) + "\n";
+    // Apple's interactive command buffer is 4096 bytes. Reject before any truncated write.
+    if (Buffer.byteLength(command, "utf8") >= 4095) throw new Error("Keychain field too large");
+    exec("/usr/bin/security", ["-i"], { input: command, stdio: ["pipe", "ignore", "ignore"], timeout: 15000 });
+  } catch {
+    throw new Error("Keychain write failed; credential values omitted.");
+  }
+}

package/lib/mailIdempotency.js

@@ -0,0 +1,70 @@
+import fs from "fs";
+import path from "path";
+import { createHash } from "crypto";
+import { getAppleToolsDir } from "./config.js";
+
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+const uncertain = () => ({
+  ok: false, unconfirmed: true, sendStarted: true,
+  message: "mail_send: unconfirmed. An earlier identical send may still complete. Check Sent and Outbox; do not resend."
+});
+
+/** Cross-process, restart-safe send claims. Only hashes and outcome metadata
+ * are stored. A crash or corrupt record fails closed, including an empty file
+ * left between exclusive creation and its first write. No uncertain claim
+ * expires: a missing Sent row cannot prove a queued send will not run later.
+ */
+export function idempotentMailSend(args, run, {
+  directory = path.join(getAppleToolsDir(), "mail-send-claims"), now = Date.now
+} = {}) {
+  if (args.dry_run === true) return run();
+  const key = args.idempotency_key;
+  if (key !== undefined && (typeof key !== "string" || !key.trim() || key.length > 256)) {
+    return { ok: false, sendStarted: false, message: "mail_send refused: idempotency_key must be a nonempty string of at most 256 characters." };
+  }
+  const addresses = (values) => (Array.isArray(values) ? values.map(v => String(v).trim().toLowerCase()).sort() : values);
+  const fingerprint = digest(JSON.stringify([
+    addresses(args.to), addresses(args.cc || []), addresses(args.bcc || []),
+    args.subject, args.body, args.body_format || "plain"
+  ]));
+  const dir = path.join(directory, digest(key === undefined ? fingerprint : `key:${key}`));
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.chmodSync(directory, 0o700);
+    fs.chmodSync(dir, 0o700);
+    const attempts = fs.readdirSync(dir).filter(n => /^\d+\.json$/.test(n)).map(n => Number(n.slice(0, -5)));
+    const last = attempts.length ? Math.max(...attempts) : 0;
+    if (last) {
+      const previous = JSON.parse(fs.readFileSync(path.join(dir, `${last}.json`), "utf8"));
+      if (previous.fingerprint !== fingerprint) {
+        return { ok: false, sendStarted: false, message: "mail_send refused: idempotency_key was already used with different message content." };
+      }
+      if (previous.state === "done") {
+        if (previous.result?.ok !== true) return uncertain();
+        return { ...previous.result, deduplicated: true };
+      }
+      if (previous.state !== "not_started") return uncertain();
+    }
+    // Atomic exclusive create arbitrates concurrent retries, even in different processes.
+    const file = path.join(dir, `${last + 1}.json`);
+    const fd = fs.openSync(file, "wx", 0o600);
+    const claim = { fingerprint, createdAt: now(), state: "pending" };
+    try {
+      fs.writeFileSync(fd, JSON.stringify(claim));
+      fs.fsyncSync(fd);
+    } finally { fs.closeSync(fd); }
+    let result;
+    try { result = run(); } catch { return uncertain(); }
+    const safe = result?.sendStarted === false || result?.planned === true || /^mail_send refused:/.test(result?.message || "");
+    const state = result?.ok === true ? "done" : safe ? "not_started" : "pending";
+    const cached = result?.ok === true ? {
+      ok: true, delivered: result.delivered === true, mailbox: result.mailbox,
+      message: "mail_send: previous send already accepted; duplicate suppressed."
+    } : undefined;
+    // Torn writes remain blocked on the next call. Never persist message content.
+    fs.writeFileSync(file, JSON.stringify({ ...claim, state, result: cached }), { mode: 0o600 });
+    return result;
+  } catch {
+    return uncertain();
+  }
+}

package/lib/mailWrite.js

@@ -207,7 +207,7 @@ export const MAIL_COMPOSE_TOP_UI_MAX = 48;
 /** Marker inside the JXA hit-test so tests can pin the proven Mini path. */
 export const ATM_AX_HIT_TEST_MARKER = "ATM_AX_HIT_TEST";
 /** Cheap pre-compose System Events check; SIGKILL if it still hangs. Not the permissions grant. */
-export const MAIL_SE_PROBE_TIMEOUT_MS = 4000;
+export const MAIL_SE_PROBE_TIMEOUT_MS = 12000;
 /** First-run / upgrade permissions probe: long enough for the Allow click. */
 export const SYSTEM_EVENTS_AUTOMATION_PROBE_TIMEOUT_MS = 30000;
 /** Compose osascript budget (make + keystroke + send). Far below the ~60s SE wedge. */
@@ -235,7 +235,7 @@ export const MCP_CALL_DEADLINE_MS = 55000;
 export const MAIL_FIND_AND_SEND_TIMEOUT_MS = MAIL_FIND_TIMEOUT_MS;
 export const MAIL_SE_APPLEEVENT_TIMEOUT_SEC = 8;
 export const MAIL_APPLEEVENT_TIMEOUT_SEC = 15;
-export const MAIL_SE_PROBE_APPLEEVENT_TIMEOUT_SEC = 3;
+export const MAIL_SE_PROBE_APPLEEVENT_TIMEOUT_SEC = 10;
 
 /**
  * AppleScript ordinal/keyword tokens that fail compile in `set {a, b}`
@@ -470,7 +470,9 @@ export function probeSystemEventsAutomation() {
   });
   if (!result.ok) {
     const kind = systemEventsGrantKind(result);
-    const guidance = isMailAccessibilityDenial(result)
+    const guidance = result.kind === "timeout"
+      ? "System Events probe timed out; permission status is unknown. Nothing was typed. Retry when the host is responsive."
+      : isMailAccessibilityDenial(result)
       ? MAIL_ACCESSIBILITY_GUIDANCE
       : MAIL_GUI_SCRIPTING_GUIDANCE;
     return {
@@ -1326,7 +1328,6 @@ export function isMailGuiScriptingUnavailable(result) {
   if (!result) return false;
   const text = String(result.error || "").toLowerCase();
   if (text.includes("gui_scripting_unavailable")) return true;
-  if (result.kind === "timeout" && text.includes("system events")) return true;
   return false;
 }
 
@@ -1474,6 +1475,12 @@ function finalizeMailWrite({
 }
 
 function guiScriptingUnavailableResult(action, summary, result, { indexerMode } = {}) {
+  if (result.kind === "timeout") {
+    return {
+      ok: false, delivered: false, mailbox: null, kind: "probe_timeout", sendStarted: false,
+      message: `${action} failed: System Events probe timed out; permission status is unknown. Nothing was composed or sent. Retry when the host is responsive.`
+    };
+  }
   const unsupported = Boolean(indexerMode);
   const message = isMailAccessibilityDenial(result)
     ? `${action} failed — attempted to ${summary}. ${MAIL_ACCESSIBILITY_GUIDANCE}`
@@ -1482,6 +1489,7 @@ function guiScriptingUnavailableResult(action, summary, result, { indexerMode }
     ok: false,
     delivered: false,
     mailbox: null,
+    sendStarted: false,
     ...(unsupported ? { unsupported: true } : {}),
     message
   };
@@ -1530,6 +1538,7 @@ export function mailCompose(args = {}, { draft = false, indexerMode = isIndexerM
   if (!plan.proceed) return plannedWriteResult(plan);
 
   const plainBody = composeNativeBody(body.text, { html: bodyFormat === "html" });
+  const deadlineMs = sentVerifyClock.now() + MCP_CALL_DEADLINE_MS;
   if (plainBody) {
     const se = probeSystemEventsGui();
     if (!se.ok) {
@@ -1547,7 +1556,6 @@ export function mailCompose(args = {}, { draft = false, indexerMode = isIndexerM
     html: bodyFormat === "html"
   });
 
-  const deadlineMs = sentVerifyClock.now() + MCP_CALL_DEADLINE_MS;
   wakeDisplay();
   const result = runAppleScript(script, { timeout: MAIL_COMPOSE_TIMEOUT_MS, appName: "Mail" });
   if (
@@ -1703,6 +1711,7 @@ export function mailReply(args = {}, { indexerMode = isIndexerMode() } = {}) {
   });
   if (!plan.proceed) return plannedWriteResult(plan);
 
+  const deadlineMs = sentVerifyClock.now() + MCP_CALL_DEADLINE_MS;
   if (quoteIntroPasteText(body.text)) {
     const se = probeSystemEventsGui();
     if (!se.ok) {
@@ -1710,11 +1719,10 @@ export function mailReply(args = {}, { indexerMode = isIndexerMode() } = {}) {
     }
   }
 
-  const deadlineMs = sentVerifyClock.now() + MCP_CALL_DEADLINE_MS;
   wakeDisplay();
   const result = runAppleScript(
     buildReplyScript({ messageId: resolved.messageId, body: body.text, replyAll, sendNow }),
-    { timeout: MAIL_FIND_AND_SEND_TIMEOUT_MS, appName: "Mail" }
+    { timeout: Math.min(MAIL_FIND_AND_SEND_TIMEOUT_MS, Math.max(1, deadlineMs - sentVerifyClock.now())), appName: "Mail" }
   );
   return finishMailGuiWrite({
     action,
@@ -1793,6 +1801,7 @@ export function mailForward(args = {}, { indexerMode = isIndexerMode() } = {}) {
   });
   if (!plan.proceed) return plannedWriteResult(plan);
 
+  const deadlineMs = sentVerifyClock.now() + MCP_CALL_DEADLINE_MS;
   if (quoteIntroPasteText(body.text)) {
     const se = probeSystemEventsGui();
     if (!se.ok) {
@@ -1800,11 +1809,10 @@ export function mailForward(args = {}, { indexerMode = isIndexerMode() } = {}) {
     }
   }
 
-  const deadlineMs = sentVerifyClock.now() + MCP_CALL_DEADLINE_MS;
   wakeDisplay();
   const result = runAppleScript(
     buildForwardScript({ messageId: resolved.messageId, to: to.addresses, body: body.text, sendNow }),
-    { timeout: MAIL_FIND_AND_SEND_TIMEOUT_MS, appName: "Mail" }
+    { timeout: Math.min(MAIL_FIND_AND_SEND_TIMEOUT_MS, Math.max(1, deadlineMs - sentVerifyClock.now())), appName: "Mail" }
   );
   return finishMailGuiWrite({
     action,

package/lib/shell.js

@@ -28,14 +28,7 @@ import { escapeSQL } from "./validators.js";
  * @returns {string} Raw output from sqlite3
  * @throws {Error} If execution fails
  */
-export function safeSqlite3(dbPath, query, options = {}) {
-  const {
-    json = true,
-    readonly = false,
-    timeout = 30000,
-    maxBuffer = 50 * 1024 * 1024
-  } = options;
-
+function buildSqlite3Args(dbPath, query, { json = true, readonly = false } = {}) {
   // Validate database path exists and is absolute
   if (!dbPath || typeof dbPath !== 'string') {
     throw new Error('Database path is required');
@@ -59,15 +52,10 @@ export function safeSqlite3(dbPath, query, options = {}) {
   }
   args.push(dbPath);
   args.push(query.replace(/\n/g, ' ')); // Normalize whitespace
+  return args;
+}
 
-  const result = spawnSync('sqlite3', args, {
-    encoding: 'utf-8',
-    timeout,
-    maxBuffer,
-    // Don't use shell - prevents injection
-    shell: false
-  });
-
+function sqlite3Output(result) {
   if (result.error) {
     throw result.error;
   }
@@ -80,6 +68,36 @@ export function safeSqlite3(dbPath, query, options = {}) {
   return result.stdout;
 }
 
+function parseSqlite3Json(output) {
+  if (!output || output.trim() === '') {
+    return [];
+  }
+
+  try {
+    return JSON.parse(output);
+  } catch (e) {
+    throw new Error(`Failed to parse sqlite3 JSON output: ${e.message}`);
+  }
+}
+
+export function safeSqlite3(dbPath, query, options = {}) {
+  const {
+    timeout = 30000,
+    maxBuffer = 50 * 1024 * 1024
+  } = options;
+  const args = buildSqlite3Args(dbPath, query, options);
+
+  const result = spawnSync('sqlite3', args, {
+    encoding: 'utf-8',
+    timeout,
+    maxBuffer,
+    // Don't use shell - prevents injection
+    shell: false
+  });
+
+  return sqlite3Output(result);
+}
+
 /**
  * Execute sqlite3 and parse JSON result
  *
@@ -89,17 +107,23 @@ export function safeSqlite3(dbPath, query, options = {}) {
  * @returns {Array} Parsed JSON array of results
  */
 export function safeSqlite3Json(dbPath, query, options = {}) {
-  const output = safeSqlite3(dbPath, query, { ...options, json: true });
-
-  if (!output || output.trim() === '') {
-    return [];
-  }
+  return parseSqlite3Json(safeSqlite3(dbPath, query, { ...options, json: true }));
+}
 
-  try {
-    return JSON.parse(output);
-  } catch (e) {
-    throw new Error(`Failed to parse sqlite3 JSON output: ${e.message}`);
-  }
+/**
+ * Async safeSqlite3Json for long-lived processes (the indexer daemon):
+ * a slow query under load waits without blocking the event loop, so the
+ * write bridge (writer.sock) keeps answering while an index cycle reads.
+ * Same validation, argv and error semantics as the sync version.
+ */
+export async function safeSqlite3JsonAsync(dbPath, query, options = {}) {
+  const {
+    timeout = 30000,
+    maxBuffer = 50 * 1024 * 1024
+  } = options;
+  const args = buildSqlite3Args(dbPath, query, { ...options, json: true });
+  const result = await spawnCollect('sqlite3', args, { timeout, maxBuffer });
+  return parseSqlite3Json(sqlite3Output(result));
 }
 
 // ============ OSASCRIPT EXECUTION ============
@@ -235,13 +259,12 @@ export function safeMdfind(query, options = {}) {
  * @param {number} options.timeout - Timeout in ms (default: 120000)
  * @returns {string[]} Array of file paths
  */
-export function safeFind(searchPath, options = {}) {
+function buildFindArgs(searchPath, options = {}) {
   const {
     name,
     type,
     mtime,
-    maxdepth,
-    timeout = 120000
+    maxdepth
   } = options;
 
   if (!searchPath || typeof searchPath !== 'string') {
@@ -280,14 +303,10 @@ export function safeFind(searchPath, options = {}) {
     }
     args.push('-mtime', mtime);
   }
+  return args;
+}
 
-  const result = spawnSync('find', args, {
-    encoding: 'utf-8',
-    timeout,
-    maxBuffer: 100 * 1024 * 1024,
-    shell: false
-  });
-
+function findPaths(result) {
   if (result.error) {
     throw result.error;
   }
@@ -308,6 +327,92 @@ export function safeFind(searchPath, options = {}) {
   return paths;
 }
 
+export function safeFind(searchPath, options = {}) {
+  const { timeout = 120000 } = options;
+  const args = buildFindArgs(searchPath, options);
+  const result = spawnSync('find', args, {
+    encoding: 'utf-8',
+    timeout,
+    maxBuffer: 100 * 1024 * 1024,
+    shell: false
+  });
+  return findPaths(result);
+}
+
+/**
+ * Async safeFind for the indexer daemon: a 2-minute find under heavy load
+ * no longer freezes the daemon's event loop (and with it writer.sock).
+ */
+export async function safeFindAsync(searchPath, options = {}) {
+  const { timeout = 120000 } = options;
+  const args = buildFindArgs(searchPath, options);
+  const result = await spawnCollect('find', args, { timeout, maxBuffer: 100 * 1024 * 1024 });
+  return findPaths(result);
+}
+
+/**
+ * spawn() with spawnSync-shaped results: { stdout, stderr, status, error }.
+ * Never a shell. On timeout the child is SIGKILLed and `error` is an
+ * ETIMEDOUT Error like spawnSync's; output past maxBuffer kills the child
+ * with ENOBUFS. Resolves (never rejects) so callers keep sync semantics.
+ */
+export function spawnCollect(command, args, { timeout = 30000, maxBuffer = 10 * 1024 * 1024, spawnImpl = spawn } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawnImpl(command, args, { shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) {
+      resolve({ stdout: '', stderr: '', status: null, error: e });
+      return;
+    }
+    const out = [];
+    const err = [];
+    let size = 0;
+    let error = null;
+    let settled = false;
+    const kill = (e) => {
+      if (!error) error = e;
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        // already exited
+      }
+    };
+    const timer = timeout > 0
+      ? setTimeout(() => {
+        const e = new Error(`spawn ${command} ETIMEDOUT`);
+        e.code = 'ETIMEDOUT';
+        kill(e);
+      }, timeout)
+      : null;
+    const collect = (chunks) => (chunk) => {
+      size += chunk.length;
+      if (size > maxBuffer) {
+        const e = new Error(`spawn ${command} ENOBUFS`);
+        e.code = 'ENOBUFS';
+        kill(e);
+        return;
+      }
+      chunks.push(chunk);
+    };
+    child.stdout.on('data', collect(out));
+    child.stderr.on('data', collect(err));
+    const finish = (status, spawnError) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve({
+        stdout: Buffer.concat(out).toString('utf-8'),
+        stderr: Buffer.concat(err).toString('utf-8'),
+        status,
+        error: error || spawnError || null
+      });
+    };
+    child.on('error', (e) => finish(null, e));
+    child.on('close', (code) => finish(code, null));
+  });
+}
+
 // ============ GENERIC SAFE SPAWN ============
 
 /**

package/lib/writeBridge.js

@@ -65,7 +65,11 @@ export function startWriteBridgeServer({ socketPath, handler, log = () => {} })
         let response;
         try {
           const request = JSON.parse(buffer.slice(0, newline));
-          response = await handler(request.tool, request.args || {});
+          if (Number.isFinite(request.expiresAt) && Date.now() >= request.expiresAt) {
+            response = { ok: false, sendStarted: false, message: "Write bridge request expired before execution; nothing was started." };
+          } else {
+            response = await handler(request.tool, request.args || {});
+          }
         } catch (e) {
           response = { ok: false, message: `Write bridge error: ${e.message}` };
         }
@@ -157,13 +161,15 @@ export function probeSocket(socketPath, timeoutMs = 1000) {
  * @returns {Promise<{ delivered: boolean, response: object|null, error: string|null }>}
  */
 export function requestWriteViaBridge({ socketPath, tool, args, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS }) {
+  const expiresAt = Date.now() + timeoutMs;
   return new Promise((resolve) => {
     if (!socketPath) {
-      resolve({ delivered: false, response: null, error: "no socket path" });
+      resolve({ delivered: false, response: null, error: "no socket path", mayHaveStarted: false });
       return;
     }
 
     let settled = false;
+    let mayHaveStarted = false;
     let buffer = "";
     const finish = (value) => {
       if (settled) return;
@@ -173,7 +179,7 @@ export function requestWriteViaBridge({ socketPath, tool, args, timeoutMs = DEFA
       } catch {
         // ignore
       }
-      resolve(value);
+      resolve({ ...value, mayHaveStarted });
     };
 
     const client = net.connect(socketPath);
@@ -181,7 +187,8 @@ export function requestWriteViaBridge({ socketPath, tool, args, timeoutMs = DEFA
     client.setTimeout(timeoutMs);
 
     client.on("connect", () => {
-      client.write(JSON.stringify({ tool, args: args || {} }) + "\n");
+      mayHaveStarted = true;
+      client.write(JSON.stringify({ tool, args: args || {}, expiresAt }) + "\n");
     });
 
     client.on("data", (chunk) => {

package/lib/writeTools.js

@@ -33,6 +33,7 @@ import { contactsAdd, contactsEdit, contactsRemove } from "./contactsWrite.js";
 import { planWriteRoute, planAfterDelegation, tccFallbackAdvice } from "./writeRouting.js";
 import { requestWriteViaBridge, probeSocket, defaultSocketPath } from "./writeBridge.js";
 import { needsHostTccAdvice } from "./appleScript.js";
+import { idempotentMailSend } from "./mailIdempotency.js";
 
 const CONFIRM_PROPS = {
   dry_run: { type: "boolean", description: "Preview only: report what would happen and change nothing (default false)" },
@@ -57,6 +58,7 @@ export const WRITE_TOOL_DEFINITIONS = [
         bcc: { type: "array", items: { type: "string" }, description: "BCC email addresses" },
         subject: { type: "string", description: "Subject line (required)" },
         body: { type: "string", description: "Message body (required)" },
+        idempotency_key: { type: "string", description: "Stable unique delivery key. Reuse for retries of the same message; a new key represents a new intended delivery. Without a key identical accepted mail is suppressed without expiry; uncertain sends stay blocked." },
         body_format: { type: "string", enum: ["plain", "html"], description: "Plain text (default) or HTML. HTML is tag-stripped; the body is pasted into Mail's compose window (System Events focus on the message body, then Cmd-A and clipboard paste). AppleScript content/html content is not set because it quote-wraps the Sent body" },
         ...CONFIRM_PROPS
       },
@@ -371,7 +373,9 @@ export function executeWriteToolLocally(name, args = {}) {
     return { ok: false, message: `Unknown write tool: ${name}`, unsupported: true };
   }
   try {
-    return handler(args || {});
+    return name === "mail_send"
+      ? idempotentMailSend(args || {}, () => handler(args || {}))
+      : handler(args || {});
   } catch (e) {
     return { ok: false, message: `${name} failed: ${e.message}` };
   }
@@ -379,7 +383,8 @@ export function executeWriteToolLocally(name, args = {}) {
 
 /**
  * Run a write, delegating privacy-gated work to the indexer daemon when it is
- * listening. Falls back to local execution whenever the bridge is unusable.
+ * listening. Sending tools fall back only when the handoff provably did not
+ * start a write; an ambiguous outcome retains daemon ownership.
  *
  * @param {string} name
  * @param {object} args
@@ -392,6 +397,7 @@ export function executeWriteToolLocally(name, args = {}) {
  */
 export function classifyWriteFailure(message) {
   const t = String(message || "");
+  if (/System Events probe timed out/i.test(t)) return "probe_timeout";
   if (/GUI scripting is unavailable/i.test(t)) return "gui_scripting_unavailable";
   if (/denied Accessibility|assistive access|-25211/i.test(t)) return "accessibility_denied";
   if (/display is asleep|screen saver/i.test(t)) return "display_asleep_or_screen_saver";
@@ -452,7 +458,17 @@ export async function dispatchWriteTool(name, args = {}, deps = {}) {
 
   let declined = null;
   if (route.target === "daemon") {
-    const { delivered, response, error } = await request({ socketPath, tool: name, args });
+    const { delivered, response, error, mayHaveStarted } = await request({ socketPath, tool: name, args });
+    // A lost response is not evidence of a failed send. Preserve the daemon's
+    // ownership after any handoff that could have reached it.
+    if ((name === "mail_send" || name === "mail_reply" || name === "mail_forward" || name === "messages_send") &&
+        ((!delivered && mayHaveStarted !== false) ||
+         (delivered && (!response || typeof response !== "object" ||
+           (response.unsupported && response.sendStarted !== false))))) {
+      log(`Write bridge outcome unknown for ${name}; local fallback suppressed.`);
+      return { ok: false, unconfirmed: true, sendStarted: true,
+        message: `${name}: unconfirmed. The daemon may still complete the write. Check Sent/Outbox or the destination before retrying; no local resend was started.` };
+    }
     const { fallbackLocal } = planAfterDelegation({ delivered, response });
     if (!fallbackLocal) {
       return response;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-tools-mcp",
-  "version": "3.2.1",
+  "version": "3.2.3",
   "description": "MCP server for semantic search and write actions across Apple Mail, Messages, Calendar, and Contacts. Speaks stdio (local) or bearer-token-authenticated Streamable HTTP (LAN / Tailscale).",
   "type": "module",
   "main": "index.js",