apple-tools-mcp 2.0.0 → 2.0.1

package/README.md

@@ -73,11 +73,13 @@ Full Disk Access covers the **read** tools. Write tools need the automation perm
 
 Write tools drive Mail, Messages, Calendar, and Contacts through AppleScript. macOS gates those Apple events behind **Automation**, not by adding `node` to the Contacts or Calendars privacy lists.
 
+**One-pass first-run:** Allow **`node`** to control **Mail**, **Messages**, **Contacts**, and **Calendar** in the same Automation pass. Contacts or Calendar being allowed does **not** grant Mail or Messages — they are separate Apple Events targets. A denied Mail grant hangs `mail_send` / `mail_draft` / `mail_reply` / `mail_forward` until the client disconnects; `dry_run` never talks to Mail, so that deny is invisible until a real compose.
+
 **Do not add `node` via the + button in System Settings → Privacy & Security → Contacts or Calendars.** On current macOS those panes often have **no Add button**, and that instruction is not the ship-gate setup — it failed on the Mini.
 
 #### Mini ship-gate host setup
 
-This is the first-run flow for Contacts and Calendar **writes** on the Mac Mini. Do it on the Mini UI (or Screen Sharing to Mini), with the indexer LaunchAgent owning `node`:
+This is the first-run flow for Mail, Messages, Contacts, and Calendar **writes** on the Mac Mini. Do it on the Mini UI (or Screen Sharing to Mini), with the indexer LaunchAgent owning `node`:
 
 1. Open **System Settings → Privacy & Security → Automation**.
 2. Run write prove-out with the **indexer LaunchAgent** owning `node` (`~/.apple-tools-mcp/writer.sock` / launchd). Against the tip, with the LaunchAgent up:
