icloud-mcp 1.5.0 → 1.6.0

package/index.js

@@ -42,8 +42,35 @@ function createClient() {
 
 // ─── Managed client helpers ───────────────────────────────────────────────────
 
-async function openClient(mailbox) {
+// Rate limit: space out connection initiations within a single server process
+// to avoid triggering iCloud's connection throttle under concurrent tool calls.
+// Wraps connect() on every client returned by createClient() so the gate
+// applies regardless of whether tools use openClient() or createClient() directly.
+// Uses a serialized gate — concurrent callers queue up; each waits 200ms after
+// the previous before initiating its connection. Connections run concurrently
+// after passing the gate.
+let _lastConnectTime = 0;
+let _connectGate = Promise.resolve();
+const MIN_CONNECT_INTERVAL = 10; // ms between connection initiations
+
+function createRateLimitedClient() {
   const client = createClient();
+  const originalConnect = client.connect.bind(client);
+  client.connect = async () => {
+    await new Promise(resolve => {
+      _connectGate = _connectGate.then(async () => {
+        const wait = MIN_CONNECT_INTERVAL - (Date.now() - _lastConnectTime);
+        if (wait > 0) await new Promise(r => setTimeout(r, wait));
+        _lastConnectTime = Date.now();
+      }).then(resolve, resolve);
+    });
+    return originalConnect();
+  };
+  return client;
+}
+
+async function openClient(mailbox) {
+  const client = createRateLimitedClient();
   await client.connect();
   if (mailbox) await client.mailboxOpen(mailbox);
   return client;
@@ -156,6 +183,10 @@ function startOperation(source, target, uids) {
     target,
     totalUids: uids.length,
     status: 'in_progress',
+    phase: 'copying',
+    verifiedAt: null,
+    deletedAt: null,
+    allFingerprints: null,
     chunks,
     summary: {
       chunksComplete: 0,
@@ -191,6 +222,14 @@ function updateChunk(index, updates) {
   });
 }
 
+function updateOperationPhase(phase, extraFields = {}) {
+  updateManifest((data) => {
+    if (!data.current) return;
+    data.current.phase = phase;
+    Object.assign(data.current, extraFields);
+  });
+}
+
 function completeOperation() {
   const data = readManifest();
   if (!data.current) return;
@@ -214,10 +253,13 @@ function formatOperation(op) {
   return {
     operationId: op.operationId,
     status: op.status,
+    phase: op.phase ?? null,
     source: op.source,
     target: op.target,
     startedAt: op.startedAt,
     updatedAt: op.updatedAt,
+    verifiedAt: op.verifiedAt ?? null,
+    deletedAt: op.deletedAt ?? null,
     summary: op.summary,
     failedChunks: op.chunks.filter(c => c.status === 'failed').map(c => ({
       index: c.index,
@@ -287,13 +329,17 @@ async function withRetry(label, fn, maxAttempts = 3) {
 
 // ─── Per-operation timeouts ───────────────────────────────────────────────────
 
+const COPY_CHUNK_DELAY_MS = 500; // ms between COPY chunks — mitigates iCloud copy throttling
+
 const TIMEOUT = {
-  METADATA: 15_000,
-  FETCH:    30_000,
-  SCAN:     60_000,
-  BULK_OP:  60_000,
-  CHUNK:   300_000,
-  SINGLE:   15_000,
+  METADATA:   15_000,
+  FETCH:      30_000,
+  SCAN:       60_000,
+  BULK_OP:    60_000,
+  CHUNK:     300_000,
+  SINGLE:     15_000,
+  VERIFY_ALL: 120_000, // full envelope scan for all N emails
+  DELETE_ALL: 600_000, // flag all + single UID EXPUNGE (measured up to 521s at 5k)
 };
 
 function withTimeout(label, ms, fn) {
@@ -390,6 +436,11 @@ async function verifyInTarget(targetClient, fingerprints, chunkIndex, knownTotal
     return { verified: true, missing: [], found: fingerprints.length, expected: fingerprints.length };
   }
 
+  if (afterScan.length > 200) {
+    moveLog(chunkIndex, `${afterScan.length} unmatched after envelope scan — too many for Message-ID fallback, treating as failed`);
+    return { verified: false, missing: afterScan, found: fingerprints.length - afterScan.length, expected: fingerprints.length };
+  }
+
   // Secondary: Message-ID search only for the ones envelope scan missed
   moveLog(chunkIndex, `${afterScan.length} unmatched after envelope scan — trying Message-ID search`);
   const withMessageId = afterScan.filter(fp => fp.messageId);
@@ -415,12 +466,146 @@ async function verifyInTarget(targetClient, fingerprints, chunkIndex, knownTotal
   };
 }
 
-// ─── Safe Move (v3: connection reuse + envelope-first verify + logging) ───────
+// ─── Option B phase helpers ────────────────────────────────────────────────────
+
+// Phase 1: Copy all chunks to target without deleting.
+// Returns { success, totalCopied, srcClient, errorResult }
+async function copyAllChunks(operation, srcClient, targetMailbox, sourceMailbox) {
+  let totalCopied = 0;
+
+  for (const chunk of operation.chunks) {
+    const chunkUids = chunk.uids;
+    const chunkStart = Date.now();
+    moveLog(chunk.index, `starting copy (${chunkUids.length} emails)`);
+
+    try {
+      await withTimeout(`copy chunk ${chunk.index}`, TIMEOUT.CHUNK, async () => {
+        // Step 1: fetch envelopes → fingerprints
+        let t = Date.now();
+        const envelopes = [];
+        try {
+          for await (const msg of srcClient.fetch(chunkUids, { envelope: true }, { uid: true })) {
+            envelopes.push(msg);
+          }
+        } catch (err) {
+          if (!isTransient(err)) throw err;
+          moveLog(chunk.index, `fetch envelopes failed (${err.message}), reconnecting...`);
+          srcClient = await reconnect(srcClient, sourceMailbox);
+          for await (const msg of srcClient.fetch(chunkUids, { envelope: true }, { uid: true })) {
+            envelopes.push(msg);
+          }
+        }
+        const fingerprints = envelopes.map(buildFingerprint);
+        const withMsgId = fingerprints.filter(fp => fp.messageId).length;
+        moveLog(chunk.index, `fetched ${envelopes.length} envelopes (${withMsgId} with Message-ID) (${elapsed(t)})`);
+
+        // Update in-memory chunk so verifyAllChunks can flatMap fingerprints later
+        chunk.fingerprints = fingerprints;
+        updateManifest((data) => {
+          if (!data.current) return;
+          const c = data.current.chunks[chunk.index];
+          if (!c) return;
+          c.fingerprints = fingerprints;
+        });
+
+        // Step 2: copy to target
+        t = Date.now();
+        try {
+          await srcClient.messageCopy(chunkUids, targetMailbox, { uid: true });
+        } catch (err) {
+          if (!isTransient(err)) throw err;
+          moveLog(chunk.index, `copy failed (${err.message}), reconnecting...`);
+          srcClient = await reconnect(srcClient, sourceMailbox);
+          await srcClient.messageCopy(chunkUids, targetMailbox, { uid: true });
+        }
+        moveLog(chunk.index, `copied ${chunkUids.length} emails to target (${elapsed(t)})`);
+        updateChunk(chunk.index, { status: 'copied_not_verified', copiedAt: new Date().toISOString() });
+      });
+
+      totalCopied += chunkUids.length;
+      moveLog(chunk.index, `copy complete (${elapsed(chunkStart)})`);
+    } catch (err) {
+      moveLog(chunk.index, `copy FAILED: ${err.message}`);
+      updateChunk(chunk.index, { status: 'failed', failureReason: err.message });
+      return {
+        success: false,
+        totalCopied,
+        srcClient,
+        errorResult: {
+          status: 'partial',
+          moved: 0,
+          failed: operation.totalUids,
+          message: `Copy failed on chunk ${chunk.index}: ${err.message}. No emails deleted from source. ${totalCopied} emails were copied to target but not verified — call get_move_status for details.`
+        }
+      };
+    }
+
+    // Delay between chunks to mitigate iCloud copy throttling
+    if (chunk.index < operation.chunks.length - 1) {
+      await new Promise(r => setTimeout(r, COPY_CHUNK_DELAY_MS));
+    }
+  }
+
+  return { success: true, totalCopied, srcClient, errorResult: null };
+}
+
+// Phase 2: Verify all copied emails are present in target.
+// Returns { verification, tgtClient }
+async function verifyAllChunks(tgtClient, operation, targetMailbox) {
+  const allFingerprints = operation.chunks.flatMap(c => c.fingerprints);
+
+  updateManifest((data) => {
+    if (!data.current) return;
+    data.current.allFingerprints = allFingerprints;
+  });
+
+  let tgtMb;
+  try {
+    tgtMb = await tgtClient.mailboxOpen(targetMailbox);
+  } catch (err) {
+    if (!isTransient(err)) throw err;
+    moveLog('global', `mailboxOpen failed (${err.message}), reconnecting...`);
+    tgtClient = await reconnect(tgtClient, targetMailbox);
+    tgtMb = await tgtClient.mailboxOpen(targetMailbox);
+  }
+
+  let verification;
+  try {
+    verification = await verifyInTarget(tgtClient, allFingerprints, 'global', tgtMb.exists);
+  } catch (err) {
+    if (!isTransient(err)) throw err;
+    moveLog('global', `verify failed (${err.message}), reconnecting...`);
+    tgtClient = await reconnect(tgtClient, targetMailbox);
+    verification = await verifyInTarget(tgtClient, allFingerprints, 'global');
+  }
+
+  return { verification, tgtClient };
+}
+
+// Phase 3: Delete all source emails in a single EXPUNGE.
+// Returns { srcClient }
+async function deleteAllChunks(srcClient, operation, sourceMailbox) {
+  const allUids = operation.chunks.flatMap(c => c.uids);
+  const t = Date.now();
+
+  try {
+    await srcClient.messageDelete(allUids, { uid: true });
+  } catch (err) {
+    if (!isTransient(err)) throw err;
+    moveLog('global', `delete failed (${err.message}), reconnecting...`);
+    srcClient = await reconnect(srcClient, sourceMailbox);
+    // Retry is idempotent — expunging already-gone UIDs is a no-op
+    await srcClient.messageDelete(allUids, { uid: true });
+  }
+
+  moveLog('global', `deleted ${allUids.length} from source — single EXPUNGE (${elapsed(t)})`);
+  return { srcClient };
+}
+
+// ─── Safe Move (Option B: COPY-all → VERIFY-all → single EXPUNGE) ─────────────
 
 async function safeMoveEmails(uids, sourceMailbox, targetMailbox) {
   const operation = startOperation(sourceMailbox, targetMailbox, uids);
-  let totalMoved = 0;
-  let totalFailed = 0;
   const opStart = Date.now();
 
   process.stderr.write(`[move] starting: ${uids.length} emails, ${operation.chunks.length} chunks, ${sourceMailbox} → ${targetMailbox}\n`);
@@ -429,151 +614,87 @@ async function safeMoveEmails(uids, sourceMailbox, targetMailbox) {
   let tgtClient = await openClient(targetMailbox);
 
   try {
-    for (const chunk of operation.chunks) {
-      const chunkUids = chunk.uids;
-      let succeeded = false;
-      const chunkStart = Date.now();
+    // Phase 1: COPY all chunks to target (no delete yet)
+    process.stderr.write(`[move] phase 1/3: copying ${uids.length} emails in ${operation.chunks.length} chunks\n`);
+    const copyResult = await copyAllChunks(operation, srcClient, targetMailbox, sourceMailbox);
+    srcClient = copyResult.srcClient;
+
+    if (!copyResult.success) {
+      failOperation(`Copy phase failed: ${copyResult.errorResult.message}`);
+      return copyResult.errorResult;
+    }
 
-      moveLog(chunk.index, `starting (${chunkUids.length} emails)`);
+    // Phase 2: VERIFY all emails are present in target
+    process.stderr.write(`[move] phase 2/3: verifying all ${copyResult.totalCopied} emails in target\n`);
+    updateOperationPhase('verifying');
 
-      for (const attemptChunkSize of [CHUNK_SIZE, CHUNK_SIZE_RETRY]) {
-        const subChunks = [];
-        for (let i = 0; i < chunkUids.length; i += attemptChunkSize) {
-          subChunks.push(chunkUids.slice(i, i + attemptChunkSize));
-        }
+    let verifyResult;
+    try {
+      verifyResult = await withTimeout('verify all', TIMEOUT.VERIFY_ALL, () =>
+        verifyAllChunks(tgtClient, operation, targetMailbox)
+      );
+      tgtClient = verifyResult.tgtClient;
+    } catch (err) {
+      moveLog('global', `verify phase FAILED: ${err.message}`);
+      failOperation(`Verify phase failed: ${err.message}`);
+      return {
+        status: 'failed',
+        moved: 0,
+        message: `Verification timed out or failed: ${err.message}. All ${copyResult.totalCopied} emails remain in source (not deleted). Call get_move_status for details.`
+      };
+    }
 
-        let verificationFailed = false;
-
-        for (const subChunk of subChunks) {
-          try {
-            await withTimeout(`safeMoveEmails chunk ${chunk.index}`, TIMEOUT.CHUNK, async () => {
-              // Step 1: fetch fingerprints from source
-              let t = Date.now();
-              const envelopes = [];
-              try {
-                for await (const msg of srcClient.fetch(subChunk, { envelope: true }, { uid: true })) {
-                  envelopes.push(msg);
-                }
-              } catch (err) {
-                if (!isTransient(err)) throw err;
-                moveLog(chunk.index, `fetch envelopes failed (${err.message}), reconnecting...`);
-                srcClient = await reconnect(srcClient, sourceMailbox);
-                for await (const msg of srcClient.fetch(subChunk, { envelope: true }, { uid: true })) {
-                  envelopes.push(msg);
-                }
-              }
-              const fingerprints = envelopes.map(buildFingerprint);
-              const withMsgId = fingerprints.filter(fp => fp.messageId).length;
-              moveLog(chunk.index, `fetched ${envelopes.length} envelopes (${withMsgId} with Message-ID) (${elapsed(t)})`);
-
-              updateManifest((data) => {
-                if (!data.current) return;
-                const c = data.current.chunks[chunk.index];
-                if (!c) return;
-                c.fingerprints = [...c.fingerprints, ...fingerprints];
-                c.status = 'pending';
-              });
-
-              // Step 2: copy to target
-              t = Date.now();
-              try {
-                await srcClient.messageCopy(subChunk, targetMailbox, { uid: true });
-              } catch (err) {
-                if (!isTransient(err)) throw err;
-                moveLog(chunk.index, `copy failed (${err.message}), reconnecting...`);
-                srcClient = await reconnect(srcClient, sourceMailbox);
-                await srcClient.messageCopy(subChunk, targetMailbox, { uid: true });
-              }
-              moveLog(chunk.index, `copied ${subChunk.length} emails to target (${elapsed(t)})`);
-              updateChunk(chunk.index, { status: 'copied_not_verified', copiedAt: new Date().toISOString() });
-
-              // Step 3: verify in target
-              t = Date.now();
-              let verification;
-              try {
-                const tgtMb = await tgtClient.mailboxOpen(targetMailbox);
-                verification = await verifyInTarget(tgtClient, fingerprints, chunk.index, tgtMb.exists);
-              } catch (err) {
-                if (!isTransient(err)) throw err;
-                moveLog(chunk.index, `verify failed (${err.message}), reconnecting...`);
-                tgtClient = await reconnect(tgtClient, targetMailbox);
-                verification = await verifyInTarget(tgtClient, fingerprints, chunk.index);
-              }
-              moveLog(chunk.index, `verification: ${verification.found}/${verification.expected} confirmed (${elapsed(t)})`);
-
-              if (!verification.verified) {
-                throw Object.assign(new Error('verification_failed'), { _verificationFailed: true });
-              }
-              updateChunk(chunk.index, { status: 'verified_not_deleted', verifiedAt: new Date().toISOString() });
-
-              // Step 4: delete from source
-              t = Date.now();
-              try {
-                await srcClient.messageDelete(subChunk, { uid: true });
-              } catch (err) {
-                if (!isTransient(err)) throw err;
-                moveLog(chunk.index, `delete failed (${err.message}), reconnecting...`);
-                srcClient = await reconnect(srcClient, sourceMailbox);
-                await srcClient.messageDelete(subChunk, { uid: true });
-              }
-              moveLog(chunk.index, `deleted ${subChunk.length} from source (${elapsed(t)})`);
-            });
-            totalMoved += subChunk.length;
-            moveLog(chunk.index, `sub-chunk complete: ${subChunk.length} moved (chunk total: ${totalMoved}/${operation.totalUids})`);
-          } catch (err) {
-            if (err._verificationFailed) {
-              verificationFailed = true;
-              break;
-            }
-            moveLog(chunk.index, `FAILED: ${err.message}`);
-            updateChunk(chunk.index, {
-              status: 'failed',
-              failureReason: err.message
-            });
-            totalFailed += chunkUids.length;
-            failOperation(`Chunk ${chunk.index} failed: ${err.message}`);
-            return {
-              status: 'partial',
-              moved: totalMoved,
-              failed: totalFailed,
-              message: `${err.message}. ${totalMoved} emails moved successfully. ${operation.totalUids - totalMoved} remain in source untouched. Call get_move_status for details.`
-            };
-          }
-        }
+    const { verification } = verifyResult;
+    moveLog('global', `verification: ${verification.found}/${verification.expected} confirmed`);
 
-        if (!verificationFailed) {
-          succeeded = true;
-          break;
-        }
+    if (!verification.verified) {
+      moveLog('global', `FAILED: ${verification.missing.length} emails missing from target after copy`);
+      failOperation(`Verification failed: ${verification.missing.length} emails missing from target`);
+      return {
+        status: 'failed',
+        moved: 0,
+        message: `Verification failed: ${verification.missing.length} of ${verification.expected} emails did not arrive in target. Source emails untouched. Call get_move_status for details.`
+      };
+    }
 
-        if (attemptChunkSize === CHUNK_SIZE_RETRY) {
-          moveLog(chunk.index, `FAILED: verification failed at both chunk sizes`);
-          updateChunk(chunk.index, {
-            status: 'failed',
-            failureReason: 'Verification failed at both chunk sizes'
-          });
-          totalFailed += chunkUids.length;
-          failOperation(`Verification failed after retry on chunk ${chunk.index}`);
-          return {
-            status: 'partial',
-            moved: totalMoved,
-            failed: totalFailed,
-            message: `Verification failed after retry. ${totalMoved} emails moved successfully. ${operation.totalUids - totalMoved} remain in source untouched. Call get_move_status for details.`
-          };
-        }
+    updateOperationPhase('verifying', { verifiedAt: new Date().toISOString() });
 
-        moveLog(chunk.index, `verification failed at chunk size ${attemptChunkSize}, retrying at ${CHUNK_SIZE_RETRY}`);
-      }
+    // Mark all chunks as verified
+    for (const chunk of operation.chunks) {
+      updateChunk(chunk.index, { status: 'verified_not_deleted', verifiedAt: new Date().toISOString() });
+    }
 
-      if (succeeded) {
-        updateChunk(chunk.index, { status: 'complete', deletedAt: new Date().toISOString() });
-        moveLog(chunk.index, `COMPLETE (${elapsed(chunkStart)})`);
-      }
+    // Phase 3: DELETE all source emails — single EXPUNGE
+    process.stderr.write(`[move] phase 3/3: deleting all ${uids.length} emails from source (1 EXPUNGE)\n`);
+    updateOperationPhase('deleting');
+
+    let deleteResult;
+    try {
+      deleteResult = await withTimeout('delete all', TIMEOUT.DELETE_ALL, () =>
+        deleteAllChunks(srcClient, operation, sourceMailbox)
+      );
+      srcClient = deleteResult.srcClient;
+    } catch (err) {
+      moveLog('global', `delete phase FAILED: ${err.message}`);
+      // Emails are safe in target (verified). Source may still have them.
+      failOperation(`Delete phase failed: ${err.message}`);
+      return {
+        status: 'failed',
+        moved: 0,
+        message: `Delete phase failed: ${err.message}. All ${copyResult.totalCopied} emails exist in target (verified) but may still exist in source. Call get_move_status for details.`
+      };
     }
 
+    // Mark all chunks complete
+    const now = new Date().toISOString();
+    for (const chunk of operation.chunks) {
+      updateChunk(chunk.index, { status: 'complete', deletedAt: now });
+    }
+    updateOperationPhase('deleting', { deletedAt: now });
     completeOperation();
-    process.stderr.write(`[move] COMPLETE: ${totalMoved}/${operation.totalUids} emails moved (${elapsed(opStart)})\n`);
-    return { status: 'complete', moved: totalMoved, total: operation.totalUids };
+
+    process.stderr.write(`[move] COMPLETE: ${copyResult.totalCopied}/${operation.totalUids} emails moved (${elapsed(opStart)})\n`);
+    return { status: 'complete', moved: copyResult.totalCopied, total: operation.totalUids };
   } finally {
     await safeClose(srcClient);
     await safeClose(tgtClient);
@@ -583,7 +704,7 @@ async function safeMoveEmails(uids, sourceMailbox, targetMailbox) {
 // ─── Email Functions ──────────────────────────────────────────────────────────
 
 async function fetchEmails(mailbox = 'INBOX', limit = 10, onlyUnread = false, page = 1) {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   const mb = await client.mailboxOpen(mailbox);
   const total = mb.exists;
@@ -637,7 +758,7 @@ async function fetchEmails(mailbox = 'INBOX', limit = 10, onlyUnread = false, pa
 }
 
 async function getInboxSummary(mailbox = 'INBOX') {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   const status = await client.status(mailbox, { messages: true, unseen: true, recent: true });
   await client.logout();
@@ -645,7 +766,7 @@ async function getInboxSummary(mailbox = 'INBOX') {
 }
 
 async function getTopSenders(mailbox = 'INBOX', sampleSize = 500, maxResults = 20) {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   const mb = await client.mailboxOpen(mailbox);
   const total = mb.exists;
@@ -674,7 +795,7 @@ async function getTopSenders(mailbox = 'INBOX', sampleSize = 500, maxResults = 2
 }
 
 async function getUnreadSenders(mailbox = 'INBOX', sampleSize = 500, maxResults = 20) {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
   const uids = (await client.search({ seen: false }, { uid: true })) ?? [];
@@ -696,7 +817,7 @@ async function getUnreadSenders(mailbox = 'INBOX', sampleSize = 500, maxResults
 }
 
 async function getEmailsBySender(sender, mailbox = 'INBOX', limit = 10) {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
   const uids = (await client.search({ from: sender }, { uid: true })) ?? [];
@@ -721,7 +842,7 @@ async function getEmailsBySender(sender, mailbox = 'INBOX', limit = 10) {
 }
 
 async function bulkDeleteBySender(sender, mailbox = 'INBOX') {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
   const uids = (await client.search({ from: sender }, { uid: true })) ?? [];
@@ -736,12 +857,13 @@ async function bulkDeleteBySender(sender, mailbox = 'INBOX') {
   return { deleted, sender };
 }
 
-async function bulkMoveBySender(sender, targetMailbox, sourceMailbox = 'INBOX') {
-  const client = createClient();
+async function bulkMoveBySender(sender, targetMailbox, sourceMailbox = 'INBOX', dryRun = false) {
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(sourceMailbox);
   const uids = (await client.search({ from: sender }, { uid: true })) ?? [];
   await client.logout();
+  if (dryRun) return { dryRun: true, wouldMove: uids.length, sender, sourceMailbox, targetMailbox };
   if (uids.length === 0) return { moved: 0 };
   await ensureMailbox(targetMailbox);
   const result = await safeMoveEmails(uids, sourceMailbox, targetMailbox);
@@ -749,7 +871,7 @@ async function bulkMoveBySender(sender, targetMailbox, sourceMailbox = 'INBOX')
 }
 
 async function bulkDeleteBySubject(subject, mailbox = 'INBOX') {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
   const uids = (await client.search({ subject }, { uid: true })) ?? [];
@@ -765,7 +887,7 @@ async function bulkDeleteBySubject(subject, mailbox = 'INBOX') {
 }
 
 async function deleteOlderThan(days, mailbox = 'INBOX') {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
   const date = new Date();
@@ -783,7 +905,7 @@ async function deleteOlderThan(days, mailbox = 'INBOX') {
 }
 
 async function getEmailsByDateRange(startDate, endDate, mailbox = 'INBOX', limit = 10) {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
   const uids = (await client.search({ since: new Date(startDate), before: new Date(endDate) }, { uid: true })) ?? [];
@@ -808,7 +930,7 @@ async function getEmailsByDateRange(startDate, endDate, mailbox = 'INBOX', limit
 }
 
 async function bulkMarkRead(mailbox = 'INBOX', sender = null) {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
   const query = sender ? { from: sender, seen: false } : { seen: false };
@@ -820,7 +942,7 @@ async function bulkMarkRead(mailbox = 'INBOX', sender = null) {
 }
 
 async function bulkMarkUnread(mailbox = 'INBOX', sender = null) {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
   const query = sender ? { from: sender, seen: true } : { seen: true };
@@ -832,7 +954,7 @@ async function bulkMarkUnread(mailbox = 'INBOX', sender = null) {
 }
 
 async function bulkFlag(filters, flagged, mailbox = 'INBOX') {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
   const query = buildQuery(filters);
@@ -848,7 +970,7 @@ async function bulkFlag(filters, flagged, mailbox = 'INBOX') {
 }
 
 async function emptyTrash() {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen('Deleted Messages');
   const uids = (await client.search({ all: true }, { uid: true })) ?? [];
@@ -864,7 +986,7 @@ async function emptyTrash() {
 }
 
 async function createMailbox(name) {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxCreate(name);
   await client.logout();
@@ -872,7 +994,7 @@ async function createMailbox(name) {
 }
 
 async function renameMailbox(oldName, newName) {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   try {
     await Promise.race([
@@ -888,7 +1010,7 @@ async function renameMailbox(oldName, newName) {
 }
 
 async function deleteMailbox(name) {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   try {
     await Promise.race([
@@ -904,7 +1026,7 @@ async function deleteMailbox(name) {
 }
 
 async function getMailboxSummary(mailbox) {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   const status = await client.status(mailbox, { messages: true, unseen: true, recent: true });
   await client.logout();
@@ -912,7 +1034,7 @@ async function getMailboxSummary(mailbox) {
 }
 
 async function getEmailContent(uid, mailbox = 'INBOX') {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
   const meta = await client.fetchOne(uid, { envelope: true, flags: true }, { uid: true });
@@ -942,7 +1064,7 @@ async function getEmailContent(uid, mailbox = 'INBOX') {
 }
 
 async function flagEmail(uid, flagged, mailbox = 'INBOX') {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
   if (flagged) {
@@ -955,7 +1077,7 @@ async function flagEmail(uid, flagged, mailbox = 'INBOX') {
 }
 
 async function markAsRead(uid, seen, mailbox = 'INBOX') {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
   if (seen) {
@@ -968,7 +1090,7 @@ async function markAsRead(uid, seen, mailbox = 'INBOX') {
 }
 
 async function deleteEmail(uid, mailbox = 'INBOX') {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
   await client.messageDelete(uid, { uid: true });
@@ -977,7 +1099,7 @@ async function deleteEmail(uid, mailbox = 'INBOX') {
 }
 
 async function listMailboxes() {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   const tree = await client.listTree();
   const mailboxes = [];
@@ -993,7 +1115,7 @@ async function listMailboxes() {
 }
 
 async function searchEmails(query, mailbox = 'INBOX', limit = 10, filters = {}) {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
 
@@ -1024,7 +1146,7 @@ async function searchEmails(query, mailbox = 'INBOX', limit = 10, filters = {})
 }
 
 async function moveEmail(uid, targetMailbox, sourceMailbox = 'INBOX') {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(sourceMailbox);
   await client.messageMove(uid, targetMailbox, { uid: true });
@@ -1051,14 +1173,14 @@ function buildQuery(filters) {
 }
 
 async function ensureMailbox(name) {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   try { await client.mailboxCreate(name); } catch { /* already exists */ }
   await client.logout();
 }
 
 async function bulkMove(filters, targetMailbox, sourceMailbox = 'INBOX', dryRun = false, limit = null) {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(sourceMailbox);
   const query = buildQuery(filters);
@@ -1083,7 +1205,7 @@ async function bulkMove(filters, targetMailbox, sourceMailbox = 'INBOX', dryRun
 // hanging forever.
 
 async function bulkDelete(filters, sourceMailbox = 'INBOX', dryRun = false) {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(sourceMailbox);
   const query = buildQuery(filters);
@@ -1120,7 +1242,7 @@ async function bulkDelete(filters, sourceMailbox = 'INBOX', dryRun = false) {
 }
 
 async function countEmails(filters, mailbox = 'INBOX') {
-  const client = createClient();
+  const client = createRateLimitedClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
   const query = buildQuery(filters);
@@ -1157,7 +1279,7 @@ function logClear() {
 
 async function main() {
   const server = new Server(
-    { name: 'icloud-mail', version: '1.5.0' },
+    { name: 'icloud-mail', version: '1.6.0' },
     { capabilities: { tools: {} } }
   );
 
@@ -1337,7 +1459,8 @@ async function main() {
           properties: {
             sender: { type: 'string', description: 'Sender email address' },
             targetMailbox: { type: 'string', description: 'Destination folder' },
-            sourceMailbox: { type: 'string', description: 'Source mailbox (default INBOX)' }
+            sourceMailbox: { type: 'string', description: 'Source mailbox (default INBOX)' },
+            dryRun: { type: 'boolean', description: 'Preview only — return count without moving' }
           },
           required: ['sender', 'targetMailbox']
         }
@@ -1585,7 +1708,7 @@ async function main() {
         const { targetMailbox, sourceMailbox, dryRun, limit, ...filters } = args;
         result = await bulkMove(filters, targetMailbox, sourceMailbox || 'INBOX', dryRun || false, limit ?? null);
       } else if (name === 'bulk_move_by_sender') {
-        result = await bulkMoveBySender(args.sender, args.targetMailbox, args.sourceMailbox || 'INBOX');
+        result = await bulkMoveBySender(args.sender, args.targetMailbox, args.sourceMailbox || 'INBOX', args.dryRun || false);
       } else if (name === 'bulk_delete') {
         // IMPROVEMENT 3: bulk_delete now has per-chunk timeouts internally
         const { sourceMailbox, dryRun, ...filters } = args;
@@ -1710,7 +1833,7 @@ async function runDoctor() {
     {
       label: `Connected to imap.mail.me.com:993`,
       run: async () => {
-        const client = createClient();
+        const client = createRateLimitedClient();
         await client.connect();
         await client.logout();
       }
@@ -1725,7 +1848,7 @@ async function runDoctor() {
     {
       label: 'INBOX opened',
       run: async () => {
-        const client = createClient();
+        const client = createRateLimitedClient();
         await client.connect();
         const mb = await client.mailboxOpen('INBOX');
         await client.logout();