@@ -87,11 +89,17 @@ This is the first-run flow for Contacts and Calendar **writes** on the Mac Mini.
    ```
 
    That is the ship-gate context. An embedded agent shell, IDE terminal, or MCP host app subprocess is **not** the ship-gate host unless the write bridge is up and the work executes inside launchd-owned `node`.
-3. When prompts appear, click **Allow** for **`node`** to control **Contacts** and **Calendar**. Use whatever path the LaunchAgent plist / `which node` reports — `/Users/petercoates/.local/node/bin/node` is a Mini *example* only, not a universal path. Do **not** approve the MCP client / host app that launched a short-lived stdio server.
-4. **Full Disk Access** on `node` is a separate grant and covers **reads** (Mail / Messages / Calendar / AddressBook databases). Contacts and Calendar **writes** need the Automation / Apple Events grants to Contacts.app and Calendar.app.
+3. When prompts appear, click **Allow** for **`node`** to control **Mail**, **Messages**, **Contacts**, and **Calendar**. Watch the host — Allow **`node`** (the LaunchAgent binary), not any other app. Use whatever path the LaunchAgent plist / `which node` reports — `/Users/petercoates/.local/node/bin/node` is a Mini *example* only, not a universal path. Do **not** approve the MCP client / host app that launched a short-lived stdio server.
+4. **Full Disk Access** on `node` is a separate grant and covers **reads** (Mail / Messages / Calendar / AddressBook databases). Write tools need the Automation / Apple Events grants to Mail.app (`mail_send`, `mail_draft`, `mail_reply`, `mail_forward`, and the other mail writes), Messages.app (`messages_send`), Contacts.app, and Calendar.app.
 5. npm Trusted Publisher / publish tokens are unrelated to TCC. Do not confuse them with this setup.
 
-If you dismissed a prompt, re-open **Automation** and turn the **node → Contacts** / **node → Calendar** toggles back on. `tccutil reset AppleEvents` re-arms the Automation prompt so you can Allow **`node`** again. Do not use `tccutil reset AddressBook` / `tccutil reset Calendar`, and do not add `node` via Settings **+** into the Contacts or Calendars privacy lists — those panes often have no Add button, and that is not how this ship gate is granted.
+If you dismissed a prompt, re-open **Automation** and turn the **node → Mail** / **node → Messages** / **node → Contacts** / **node → Calendar** toggles back on. `tccutil reset AppleEvents` re-arms the Automation prompt so you can Allow **`node`** again. Do not use `tccutil reset AddressBook` / `tccutil reset Calendar`, and do not add `node` via Settings **+** into the Contacts or Calendars privacy lists — those panes often have no Add button, and that is not how this ship gate is granted.
+
+#### `dry_run` does not prove Mail Automation
+
+`mail_send` / `mail_draft` / `mail_reply` / `mail_forward` with `dry_run=true` return immediately and never send Apple events to Mail — dry_run never talks to Mail. A TCC deny for **node → Mail** is therefore invisible until a real compose (`make new outgoing message`). The hang is **Automation denied**, not “Mail.app could not be reached” / “app not available”.
+
+`tell application "Mail" to get name` can succeed while compose still hangs. The smoke test’s Mail step runs that real compose (then discards the outgoing message, or on an older daemon saves a clearly named Draft) so the deny fails **setup**, not a later production `mail_send`. The same Allow-via-prompt applies to **Messages** for `messages_send`; `messages_send` with `dry_run=true` likewise never talks to Messages.app. Smoke also live-enumerates Messages accounts (nothing is sent). **`--apply` fails closed if Mail, Messages, Contacts, or Calendar Automation is missing.**
 
 #### Which process macOS is actually asking about
 
@@ -140,7 +148,7 @@ So the supported configuration for writes is: **run the indexer daemon** ([Launc
 
 If a write is denied and no daemon is listening, the tool says so and tells you to start `apple-tools-indexer`, rather than failing with a bare AppleScript error. Contacts and Calendar denials each name their own privacy class and note that reads are unaffected.
 
-#### Verifying Contacts and Calendar CRUD on a Node host
+#### Verifying Mail Automation plus Contacts and Calendar CRUD on a Node host
 
 The smoke test drives writes through **the same dispatcher the MCP tools use**, so when the write bridge is up the work executes inside the indexer daemon. That matters: the thing being proven is the shipping path, not the Automation rights of whatever shell you happened to type the command into.
 
@@ -155,7 +163,7 @@ The smoke test drives writes through **the same dispatcher the MCP tools use**,
 
 2. **Check out the tip / unpack the tarball** you are gating, in a short-lived directory. The global install stays untouched.
 
-3. **Dry run first.** It creates, edits, and deletes nothing — but it is not a no-op: it reads your contacts from the AddressBook database and calls `calendar_list_calendars`, which is a **live Calendar.app query and therefore a real TCC touch** that can raise an Automation prompt or be denied. Because the run changes nothing, a refused listing is reported as `WARN` rather than failing the run.
+3. **Dry run first.** It creates, edits, and deletes nothing on Contacts/Calendar — but it is not a no-op: it reads your contacts from the AddressBook database, calls `calendar_list_calendars` (a **live Calendar.app query and therefore a real TCC touch**), runs a **live Mail compose** (`make new outgoing message`) because `mail_send` `dry_run` never touches Mail, and live-enumerates **Messages** accounts because `messages_send` `dry_run` never touches Messages. A refused Calendar listing, Mail compose, or Messages lookup is `WARN` on a dry run. `--apply` fails closed if **Mail, Messages, Contacts, or Calendar** Automation is still denied.
 
    ```bash
    npm run smoke:writes
@@ -169,7 +177,7 @@ The smoke test drives writes through **the same dispatcher the MCP tools use**,
    node scripts/smoke-writes.js --apply --keep           # leave the test items behind
    ```
 
-The header prints the write path it chose (`indexer daemon via write bridge` or `in this process`), and the read path (sqlite + FDA) is reported separately from the two write paths (Contacts.app, Calendar.app), so a failure tells you which mechanism refused.
+The header prints the write path it chose (`indexer daemon via write bridge` or `in this process`), and the read path (sqlite + FDA) is reported separately from the write paths (Mail.app compose, Contacts.app, Calendar.app), so a failure tells you which mechanism refused. A Mail hang or timeout is **TCC / Automation denied**, not “app not available”.
 
 **The parent process matters.** With `--apply` and **no bridge listening**, the smoke test **refuses to run** rather than executing in-process and calling the result a package failure. Running it from an embedded agent shell, an IDE terminal, or a host app's subprocess is *not* the ship-gate context on its own, because macOS attributes the Apple events to that parent. Either start the LaunchAgent (preferred, and what production clients use), or run it from **Terminal.app**, where node is the responsible process, and pass `--allow-local` to acknowledge that:
 
@@ -177,7 +185,7 @@ The header prints the write path it chose (`indexer daemon via write bridge` or
 node scripts/smoke-writes.js --apply --allow-local   # only from Terminal.app / launchd
 ```
 
-Expected results: **PASS on the Node host with the bridge up — this is the ship gate for Contacts and Calendar writes.** On Claude Desktop with no daemon running, Contacts and Calendar CRUD are both expected to fail; that is the documented host limitation above, not a regression.
+Expected results: **PASS on the Node host with the bridge up — this is the ship gate for Mail, Messages, Contacts, and Calendar writes.** `--apply` fails closed if any of those four Automation grants is missing. On Claude Desktop with no daemon running, Contacts and Calendar CRUD are both expected to fail; that is the documented host limitation above, not a regression. Mail and Messages still need their own **node → Mail** / **node → Messages** grants; a Contacts/Calendar grant does not cover them.
 
 ### 3. Configure your MCP client
 
@@ -266,7 +274,7 @@ Missing `config.json` is fine — env then the 5-minute default apply.
 
 On Mini, run the **indexer daemon**, not a sleep-pipe wrapper around `apple-tools-mcp`. Claude Desktop and other clients still attach via short-lived stdio MCP (`npx -y apple-tools-mcp` or the global `apple-tools-mcp` bin).
 
-The daemon does two jobs: it refreshes the vector index, and it serves the **write bridge** at `~/.apple-tools-mcp/writer.sock` so stdio clients can perform Contacts/Calendar writes that their host app cannot be granted (see [step 2b](#2b-grant-automation-for-write-tools-first-run--ship-gate)). When macOS prompts, Allow **`node`** (the LaunchAgent binary) to control Contacts.app and Calendar.app. Do not approve the MCP client / host app that launched a short-lived stdio server, and do not try to add `node` via **+** in the Contacts or Calendars privacy lists.
+The daemon does two jobs: it refreshes the vector index, and it serves the **write bridge** at `~/.apple-tools-mcp/writer.sock` so stdio clients can perform Mail / Messages / Contacts / Calendar writes that their host app cannot be granted (see [step 2b](#2b-grant-automation-for-write-tools-first-run--ship-gate)). When macOS prompts, Allow **`node`** (the LaunchAgent binary) to control Mail.app, Messages.app, Contacts.app, and Calendar.app. Do not approve the MCP client / host app that launched a short-lived stdio server, and do not try to add `node` via **+** in the Contacts or Calendars privacy lists.
 
 The bridge is created before the daemon touches the vector index, so writes stay available even when the index is missing, locked, or mid-rebuild. Confirm it after an upgrade with `ls -l ~/.apple-tools-mcp/writer.sock` (it should be a `srw-------` socket); the daemon removes it on shutdown.
 
@@ -438,12 +446,20 @@ Supported identifiers:
 |------|-----------|--------------|
 | `calendar_list_calendars` | none | none (read-only helper) |
 | `calendar_add` | `calendar_name` (required), `title` (required), `start` (required), `end`, `all_day`, `location`, `notes`, recurrence args, `alerts_minutes_before[]` | none |
-| `calendar_edit` | `event_id` (required) plus any of `title`, `start`, `end`, `location`, `notes`, recurrence args, `alerts_minutes_before[]`, `replace_alerts` | none |
-| `calendar_remove` | `event_id` (required) | **`confirm` required** |
+| `calendar_edit` | `event_id` (required), optional `eventkit_id` from add, plus any of `title`, `start`, `end`, `location`, `notes`, recurrence args, `alerts_minutes_before[]`, `replace_alerts` | none |
+| `calendar_remove` | `event_id` (required), optional `eventkit_id` from add, optional `calendar_name` | **`confirm` required** |
 | `calendar_rsvp` | `event_id` (required), `response` (`accept` \| `decline` \| `tentative`), `attendee_email` | none |
 
 Events are addressed by their **iCalendar UID**, reported as `Event ID` by `calendar_date` and returned by `calendar_add`. Run `calendar_list_calendars` first so new events land on the intended calendar instead of the default one.
 
+`calendar_add`, `calendar_edit`, and `calendar_remove` share the same write-bridge RPC (`{ tool, args }` into launchd-owned node). They do not use a different socket or calendar account. Calendar.app’s dictionary has **`delete` only** — there is no `remove` or `move to trash`.
+
+Non-recurring `calendar_add` **must** create through **EventKit** and print `via: EventKit` plus `eventkit_id`. Mini `cd74071`: EventKit had `eventKitCalendars=1` but `default=[id NSTaggedPointerString]` — JXA `String(title)` prints the ObjC class, not the calendar name, so the title match missed the only writable calendar. Titles and `calendarIdentifier` are `ObjC.unwrap`d; a single writable calendar or `defaultCalendarForNewEvents` is used when the name does not match. There is **no AppleScript fallback** for non-recurring add.
+
+`calendar_edit` and `calendar_remove` take `eventkit_id` from add (`calendarUUID:eventUUID` on Mini). writeOnly EventKit (`status=4`) can create and read ids off the saved `EKEvent`, but **cannot re-query** via `eventWithIdentifier` — Mini `2cdf44d` failed add on that post-save lookup. Add therefore returns ids from the in-memory event. The indexer write-bridge keeps a long-lived EventKit osascript session that caches the `EKEvent` so edit/remove call `saveEvent` / `removeEvent` without a fetch. When `eventkit_id` is present and the session misses, Calendar.app uid lookup is skipped so iCloud cannot hang. `ETIMEDOUT` / `-1712` is **`timeout`**, never TCC. Failures print `osascript kind=… error=… codes=…`. `--apply` fails closed unless add printed `via: EventKit` and `eventkit_id`.
+
+`--apply` prefers an **On My Mac** calendar when EventKit lists one. `--calendar=` still wins. The Mini host’s first writable calendar named **Calendar** (no On My Mac / iCloud label) is fine if EventKit create actually runs.
+
 Like Contacts, calendar writes go through Calendar.app rather than writing `Calendar.sqlitedb` directly. Reads query that database for speed, but edits must go through the app so iCloud sync, invitations, and alarms behave correctly.
 
 **Supported recurrence patterns.** Either pass structured arguments or a raw `recurrence` RRULE:
@@ -526,12 +542,13 @@ Ensure Node.js has Full Disk Access (see Installation step 2).
 
 The message names which process macOS was actually asking about. Work through it in this order:
 
-1. **Is the indexer daemon running?** `pgrep -fl apple-tools-indexer`. If not, start it — the daemon is the supported host for Contacts and Calendar writes (see [step 2b](#2b-grant-automation-for-write-tools-first-run--ship-gate)).
-2. **Did you approve the Automation prompts for `node`?** Open System Settings → Privacy & Security → **Automation** and confirm **node** (the LaunchAgent binary — whatever path the plist / `which node` reports; `/Users/petercoates/.local/node/bin/node` is a Mini *example* only) is allowed to control Contacts and Calendar. Do **not** approve the MCP client / host app that launched a short-lived stdio server, and do **not** try to add `node` via **+** in the Contacts or Calendars privacy lists — those panes often have no Add button. `tccutil reset AppleEvents` re-arms the Automation prompt so you can Allow **`node`** again. Full Disk Access is a separate read grant; npm Trusted Publisher / tokens are unrelated.
+1. **Is the indexer daemon running?** `pgrep -fl apple-tools-indexer`. If not, start it — the daemon is the supported host for Mail, Messages, Contacts, and Calendar writes (see [step 2b](#2b-grant-automation-for-write-tools-first-run--ship-gate)).
+2. **Did you approve the Automation prompts for `node`?** Open System Settings → Privacy & Security → **Automation** and confirm **node** (the LaunchAgent binary — whatever path the plist / `which node` reports; `/Users/petercoates/.local/node/bin/node` is a Mini *example* only) is allowed to control **Mail**, **Messages**, Contacts, and Calendar. Watch the host — Allow **`node`**, not any other app. Contacts or Calendar being allowed does **not** grant Mail. A `mail_send` hang is **Automation denied**, not “Mail.app could not be reached”; `dry_run` never talks to Mail so it cannot detect this. Do **not** approve the MCP client / host app that launched a short-lived stdio server, and do **not** try to add `node` via **+** in the Contacts or Calendars privacy lists — those panes often have no Add button. `tccutil reset AppleEvents` re-arms the Automation prompt so you can Allow **`node`** again. Full Disk Access is a separate read grant; npm Trusted Publisher / tokens are unrelated.
 3. **Is the daemon's node binary the one with Full Disk Access?** LaunchAgents do not inherit your shell `PATH`; confirm the plist points at the same path `which node` reports.
 4. **Is it actually the write path?** Contacts or Calendar *reads* failing with `EPERM` is a Full Disk Access / attribution problem, not the entitlement gap — fix FDA for the responsible process. Contacts or Calendar *CRUD* failing with no prompt under Claude Desktop is the [documented host limitation](#reads-and-writes-are-different-mechanisms): Claude.app carries neither the addressbook nor the calendars entitlement. Start the daemon and the write succeeds through the bridge.
 5. **"Contacts.app / Calendar.app could not be reached"** with the app clearly installed is an **Automation / responsible-process** failure, not a missing app — macOS reports a refused Apple event as `-1728` / "can't get application". The tool says so and points at the bridge. Start the LaunchAgent, or run from Terminal.app and approve the Automation prompt.
-6. **Prove the host itself works** with `node scripts/smoke-writes.js --apply` on the Node host with the LaunchAgent running; it routes through the bridge and separates the read and write mechanisms for you.
+6. **`calendar_remove` FAIL after add/edit PASS** is a delete-path failure, not missing Calendar Automation. Same write-bridge RPC. Read the `osascript kind=/error=` line: `kind=timeout` + `ETIMEDOUT` / `-1712` is an iCloud/CalDAV hang or Calendar confirmation dialog — **not** TCC. `EVENTKIT_NOT_FOUND status=4` is writeOnly EventKit failing to see an AppleScript-created event (add must go through EventKit). `-1743` / `-10004` is a real Automation deny. Paste that line if it still FAILs.
+7. **Prove the host itself works** with `node scripts/smoke-writes.js --apply` on the Node host with the LaunchAgent running; it routes through the bridge and separates the read and write mechanisms for you.
 
 ### A write returned "CONFIRMATION REQUIRED"
 

package/index.js

@@ -29,6 +29,8 @@ import {
   executeWriteToolLocally
 } from "./lib/writeTools.js";
 import { startWriteBridgeServer, defaultSocketPath } from "./lib/writeBridge.js";
+import { closeEventKitSession, ensureEventKitSession } from "./lib/eventKitSession.js";
+import { EVENTKIT_JXA_HELPERS } from "./lib/calendarWrite.js";
 
 const PACKAGE_VERSION = JSON.parse(
   fs.readFileSync(new URL("./package.json", import.meta.url), "utf8")
@@ -83,6 +85,7 @@ const WRITE_SOCKET_PATH = defaultSocketPath();
 let writeBridge = null;
 
 function stopWriteBridge() {
+  closeEventKitSession();
   if (!writeBridge) return;
   try {
     writeBridge.close();
@@ -99,6 +102,7 @@ async function startWriteBridge() {
       handler: (tool, args) => executeWriteToolLocally(tool, args),
       log: (msg) => console.error(msg)
     });
+    ensureEventKitSession({ helpers: EVENTKIT_JXA_HELPERS });
   } catch (e) {
     console.error(`Write bridge unavailable: ${e.message}. Writes will run in each MCP process.`);
   }

package/lib/appleScript.js

@@ -24,6 +24,7 @@ export const DEFAULT_SCRIPT_TIMEOUT_MS = 30000;
 export const NOT_FOUND_SENTINELS = [
   "MESSAGE_NOT_FOUND",
   "EVENT_NOT_FOUND",
+  "EVENTKIT_NOT_FOUND",
   "CONTACT_NOT_FOUND",
   "CALENDAR_NOT_FOUND",
   "CHAT_NOT_FOUND",
@@ -69,11 +70,27 @@ const APP_MISSING_SIGNATURES = [
 
 // osascript itself is missing: not macOS, or a stripped PATH. Never an
 // attribution problem, because nothing ran.
+//
+// Do **not** match a bare "spawnSync osascript" here. A TCC-denied Mail
+// compose hangs until spawnSync times out (`spawnSync osascript ETIMEDOUT`);
+// that string also contains "spawnSync osascript" and must not be reported
+// as "Mail.app could not be reached".
 const OSASCRIPT_MISSING_SIGNATURES = [
-  "spawnsync osascript",
+  "spawnsync osascript enoent",
   "enoent"
 ];
 
+// Hung Apple events. Mini diagnosis: `tell Mail to get name` returns, but
+// `make new outgoing message` blocks until timeout when node → Mail
+// Automation is denied. That hang is a TCC deny, not a missing app.
+const TIMEOUT_SIGNATURES = [
+  "etimedout",
+  "timed out after",
+  "-1712",
+  "appleevent timed out",
+  "apple event timed out"
+];
+
 /**
  * Standard install locations for the apps this package automates.
  * Ventura and later keep the first-party apps in /System/Applications.
@@ -98,7 +115,7 @@ export function appBundleInstalled(appName, existsFn = fs.existsSync) {
  * @param {string} message
  * @param {object} [context]
  * @param {boolean|null} [context.appInstalled] - whether the target app exists
- * @returns {"tcc"|"not_found"|"attribution"|"app_unavailable"|"unknown"}
+ * @returns {"tcc"|"timeout"|"not_found"|"attribution"|"app_unavailable"|"unknown"}
  */
 export function classifyAppleScriptError(message, context = {}) {
   const text = String(message || "").toLowerCase();
@@ -106,7 +123,21 @@ export function classifyAppleScriptError(message, context = {}) {
     if (text.includes(sentinel.toLowerCase())) return "not_found";
   }
   if (OSASCRIPT_MISSING_SIGNATURES.some((sig) => text.includes(sig))) return "app_unavailable";
+  // ETIMEDOUT / -1712 is a hang, not a TCC deny. Mail/Messages still map
+  // this kind to Automation guidance (compose hang = grant missing).
+  // calendar_remove must never print Calendar-denied copy for ETIMEDOUT alone.
+  if (TIMEOUT_SIGNATURES.some((sig) => text.includes(sig))) return "timeout";
   if (TCC_SIGNATURES.some((sig) => text.includes(sig))) return "tcc";
+  // Calendar delete of a detached event specifier often returns
+  // "Can't get event … (-1728)". That is a missing object, not a missing app.
+  // Check before the generic -1728 / "can't get application" path.
+  if (
+    text.includes("can't get event") ||
+    text.includes("can't get calendar") ||
+    text.includes("can't get theevent")
+  ) {
+    return "not_found";
+  }
   if (APP_MISSING_SIGNATURES.some((sig) => text.includes(sig))) {
     // The app is on disk, so "can't get application" means macOS refused to
     // let the responsible process drive it - an Automation / attribution
@@ -120,6 +151,75 @@ export function isTccDenial(message) {
   return classifyAppleScriptError(message) === "tcc";
 }
 
+/**
+ * Real Automation / privacy deny codes — not a hung Calendar.app delete.
+ *
+ * Mini calendar_remove: add/edit succeed (Automation granted), then delete
+ * hits spawnSync ETIMEDOUT / AppleEvent -1712. That is an iCloud/CalDAV
+ * hang or a confirmation dialog, not -1743 / -10004. Callers must not
+ * rewrite that as CALENDAR_TCC_GUIDANCE.
+ */
+const HARD_TCC_SIGNATURES = [
+  "-1743",
+  "-10004",
+  "-25211",
+  "not authorized to send apple events",
+  "not allowed to send apple events",
+  "is not allowed assistive access",
+  "operation not permitted",
+  "not permitted to access",
+  "access to contacts",
+  "access to calendars",
+  "privacy settings",
+  "errae eventnotpermitted",
+  "errAEEventNotPermitted".toLowerCase()
+];
+
+export function isHardTccDenial(message) {
+  const text = String(message || "").toLowerCase();
+  return HARD_TCC_SIGNATURES.some((sig) => text.includes(sig));
+}
+
+const APPLEEVENT_CODES = [
+  "-1743",
+  "-10004",
+  "-25211",
+  "-1712",
+  "-1728",
+  "-600",
+  "-10810",
+  "-1708",
+  "-1719",
+  "-10025",
+  "-2700"
+];
+
+/**
+ * Pull known AppleEvent / spawn codes out of osascript stderr so smoke
+ * can print them instead of guessing TCC.
+ */
+export function extractAppleEventCodes(message) {
+  const text = String(message || "");
+  const found = [];
+  for (const code of APPLEEVENT_CODES) {
+    if (text.includes(code) && !found.includes(code)) found.push(code);
+  }
+  if (/etimedout/i.test(text) && !found.includes("ETIMEDOUT")) found.push("ETIMEDOUT");
+  return found;
+}
+
+/**
+ * One-line osascript diagnostic. Always include this on calendar_remove
+ * failure so Mini --apply stops looking like a TCC deny.
+ */
+export function formatOsascriptDiagnostic(result, source = "osascript") {
+  const raw = String(result && result.error ? result.error : "").replace(/\s+/g, " ").trim();
+  const clipped = raw.length > 360 ? `${raw.slice(0, 360)}...` : raw;
+  const kind = (result && result.kind) || "unknown";
+  const codes = extractAppleEventCodes(raw);
+  return `${source} kind=${kind} error=${clipped || "(empty)"}${codes.length ? ` codes=${codes.join(",")}` : ""}`;
+}
+
 /**
  * Guidance attached to TCC denials. Names the host constraint without
  * claiming the package can grant another app's entitlements.
@@ -168,11 +268,35 @@ export const ATTRIBUTION_GUIDANCE =
   "under launchd-owned node, or run this server from a parent that can hold Automation access (Terminal.app) and approve the prompt.";
 
 /**
- * @param {"contacts"|"calendar"|string} source
+ * Mail writes are gated by Automation → Mail for the responsible process.
+ * A hang or timeout on compose/send is that deny — not "Mail.app missing".
+ * dry_run never sends Apple events to Mail, so it cannot detect the grant.
+ */
+export const MAIL_TCC_GUIDANCE =
+  "macOS denied Mail automation (Apple Events to Mail.app). A hang or timeout on compose or send is a TCC / Automation deny for node → Mail, " +
+  "not Mail.app missing or unavailable. dry_run never talks to Mail, so it cannot detect this grant. " +
+  "Allow node in System Settings → Privacy & Security → Automation for Mail (same Allow-via-prompt as Contacts and Calendar — do not add node via + in a privacy list). " +
+  "A Contacts or Calendar grant does not include Mail. " +
+  "Run the indexer daemon (apple-tools-indexer / the LaunchAgent) so Mail writes execute under node.";
+
+/**
+ * Messages writes are a separate Automation target from Mail / Contacts / Calendar.
+ */
+export const MESSAGES_TCC_GUIDANCE =
+  "macOS denied Messages automation (Apple Events to Messages.app). A hang or timeout on send is a TCC / Automation deny for node → Messages, " +
+  "not Messages.app missing or unavailable. dry_run never talks to Messages, so it cannot detect this grant. " +
+  "Allow node in System Settings → Privacy & Security → Automation for Messages (same Allow-via-prompt as Mail, Contacts, and Calendar — do not add node via + in a privacy list). " +
+  "A Contacts or Calendar grant does not include Messages. " +
+  "Run the indexer daemon (apple-tools-indexer / the LaunchAgent) so Messages writes execute under node.";
+
+/**
+ * @param {"contacts"|"calendar"|"mail"|"messages"|string} source
  */
 export function tccGuidanceFor(source) {
   if (source === "contacts") return CONTACTS_TCC_GUIDANCE;
   if (source === "calendar") return CALENDAR_TCC_GUIDANCE;
+  if (source === "mail") return MAIL_TCC_GUIDANCE;
+  if (source === "messages") return MESSAGES_TCC_GUIDANCE;
   return TCC_GUIDANCE;
 }
 
@@ -184,9 +308,9 @@ export function tccGuidanceFor(source) {
  * @returns {{ ok: boolean, output: string, error: string|null, kind: string|null }}
  */
 export function runAppleScript(script, options = {}) {
-  const { timeout = DEFAULT_SCRIPT_TIMEOUT_MS, appName = null } = options;
+  const { timeout = DEFAULT_SCRIPT_TIMEOUT_MS, appName = null, language = null } = options;
   try {
-    const output = safeOsascript(script, { timeout });
+    const output = safeOsascript(script, { timeout, language });
     return { ok: true, output: (output || "").trim(), error: null, kind: null };
   } catch (e) {
     const message = e && e.message ? e.message : String(e);