icloud-mcp 1.4.1 → 1.5.0

package/README.md

@@ -43,9 +43,40 @@ Then find the install location:
 npm root -g
 ```
 
-This will return a path like `/opt/homebrew/lib/node_modules` or `/usr/local/lib/node_modules`.
+The path varies by setup:
 
-### 3. Configure Claude Desktop
+| Setup | Typical path |
+|-------|-------------|
+| Mac with Homebrew Node | `/opt/homebrew/lib/node_modules` |
+| Mac with system Node | `/usr/local/lib/node_modules` |
+| nvm | `~/.nvm/versions/node/v20.x.x/lib/node_modules` |
+
+### 3. Verify your setup
+
+Before configuring Claude Desktop, run the doctor command to confirm everything is working:
+
+```bash
+IMAP_USER="you@icloud.com" IMAP_PASSWORD="your-app-specific-password" node $(npm root -g)/icloud-mcp/index.js --doctor
+```
+
+You should see:
+
+```
+icloud-mcp doctor
+─────────────────────────────
+✅ IMAP_USER is set
+✅ IMAP_PASSWORD is set
+✅ IMAP_USER looks like an email address
+✅ Connected to imap.mail.me.com:993
+✅ Authenticated as you@icloud.com
+✅ INBOX opened (12453 messages)
+─────────────────────────────
+All checks passed. Ready to use with Claude Desktop.
+```
+
+If any step fails, a plain-English explanation and suggested fix will be shown.
+
+### 4. Configure Claude Desktop
 
 Open your Claude Desktop config file:
 
@@ -53,7 +84,7 @@ Open your Claude Desktop config file:
 open ~/Library/Application\ Support/Claude/claude_desktop_config.json
 ```
 
-Add the following under `mcpServers`, replacing the path with your npm root path from the previous step:
+Add the following under `mcpServers`, replacing the path with your npm root from step 2:
 
 ```json
 {
@@ -70,9 +101,7 @@ Add the following under `mcpServers`, replacing the path with your npm root path
 }
 ```
 
-> **Note:** If your `npm root -g` returned a different path, replace `/opt/homebrew/lib/node_modules` with that path.
-
-### 4. Add Custom Instructions (Recommended)
+### 5. Add Custom Instructions (Recommended)
 
 For large inbox operations, add the following to Claude Desktop's custom instructions to ensure Claude stays on track and checks in with you regularly. Go to **Claude Desktop → Settings → Custom Instructions** and add:
 
@@ -85,7 +114,7 @@ When using icloud-mail tools:
 5. If you are ever unsure what you have done so far, call log_read before proceeding
 ```
 
-### 5. Restart Claude Desktop
+### 6. Restart Claude Desktop
 
 Fully quit Claude Desktop (Cmd+Q) and reopen it. You should now be able to manage your iCloud inbox through Claude.
 
@@ -103,7 +132,7 @@ Fully quit Claude Desktop (Cmd+Q) and reopen it. You should now be able to manag
 | `get_emails_by_date_range` | Emails between two dates |
 | `search_emails` | Search by keyword with optional filters (date, unread, domain, etc.) |
 | `count_emails` | Count emails matching any combination of filters without modifying them |
-| `bulk_move` | Move emails matching any combination of filters between folders (supports `dryRun`) |
+| `bulk_move` | Move emails matching any combination of filters between folders (supports `dryRun` and `limit`) |
 | `bulk_delete` | Delete emails matching any combination of filters (supports `dryRun`) |
 | `bulk_flag` | Flag or unflag emails matching any combination of filters |
 | `bulk_mark_read` | Mark all emails (or all from a sender) as read |

package/index.js

@@ -15,23 +15,52 @@ const IMAP_USER = process.env.IMAP_USER;
 const IMAP_PASSWORD = process.env.IMAP_PASSWORD;
 
 if (!IMAP_USER || !IMAP_PASSWORD) {
-  process.stderr.write('Error: IMAP_USER and IMAP_PASSWORD environment variables are required\n');
-  process.exit(1);
+  if (process.argv.includes('--doctor')) {
+    // Doctor will handle missing credentials with friendly output
+  } else {
+    process.stderr.write('Error: IMAP_USER and IMAP_PASSWORD environment variables are required\n');
+    process.exit(1);
+  }
 }
 
+// ─── IMPROVEMENT 1: Connection-level timeout on createClient ──────────────────
+// ImapFlow supports connectionTimeout and greetingTimeout options.
+// This ensures we don't hang forever waiting for iCloud to respond.
+
 function createClient() {
   return new ImapFlow({
     host: 'imap.mail.me.com',
     port: 993,
     secure: true,
     auth: { user: IMAP_USER, pass: IMAP_PASSWORD },
-    logger: false
+    logger: false,
+    connectionTimeout: 15_000,   // 15s to establish TCP+TLS connection
+    greetingTimeout: 15_000,     // 15s to receive IMAP greeting after connect
+    socketTimeout: 60_000,       // 60s of inactivity before socket is killed
   });
 }
 
+// ─── Managed client helpers ───────────────────────────────────────────────────
+
+async function openClient(mailbox) {
+  const client = createClient();
+  await client.connect();
+  if (mailbox) await client.mailboxOpen(mailbox);
+  return client;
+}
+
+async function safeClose(client) {
+  try { await client.logout(); } catch { try { client.close(); } catch { /* already gone */ } }
+}
+
+async function reconnect(client, mailbox) {
+  safeClose(client);
+  return openClient(mailbox);
+}
+
 // ─── Move Manifest ────────────────────────────────────────────────────────────
 
-const CHUNK_SIZE = 250;
+const CHUNK_SIZE = 500;
 const CHUNK_SIZE_RETRY = 100;
 
 function readManifest() {
@@ -49,7 +78,9 @@ function writeManifest(data) {
 
 function updateManifest(updater) {
   const data = readManifest();
+  if (!data.current) return data; // guard: operation already archived/failed
   updater(data);
+  if (!data.current) return data; // guard: updater may have archived it
   data.current.updatedAt = new Date().toISOString();
   writeManifest(data);
   return data;
@@ -140,7 +171,9 @@ function startOperation(source, target, uids) {
 
 function updateChunk(index, updates) {
   updateManifest((data) => {
+    if (!data.current) return; // guard: operation already archived
     const chunk = data.current.chunks[index];
+    if (!chunk) return; // guard: chunk index out of range
     Object.assign(chunk, updates);
 
     let moved = 0, failed = 0, pending = 0;
@@ -222,188 +255,329 @@ function fingerprintToKey(fp) {
   return fp.messageId ?? fp.fallback;
 }
 
-// ─── IMAP Move Helpers ────────────────────────────────────────────────────────
+// ─── Transient error detection ────────────────────────────────────────────────
 
-async function fetchEnvelopes(mailbox, uids) {
-  const client = createClient();
-  await client.connect();
-  await client.mailboxOpen(mailbox);
-  const envelopes = [];
-  for await (const msg of client.fetch(uids, { envelope: true }, { uid: true })) {
-    envelopes.push(msg);
+function isTransient(err) {
+  const msg = err.message ?? '';
+  return msg.includes('ECONNRESET') ||
+    msg.includes('ECONNREFUSED') ||
+    msg.includes('ETIMEDOUT') ||
+    msg.includes('EPIPE') ||
+    msg.includes('socket hang up') ||
+    msg.includes('Connection not available') ||
+    msg.includes('BAD') ||
+    msg.includes('NO ');
+}
+
+async function withRetry(label, fn, maxAttempts = 3) {
+  let lastErr;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (!isTransient(err) || attempt === maxAttempts) throw err;
+      const delay = attempt * 2000;
+      process.stderr.write(`[retry] ${label} failed (attempt ${attempt}/${maxAttempts}): ${err.message} — retrying in ${delay}ms\n`);
+      await new Promise(r => setTimeout(r, delay));
+    }
   }
-  await client.logout();
-  return envelopes;
+  throw lastErr;
 }
 
-async function copyChunk(sourceMailbox, targetMailbox, uids) {
-  const client = createClient();
-  await client.connect();
-  await client.mailboxOpen(sourceMailbox);
-  await client.messageCopy(uids, targetMailbox, { uid: true });
-  await client.logout();
+// ─── Per-operation timeouts ───────────────────────────────────────────────────
+
+const TIMEOUT = {
+  METADATA: 15_000,
+  FETCH:    30_000,
+  SCAN:     60_000,
+  BULK_OP:  60_000,
+  CHUNK:   300_000,
+  SINGLE:   15_000,
+};
+
+function withTimeout(label, ms, fn) {
+  let timer;
+  return Promise.race([
+    fn().finally(() => clearTimeout(timer)),
+    new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        process.stderr.write(`[timeout] ${label} timed out after ${ms / 1000}s\n`);
+        reject(new Error(`${label} timed out after ${ms / 1000}s`));
+      }, ms);
+    })
+  ]);
 }
 
-async function deleteChunk(sourceMailbox, uids) {
-  const client = createClient();
-  await client.connect();
-  await client.mailboxOpen(sourceMailbox);
-  await client.messageDelete(uids, { uid: true });
-  await client.logout();
+// ─── Move logging ─────────────────────────────────────────────────────────────
+
+function elapsed(startMs) {
+  return ((Date.now() - startMs) / 1000).toFixed(1) + 's';
 }
 
-async function verifyFingerprintsInTarget(targetMailbox, expectedFingerprints) {
-  const client = createClient();
-  await client.connect();
-  const mb = await client.mailboxOpen(targetMailbox);
-  const total = mb.exists;
+function moveLog(chunkIndex, msg) {
+  process.stderr.write(`[move] chunk ${chunkIndex}: ${msg}\n`);
+}
+
+// ─── Verification (v3: envelope scan first, Message-ID fallback) ──────────────
+// Strategy: one bulk FETCH of recent envelopes in the target is far faster than
+// N individual SEARCH commands. We use envelope scan as the primary check, then
+// only fall back to per-email Message-ID SEARCH for the few that didn't match
+// (which can happen if the envelope fingerprint differs slightly between source
+// and target, e.g. date normalization).
 
-  // Fetch recent envelopes from target — copies land at the end
-  const fetchCount = Math.min(total, expectedFingerprints.length * 2 + 500);
+async function verifyByEnvelopeScan(client, fingerprints, chunkIndex, knownTotal = null) {
+  if (fingerprints.length === 0) return { missing: [], found: 0 };
+
+  const t0 = Date.now();
+  const total = knownTotal ?? (await client.status(client.mailbox.path, { messages: true })).messages;
+  const fetchCount = Math.min(total, fingerprints.length + 150);
   const start = Math.max(1, total - fetchCount + 1);
   const range = `${start}:${total}`;
 
   const targetKeys = new Set();
+  let scanned = 0;
   for await (const msg of client.fetch(range, { envelope: true })) {
     const fp = buildFingerprint(msg);
     targetKeys.add(fingerprintToKey(fp));
+    scanned++;
   }
-  await client.logout();
 
   const missing = [];
-  for (const fp of expectedFingerprints) {
-    const key = fingerprintToKey(fp);
-    if (!targetKeys.has(key)) missing.push(fp);
+  for (const fp of fingerprints) {
+    if (!targetKeys.has(fingerprintToKey(fp))) missing.push(fp);
   }
 
-  return {
-    verified: missing.length === 0,
-    missing,
-    found: expectedFingerprints.length - missing.length,
-    expected: expectedFingerprints.length
-  };
+  moveLog(chunkIndex, `envelope scan: ${scanned} scanned, ${fingerprints.length - missing.length}/${fingerprints.length} matched (${elapsed(t0)})`);
+  return { missing, found: fingerprints.length - missing.length };
 }
 
-// ─── Transient error detection ────────────────────────────────────────────────
+async function verifyByMessageId(client, fingerprints, chunkIndex) {
+  if (fingerprints.length === 0) return { missing: [], verified: 0 };
 
-function isTransient(err) {
-  const msg = err.message ?? '';
-  return msg.includes('ECONNRESET') ||
-    msg.includes('ECONNREFUSED') ||
-    msg.includes('ETIMEDOUT') ||
-    msg.includes('EPIPE') ||
-    msg.includes('socket hang up') ||
-    msg.includes('Connection not available') ||
-    msg.includes('BAD') ||      // IMAP BAD response — often transient on Apple
-    msg.includes('NO ');        // IMAP NO response — often transient on Apple
-}
+  const t0 = Date.now();
+  const missing = [];
+  let verified = 0;
 
-async function withRetry(label, fn, maxAttempts = 3) {
-  let lastErr;
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      return await fn();
-    } catch (err) {
-      lastErr = err;
-      if (!isTransient(err) || attempt === maxAttempts) throw err;
-      const delay = attempt * 2000; // 2s, 4s backoff
-      process.stderr.write(`[retry] ${label} failed (attempt ${attempt}/${maxAttempts}): ${err.message} — retrying in ${delay}ms\n`);
-      await new Promise(r => setTimeout(r, delay));
+  for (const fp of fingerprints) {
+    if (!fp.messageId) {
+      // No Message-ID — can't verify this way, count as missing
+      missing.push(fp);
+      continue;
+    }
+    const uids = (await client.search({ header: ['Message-ID', fp.messageId] }, { uid: true })) ?? [];
+    if (uids.length === 0) {
+      missing.push(fp);
+    } else {
+      verified++;
+    }
+    // Progress logging every 25 emails
+    const checked = verified + missing.length;
+    if (checked % 25 === 0) {
+      moveLog(chunkIndex, `Message-ID fallback: ${checked}/${fingerprints.length} checked (${verified} found, ${missing.length} missing, ${elapsed(t0)})`);
     }
   }
-  throw lastErr;
+
+  moveLog(chunkIndex, `Message-ID fallback: ${verified}/${fingerprints.length} verified, ${missing.length} still missing (${elapsed(t0)})`);
+  return { missing, verified };
 }
 
-// ─── Safe Move ────────────────────────────────────────────────────────────────
+async function verifyInTarget(targetClient, fingerprints, chunkIndex, knownTotal = null) {
+  // Primary: fast envelope scan (one FETCH command)
+  const { missing: afterScan } = await verifyByEnvelopeScan(targetClient, fingerprints, chunkIndex, knownTotal);
+
+  if (afterScan.length === 0) {
+    return { verified: true, missing: [], found: fingerprints.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);
+  const noMessageId = afterScan.filter(fp => !fp.messageId);
+
+  if (withMessageId.length > 0) {
+    const { missing: stillMissing } = await verifyByMessageId(targetClient, withMessageId, chunkIndex);
+    const allMissing = [...stillMissing, ...noMessageId];
+    return {
+      verified: allMissing.length === 0,
+      missing: allMissing,
+      found: fingerprints.length - allMissing.length,
+      expected: fingerprints.length
+    };
+  }
+
+  // No Message-IDs to try — whatever envelope scan missed is truly missing
+  return {
+    verified: noMessageId.length === 0,
+    missing: noMessageId,
+    found: fingerprints.length - noMessageId.length,
+    expected: fingerprints.length
+  };
+}
+
+// ─── Safe Move (v3: connection reuse + envelope-first verify + logging) ───────
 
 async function safeMoveEmails(uids, sourceMailbox, targetMailbox) {
   const operation = startOperation(sourceMailbox, targetMailbox, uids);
   let totalMoved = 0;
   let totalFailed = 0;
+  const opStart = Date.now();
 
-  for (const chunk of operation.chunks) {
-    const chunkUids = chunk.uids;
-    let succeeded = false;
+  process.stderr.write(`[move] starting: ${uids.length} emails, ${operation.chunks.length} chunks, ${sourceMailbox} → ${targetMailbox}\n`);
 
-    // Try at full chunk size first, then smaller on verification failure
-    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 srcClient = await openClient(sourceMailbox);
+  let tgtClient = await openClient(targetMailbox);
 
-      let verificationFailed = false;
-
-      for (const subChunk of subChunks) {
-        // Step 1: fetch fingerprints from source and write to manifest
-        // before doing anything destructive — retries on transient errors
-        const envelopes = await withRetry(
-          `fetchEnvelopes chunk ${chunk.index}`,
-          () => fetchEnvelopes(sourceMailbox, subChunk)
-        );
-        const fingerprints = envelopes.map(buildFingerprint);
-
-        updateManifest((data) => {
-          const c = data.current.chunks[chunk.index];
-          c.fingerprints = [...c.fingerprints, ...fingerprints];
-          c.status = 'pending';
-        });
+  try {
+    for (const chunk of operation.chunks) {
+      const chunkUids = chunk.uids;
+      let succeeded = false;
+      const chunkStart = Date.now();
 
-        // Step 2: copy to target — retries on transient errors
-        await withRetry(
-          `copyChunk chunk ${chunk.index}`,
-          () => copyChunk(sourceMailbox, targetMailbox, subChunk)
-        );
-        updateChunk(chunk.index, { status: 'copied_not_verified', copiedAt: new Date().toISOString() });
-
-        // Step 3: verify by fetching envelopes from target — retries on transient errors
-        const verification = await withRetry(
-          `verifyFingerprints chunk ${chunk.index}`,
-          () => verifyFingerprintsInTarget(targetMailbox, fingerprints)
-        );
-        if (!verification.verified) {
-          verificationFailed = true;
+      moveLog(chunk.index, `starting (${chunkUids.length} emails)`);
+
+      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 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.`
+            };
+          }
+        }
+
+        if (!verificationFailed) {
+          succeeded = true;
           break;
         }
-        updateChunk(chunk.index, { status: 'verified_not_deleted', verifiedAt: new Date().toISOString() });
-
-        // Step 4: safe to delete from source — retries on transient errors
-        await withRetry(
-          `deleteChunk chunk ${chunk.index}`,
-          () => deleteChunk(sourceMailbox, subChunk)
-        );
-        totalMoved += subChunk.length;
-      }
 
-      if (!verificationFailed) {
-        succeeded = true;
-        break;
+        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.`
+          };
+        }
+
+        moveLog(chunk.index, `verification failed at chunk size ${attemptChunkSize}, retrying at ${CHUNK_SIZE_RETRY}`);
       }
 
-      if (attemptChunkSize === CHUNK_SIZE_RETRY) {
-        // Verification failed at both chunk sizes — stop and report, source untouched from here
-        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.`
-        };
+      if (succeeded) {
+        updateChunk(chunk.index, { status: 'complete', deletedAt: new Date().toISOString() });
+        moveLog(chunk.index, `COMPLETE (${elapsed(chunkStart)})`);
       }
     }
 
-    if (succeeded) {
-      updateChunk(chunk.index, { status: 'complete', deletedAt: new Date().toISOString() });
-    }
+    completeOperation();
+    process.stderr.write(`[move] COMPLETE: ${totalMoved}/${operation.totalUids} emails moved (${elapsed(opStart)})\n`);
+    return { status: 'complete', moved: totalMoved, total: operation.totalUids };
+  } finally {
+    await safeClose(srcClient);
+    await safeClose(tgtClient);
   }
-
-  completeOperation();
-  return { status: 'complete', moved: totalMoved, total: operation.totalUids };
 }
 
 // ─── Email Functions ──────────────────────────────────────────────────────────
@@ -551,18 +725,14 @@ async function bulkDeleteBySender(sender, mailbox = 'INBOX') {
   await client.connect();
   await client.mailboxOpen(mailbox);
   const uids = (await client.search({ from: sender }, { uid: true })) ?? [];
-  await client.logout();
-  if (uids.length === 0) return { deleted: 0 };
+  if (uids.length === 0) { await client.logout(); return { deleted: 0 }; }
   let deleted = 0;
   for (let i = 0; i < uids.length; i += CHUNK_SIZE) {
     const chunk = uids.slice(i, i + CHUNK_SIZE);
-    const dc = createClient();
-    await dc.connect();
-    await dc.mailboxOpen(mailbox);
-    await dc.messageDelete(chunk, { uid: true });
-    await dc.logout();
+    await client.messageDelete(chunk, { uid: true });
     deleted += chunk.length;
   }
+  await client.logout();
   return { deleted, sender };
 }
 
@@ -583,18 +753,14 @@ async function bulkDeleteBySubject(subject, mailbox = 'INBOX') {
   await client.connect();
   await client.mailboxOpen(mailbox);
   const uids = (await client.search({ subject }, { uid: true })) ?? [];
-  await client.logout();
-  if (uids.length === 0) return { deleted: 0 };
+  if (uids.length === 0) { await client.logout(); return { deleted: 0 }; }
   let deleted = 0;
   for (let i = 0; i < uids.length; i += CHUNK_SIZE) {
     const chunk = uids.slice(i, i + CHUNK_SIZE);
-    const dc = createClient();
-    await dc.connect();
-    await dc.mailboxOpen(mailbox);
-    await dc.messageDelete(chunk, { uid: true });
-    await dc.logout();
+    await client.messageDelete(chunk, { uid: true });
     deleted += chunk.length;
   }
+  await client.logout();
   return { deleted, subject };
 }
 
@@ -605,18 +771,14 @@ async function deleteOlderThan(days, mailbox = 'INBOX') {
   const date = new Date();
   date.setDate(date.getDate() - days);
   const uids = (await client.search({ before: date }, { uid: true })) ?? [];
-  await client.logout();
-  if (uids.length === 0) return { deleted: 0 };
+  if (uids.length === 0) { await client.logout(); return { deleted: 0 }; }
   let deleted = 0;
   for (let i = 0; i < uids.length; i += CHUNK_SIZE) {
     const chunk = uids.slice(i, i + CHUNK_SIZE);
-    const dc = createClient();
-    await dc.connect();
-    await dc.mailboxOpen(mailbox);
-    await dc.messageDelete(chunk, { uid: true });
-    await dc.logout();
+    await client.messageDelete(chunk, { uid: true });
     deleted += chunk.length;
   }
+  await client.logout();
   return { deleted, olderThan: date.toISOString() };
 }
 
@@ -895,14 +1057,16 @@ async function ensureMailbox(name) {
   await client.logout();
 }
 
-async function bulkMove(filters, targetMailbox, sourceMailbox = 'INBOX', dryRun = false) {
+async function bulkMove(filters, targetMailbox, sourceMailbox = 'INBOX', dryRun = false, limit = null) {
   const client = createClient();
   await client.connect();
   await client.mailboxOpen(sourceMailbox);
   const query = buildQuery(filters);
-  const uids = (await client.search(query, { uid: true })) ?? [];
+  let uids = (await client.search(query, { uid: true })) ?? [];
   await client.logout();
 
+  if (limit !== null) uids = uids.slice(0, limit);
+
   if (dryRun) {
     return { dryRun: true, wouldMove: uids.length, sourceMailbox, targetMailbox, filters };
   }
@@ -913,29 +1077,45 @@ async function bulkMove(filters, targetMailbox, sourceMailbox = 'INBOX', dryRun
   return { ...result, sourceMailbox, targetMailbox, filters };
 }
 
+// ─── IMPROVEMENT 3: bulk_delete now has per-chunk timeout ─────────────────────
+// Previously the chunk loop could run unbounded. Now each chunk gets a BULK_OP
+// timeout. If a single chunk hangs, we bail with a partial result instead of
+// hanging forever.
+
 async function bulkDelete(filters, sourceMailbox = 'INBOX', dryRun = false) {
   const client = createClient();
   await client.connect();
   await client.mailboxOpen(sourceMailbox);
   const query = buildQuery(filters);
   const uids = (await client.search(query, { uid: true })) ?? [];
-  await client.logout();
 
   if (dryRun) {
+    await client.logout();
     return { dryRun: true, wouldDelete: uids.length, sourceMailbox, filters };
   }
-  if (uids.length === 0) return { deleted: 0, sourceMailbox };
+  if (uids.length === 0) { await client.logout(); return { deleted: 0, sourceMailbox }; }
 
   let deleted = 0;
   for (let i = 0; i < uids.length; i += CHUNK_SIZE) {
     const chunk = uids.slice(i, i + CHUNK_SIZE);
-    const deleteClient = createClient();
-    await deleteClient.connect();
-    await deleteClient.mailboxOpen(sourceMailbox);
-    await deleteClient.messageDelete(chunk, { uid: true });
-    await deleteClient.logout();
-    deleted += chunk.length;
+    const chunkIndex = Math.floor(i / CHUNK_SIZE);
+    try {
+      await withTimeout(`bulk_delete chunk ${chunkIndex}`, TIMEOUT.BULK_OP, async () => {
+        await client.messageDelete(chunk, { uid: true });
+      });
+      deleted += chunk.length;
+    } catch (err) {
+      await safeClose(client);
+      return {
+        deleted,
+        failed: uids.length - deleted,
+        sourceMailbox,
+        filters,
+        error: `Chunk ${chunkIndex} failed: ${err.message}. ${deleted} deleted so far, ${uids.length - deleted} remaining.`
+      };
+    }
   }
+  await client.logout();
   return { deleted, sourceMailbox, filters };
 }
 
@@ -977,7 +1157,7 @@ function logClear() {
 
 async function main() {
   const server = new Server(
-    { name: 'icloud-mail', version: '1.4.1' },
+    { name: 'icloud-mail', version: '1.5.0' },
     { capabilities: { tools: {} } }
   );
 
@@ -1106,6 +1286,7 @@ async function main() {
             targetMailbox: { type: 'string', description: 'Destination mailbox path' },
             sourceMailbox: { type: 'string', description: 'Source mailbox (default INBOX)' },
             dryRun: { type: 'boolean', description: 'If true, preview what would be moved without actually moving' },
+            limit: { type: 'number', description: 'Maximum number of emails to move (default: all matching)' },
             ...filtersSchema
           },
           required: ['targetMailbox']
@@ -1113,7 +1294,7 @@ async function main() {
       },
       {
         name: 'bulk_delete',
-        description: 'Delete emails matching any combination of filters. Processes in chunks of 250 for reliability. Use dryRun: true to preview without making changes.',
+        description: 'Delete emails matching any combination of filters. Processes in chunks of 250 with per-chunk timeouts for reliability. Use dryRun: true to preview without making changes.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -1350,71 +1531,80 @@ async function main() {
     const { name, arguments: args } = request.params;
     try {
       let result;
+      // ── Metadata tier (15s) ──
       if (name === 'get_inbox_summary') {
-        result = await getInboxSummary(args.mailbox || 'INBOX');
+        result = await withTimeout('get_inbox_summary', TIMEOUT.METADATA, () => getInboxSummary(args.mailbox || 'INBOX'));
       } else if (name === 'get_mailbox_summary') {
-        result = await getMailboxSummary(args.mailbox);
-      } else if (name === 'get_top_senders') {
-        result = await getTopSenders(args.mailbox || 'INBOX', args.sampleSize || 500, args.maxResults || 20);
-      } else if (name === 'get_unread_senders') {
-        result = await getUnreadSenders(args.mailbox || 'INBOX', args.sampleSize || 500, args.maxResults || 20);
-      } else if (name === 'get_emails_by_sender') {
-        result = await getEmailsBySender(args.sender, args.mailbox || 'INBOX', args.limit || 10);
+        result = await withTimeout('get_mailbox_summary', TIMEOUT.METADATA, () => getMailboxSummary(args.mailbox));
+      } else if (name === 'count_emails') {
+        const { mailbox, ...filters } = args;
+        result = await withTimeout('count_emails', TIMEOUT.METADATA, () => countEmails(filters, mailbox || 'INBOX'));
+      } else if (name === 'list_mailboxes') {
+        result = await withTimeout('list_mailboxes', TIMEOUT.METADATA, () => listMailboxes());
+      } else if (name === 'create_mailbox') {
+        result = await withTimeout('create_mailbox', TIMEOUT.METADATA, () => createMailbox(args.name));
+      } else if (name === 'rename_mailbox') {
+        result = await renameMailbox(args.oldName, args.newName); // already has its own 15s timeout
+      } else if (name === 'delete_mailbox') {
+        result = await deleteMailbox(args.name); // already has its own 15s timeout
+      // ── Fetch tier (30s) ──
       } else if (name === 'read_inbox') {
-        result = await fetchEmails(args.mailbox || 'INBOX', args.limit || 10, args.onlyUnread || false, args.page || 1);
+        result = await withTimeout('read_inbox', TIMEOUT.FETCH, () => fetchEmails(args.mailbox || 'INBOX', args.limit || 10, args.onlyUnread || false, args.page || 1));
       } else if (name === 'get_email') {
-        result = await getEmailContent(args.uid, args.mailbox || 'INBOX');
+        result = await withTimeout('get_email', TIMEOUT.FETCH, () => getEmailContent(args.uid, args.mailbox || 'INBOX'));
       } else if (name === 'search_emails') {
         const { query, mailbox, limit, ...filters } = args;
-        result = await searchEmails(query, mailbox || 'INBOX', limit || 10, filters);
-      } else if (name === 'count_emails') {
-        const { mailbox, ...filters } = args;
-        result = await countEmails(filters, mailbox || 'INBOX');
-      } else if (name === 'bulk_move') {
-        const { targetMailbox, sourceMailbox, dryRun, ...filters } = args;
-        result = await bulkMove(filters, targetMailbox, sourceMailbox || 'INBOX', dryRun || false);
-      } else if (name === 'bulk_delete') {
-        const { sourceMailbox, dryRun, ...filters } = args;
-        result = await bulkDelete(filters, sourceMailbox || 'INBOX', dryRun || false);
-      } else if (name === 'bulk_flag') {
-        const { flagged, mailbox, ...filters } = args;
-        result = await bulkFlag(filters, flagged, mailbox || 'INBOX');
+        result = await withTimeout('search_emails', TIMEOUT.FETCH, () => searchEmails(query, mailbox || 'INBOX', limit || 10, filters));
+      } else if (name === 'get_emails_by_sender') {
+        result = await withTimeout('get_emails_by_sender', TIMEOUT.FETCH, () => getEmailsBySender(args.sender, args.mailbox || 'INBOX', args.limit || 10));
+      } else if (name === 'get_emails_by_date_range') {
+        result = await withTimeout('get_emails_by_date_range', TIMEOUT.FETCH, () => getEmailsByDateRange(args.startDate, args.endDate, args.mailbox || 'INBOX', args.limit || 10));
+      // ── Scan tier (60s) ──
+      } else if (name === 'get_top_senders') {
+        result = await withTimeout('get_top_senders', TIMEOUT.SCAN, () => getTopSenders(args.mailbox || 'INBOX', args.sampleSize || 500, args.maxResults || 20));
+      } else if (name === 'get_unread_senders') {
+        result = await withTimeout('get_unread_senders', TIMEOUT.SCAN, () => getUnreadSenders(args.mailbox || 'INBOX', args.sampleSize || 500, args.maxResults || 20));
+      // ── Bulk operation tier (60s) ──
       } else if (name === 'bulk_delete_by_sender') {
-        result = await bulkDeleteBySender(args.sender, args.mailbox || 'INBOX');
-      } else if (name === 'bulk_move_by_sender') {
-        result = await bulkMoveBySender(args.sender, args.targetMailbox, args.sourceMailbox || 'INBOX');
+        result = await withTimeout('bulk_delete_by_sender', TIMEOUT.BULK_OP, () => bulkDeleteBySender(args.sender, args.mailbox || 'INBOX'));
       } else if (name === 'bulk_delete_by_subject') {
-        result = await bulkDeleteBySubject(args.subject, args.mailbox || 'INBOX');
+        result = await withTimeout('bulk_delete_by_subject', TIMEOUT.BULK_OP, () => bulkDeleteBySubject(args.subject, args.mailbox || 'INBOX'));
       } else if (name === 'bulk_mark_read') {
-        result = await bulkMarkRead(args.mailbox || 'INBOX', args.sender || null);
+        result = await withTimeout('bulk_mark_read', TIMEOUT.BULK_OP, () => bulkMarkRead(args.mailbox || 'INBOX', args.sender || null));
       } else if (name === 'bulk_mark_unread') {
-        result = await bulkMarkUnread(args.mailbox || 'INBOX', args.sender || null);
+        result = await withTimeout('bulk_mark_unread', TIMEOUT.BULK_OP, () => bulkMarkUnread(args.mailbox || 'INBOX', args.sender || null));
+      } else if (name === 'bulk_flag') {
+        const { flagged, mailbox, ...filters } = args;
+        result = await withTimeout('bulk_flag', TIMEOUT.BULK_OP, () => bulkFlag(filters, flagged, mailbox || 'INBOX'));
       } else if (name === 'delete_older_than') {
-        result = await deleteOlderThan(args.days, args.mailbox || 'INBOX');
-      } else if (name === 'get_emails_by_date_range') {
-        result = await getEmailsByDateRange(args.startDate, args.endDate, args.mailbox || 'INBOX', args.limit || 10);
+        result = await withTimeout('delete_older_than', TIMEOUT.BULK_OP, () => deleteOlderThan(args.days, args.mailbox || 'INBOX'));
+      } else if (name === 'empty_trash') {
+        result = await withTimeout('empty_trash', TIMEOUT.BULK_OP, () => emptyTrash());
+      // ── No top-level timeout — chunked with internal timeouts ──
+      } else if (name === 'bulk_move') {
+        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');
+      } else if (name === 'bulk_delete') {
+        // IMPROVEMENT 3: bulk_delete now has per-chunk timeouts internally
+        const { sourceMailbox, dryRun, ...filters } = args;
+        result = await bulkDelete(filters, sourceMailbox || 'INBOX', dryRun || false);
+      // ── Single-email tier (15s) ──
       } else if (name === 'flag_email') {
-        result = await flagEmail(args.uid, args.flagged, args.mailbox || 'INBOX');
+        result = await withTimeout('flag_email', TIMEOUT.SINGLE, () => flagEmail(args.uid, args.flagged, args.mailbox || 'INBOX'));
       } else if (name === 'mark_as_read') {
-        result = await markAsRead(args.uid, args.seen, args.mailbox || 'INBOX');
+        result = await withTimeout('mark_as_read', TIMEOUT.SINGLE, () => markAsRead(args.uid, args.seen, args.mailbox || 'INBOX'));
       } else if (name === 'delete_email') {
-        result = await deleteEmail(args.uid, args.mailbox || 'INBOX');
+        result = await withTimeout('delete_email', TIMEOUT.SINGLE, () => deleteEmail(args.uid, args.mailbox || 'INBOX'));
       } else if (name === 'move_email') {
-        result = await moveEmail(args.uid, args.targetMailbox, args.sourceMailbox || 'INBOX');
-      } else if (name === 'list_mailboxes') {
-        result = await listMailboxes();
-      } else if (name === 'create_mailbox') {
-        result = await createMailbox(args.name);
-      } else if (name === 'rename_mailbox') {
-        result = await renameMailbox(args.oldName, args.newName);
-      } else if (name === 'delete_mailbox') {
-        result = await deleteMailbox(args.name);
-      } else if (name === 'empty_trash') {
-        result = await emptyTrash();
+        result = await withTimeout('move_email', TIMEOUT.SINGLE, () => moveEmail(args.uid, args.targetMailbox, args.sourceMailbox || 'INBOX'));
+      // ── Move status (synchronous, no timeout needed) ──
       } else if (name === 'get_move_status') {
         result = getMoveStatus();
       } else if (name === 'abandon_move') {
         result = abandonMove();
+      // ── Session log (synchronous, no timeout needed) ──
       } else if (name === 'log_write') {
         result = logWrite(args.step);
       } else if (name === 'log_read') {
@@ -1426,7 +1616,7 @@ async function main() {
       }
       return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     } catch (error) {
-      return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true };
+      return { content: [{ type: 'text', text: `Error: ${friendlyError(error)}` }], isError: true };
     }
   });
 
@@ -1435,6 +1625,140 @@ async function main() {
   process.stderr.write('iCloud Mail MCP Server running\n');
 }
 
+// ─── Friendly error messages ──────────────────────────────────────────────────
+
+function friendlyError(err) {
+  const msg = err.message ?? '';
+
+  if (msg.includes('AUTHENTICATIONFAILED') || msg.includes('Invalid credentials') || msg.includes('Authentication failed')) {
+    return [
+      'Authentication failed.',
+      '→ Make sure IMAP_PASSWORD is an app-specific password, not your regular iCloud password.',
+      '→ Generate one at: appleid.apple.com → Sign-In and Security → App-Specific Passwords',
+      '→ Also check that IMAP_USER is your full iCloud email address (e.g. you@icloud.com)'
+    ].join('\n');
+  }
+
+  if (msg.includes('ECONNREFUSED') || msg.includes('ENOTFOUND') || msg.includes('ENETUNREACH')) {
+    return [
+      'Could not reach imap.mail.me.com:993.',
+      '→ Check your internet connection.',
+      '→ If you are behind a firewall or VPN, port 993 may be blocked.'
+    ].join('\n');
+  }
+
+  if (msg.includes('ETIMEDOUT') || msg.includes('socket hang up')) {
+    return [
+      'Connection to iCloud timed out.',
+      '→ Check your internet connection and try again.',
+      '→ iCloud IMAP can be slow under load — this is usually transient.'
+    ].join('\n');
+  }
+
+  if (msg.includes('ECONNRESET')) {
+    return [
+      'iCloud closed the connection unexpectedly.',
+      '→ This is usually transient. Try again in a few seconds.'
+    ].join('\n');
+  }
+
+  if (msg.includes('timed out after')) {
+    return [
+      `Operation ${msg}`,
+      '→ This usually means iCloud is slow or the operation is larger than expected.',
+      '→ Try again — if it persists, the operation may need to be broken into smaller steps.'
+    ].join('\n');
+  }
+
+  if (msg.includes('Mailbox does not exist') || msg.includes('does not exist') || msg.includes('NONEXISTENT')) {
+    return [
+      `Mailbox not found: ${msg}`,
+      '→ Check the folder name is correct — iCloud folder names are case-sensitive.',
+      '→ Use list_mailboxes to see all available folders.'
+    ].join('\n');
+  }
+
+  // Fall through — return original message
+  return msg;
+}
+
+// ─── Doctor command ───────────────────────────────────────────────────────────
+
+async function runDoctor() {
+  const divider = '─'.repeat(45);
+  process.stdout.write(`\nicloud-mcp doctor\n${divider}\n`);
+
+  const checks = [
+    {
+      label: 'IMAP_USER is set',
+      run: () => {
+        if (!IMAP_USER) throw new Error('IMAP_USER environment variable is not set.\n→ Add it to your Claude Desktop config env block.');
+      }
+    },
+    {
+      label: 'IMAP_PASSWORD is set',
+      run: () => {
+        if (!IMAP_PASSWORD) throw new Error('IMAP_PASSWORD environment variable is not set.\n→ Add it to your Claude Desktop config env block.');
+      }
+    },
+    {
+      label: 'IMAP_USER looks like an email address',
+      run: () => {
+        if (!IMAP_USER?.includes('@')) throw new Error(`IMAP_USER "${IMAP_USER}" doesn't look like an email address.\n→ Use your full iCloud address, e.g. you@icloud.com`);
+      }
+    },
+    {
+      label: `Connected to imap.mail.me.com:993`,
+      run: async () => {
+        const client = createClient();
+        await client.connect();
+        await client.logout();
+      }
+    },
+    {
+      label: `Authenticated as ${IMAP_USER}`,
+      run: async () => {
+        // Auth is validated as part of connect — if we reach here it passed.
+        // This check exists to give a clearer label in the output.
+      }
+    },
+    {
+      label: 'INBOX opened',
+      run: async () => {
+        const client = createClient();
+        await client.connect();
+        const mb = await client.mailboxOpen('INBOX');
+        await client.logout();
+        return `${mb.exists.toLocaleString()} messages`;
+      }
+    }
+  ];
+
+  let allPassed = true;
+
+  for (const check of checks) {
+    try {
+      const detail = await check.run();
+      const suffix = detail ? ` (${detail})` : '';
+      process.stdout.write(`✅ ${check.label}${suffix}\n`);
+    } catch (err) {
+      process.stdout.write(`❌ ${check.label}\n   ${friendlyError(err).replace(/\n/g, '\n   ')}\n`);
+      allPassed = false;
+      break; // No point continuing after a failure
+    }
+  }
+
+  process.stdout.write(`${divider}\n`);
+  if (allPassed) {
+    process.stdout.write('All checks passed. Ready to use with Claude Desktop.\n\n');
+    process.exit(0);
+  } else {
+    process.stdout.write('Setup is not complete. Fix the issue above and run --doctor again.\n\n');
+    process.exit(1);
+  }
+}
+
+
 process.on('uncaughtException', (err) => {
   process.stderr.write(`Uncaught exception: ${err.message}\n${err.stack}\n`);
   process.exit(1);
@@ -1445,7 +1769,14 @@ process.on('unhandledRejection', (reason) => {
   process.exit(1);
 });
 
-main().catch((err) => {
-  process.stderr.write(`Fatal error: ${err.message}\n${err.stack}\n`);
-  process.exit(1);
-});
+if (process.argv.includes('--doctor')) {
+  runDoctor().catch((err) => {
+    process.stderr.write(`Doctor failed unexpectedly: ${err.message}\n`);
+    process.exit(1);
+  });
+} else {
+  main().catch((err) => {
+    process.stderr.write(`Fatal error: ${err.message}\n${err.stack}\n`);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icloud-mcp",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "A Model Context Protocol (MCP) server for iCloud Mail",
   "main": "index.js",
   "bin": {

package/test.js

@@ -13,15 +13,20 @@ if (!IMAP_USER || !IMAP_PASSWORD) {
 }
 
 const projectDir = fileURLToPath(new URL('.', import.meta.url));
+const VERBOSE = process.argv.includes('--verbose') || process.argv.includes('-v');
 
 // Timeout in ms per tool category
 const TIMEOUTS = {
   mailbox_mgmt: 60000,   // create/rename/delete mailbox — can be slow on iCloud
+  bulk_move: 900000,     // pre-flight restore may have many stranded emails; test moves use limit:50
   default: 300000        // everything else — allow up to 5 min for large operations
 };
 
 const MAILBOX_MGMT_TOOLS = new Set(['create_mailbox', 'rename_mailbox', 'delete_mailbox']);
 
+// Tools whose stderr output is always interesting (move pipeline logging)
+const ALWAYS_LOG_STDERR = new Set(['bulk_move', 'bulk_move_by_sender']);
+
 function callToolRaw(name, args = {}, timeout = TIMEOUTS.default) {
   const messages = [
     { jsonrpc: '2.0', id: 0, method: 'initialize', params: { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'test', version: '1.0.0' } } },
@@ -45,8 +50,22 @@ function callToolRaw(name, args = {}, timeout = TIMEOUTS.default) {
       }
     );
 
+    // Capture stderr for logging
+    const stderr = (result.stderr || '').trim();
+
+    // Print stderr for move operations (always) or all tools (verbose mode)
+    if (stderr && (VERBOSE || ALWAYS_LOG_STDERR.has(name))) {
+      const lines = stderr.split('\n');
+      for (const line of lines) {
+        // Only print [move], [timeout], [retry] lines — skip noise
+        if (VERBOSE || /^\[(move|timeout|retry)\]/.test(line)) {
+          console.log(`     ${line}`);
+        }
+      }
+    }
+
     if (result.error) throw new Error(`Spawn error: ${result.error.message}`);
-    if (result.status !== 0) throw new Error(`Process exited with code ${result.status}: ${result.stderr}`);
+    if (result.status !== 0) throw new Error(`Process exited with code ${result.status}: ${stderr}`);
 
     const lines = (result.stdout || '').trim().split('\n').filter(l => l.trim().startsWith('{'));
     const responses = lines.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
@@ -54,7 +73,19 @@ function callToolRaw(name, args = {}, timeout = TIMEOUTS.default) {
     if (!toolResponse) throw new Error(`No response for tool: ${name}`);
     const content = toolResponse.result?.content?.[0]?.text;
     if (!content) throw new Error(`No content in response for: ${name}`);
-    if (toolResponse.result?.isError) throw new Error(`Tool error: ${content}`);
+    if (toolResponse.result?.isError) {
+      // On tool errors, always show stderr for diagnostics
+      if (stderr && !VERBOSE && !ALWAYS_LOG_STDERR.has(name)) {
+        const stderrLines = stderr.split('\n').filter(l => /^\[(move|timeout|retry)\]/.test(l));
+        if (stderrLines.length > 0) {
+          console.log(`\n     📋 stderr diagnostics:`);
+          for (const line of stderrLines) {
+            console.log(`     ${line}`);
+          }
+        }
+      }
+      throw new Error(`Tool error: ${content}`);
+    }
     return JSON.parse(content);
   } finally {
     try { unlinkSync(tmpFile); } catch {}
@@ -62,18 +93,24 @@ function callToolRaw(name, args = {}, timeout = TIMEOUTS.default) {
 }
 
 function callTool(name, args = {}) {
-  const timeout = MAILBOX_MGMT_TOOLS.has(name) ? TIMEOUTS.mailbox_mgmt : TIMEOUTS.default;
+  let timeout = TIMEOUTS.default;
+  if (MAILBOX_MGMT_TOOLS.has(name)) timeout = TIMEOUTS.mailbox_mgmt;
+  else if (name === 'bulk_move' || name === 'bulk_move_by_sender') timeout = TIMEOUTS.bulk_move;
+
   try {
     return callToolRaw(name, args, timeout);
   } catch (err) {
     // Only retry on spawn-level transient errors (ECONNRESET, ETIMEDOUT on the
     // child process itself) — NOT on Tool errors, which are application-level
     // failures that should propagate immediately.
+    // Never retry bulk_move: a timed-out move leaves the manifest in_progress,
+    // so a retry would immediately fail with a manifest conflict.
+    const isBulkMove = name === 'bulk_move' || name === 'bulk_move_by_sender';
     const isSpawnTransient = (
       err.message.includes('ECONNRESET') ||
       err.message.includes('ETIMEDOUT')
     ) && !err.message.startsWith('Tool error:');
-    if (isSpawnTransient) {
+    if (isSpawnTransient && !isBulkMove) {
       console.log(`\n     ⚠️  transient spawn error (${err.message.split(':')[0]}), retrying...`);
       return callToolRaw(name, args, timeout);
     }
@@ -100,7 +137,8 @@ function assert(condition, message) {
   if (!condition) throw new Error(message);
 }
 
-console.log('\n🧪 iCloud MCP Server Tests v1.6.0\n');
+console.log('\n🧪 iCloud MCP Server Tests v1.5.0\n');
+if (VERBOSE) console.log('🔊 Verbose mode: showing all stderr output\n');
 
 // ─── Pre-flight cleanup ───────────────────────────────────────────────────────
 // Abandon any leftover in-progress manifest from a previous crashed run,
@@ -408,57 +446,61 @@ test('abandon_move (nothing to abandon)', () => {
 });
 
 // ─── Safe Move (live) ─────────────────────────────────────────────────────────
-console.log('\n🔐 Safe Move Test (live — newsletters ↔ test)');
+// Uses limit:50 to keep the test fast and deterministic. Moving the full
+// newsletters folder (5000+ emails) is too slow for a test suite — IMAP EXPUNGE
+// scales with mailbox size, taking 60-160s per chunk on large folders.
+// 50 emails completes in ~15-30s total and tests all the same code paths:
+// fingerprinting, envelope scan, Message-ID fallback, manifest, delete.
+console.log('\n🔐 Safe Move Test (live — newsletters ↔ test, 50-email sample)');
 
-test('bulk_move newsletters → test (fingerprint verified)', () => {
+const MOVE_SAMPLE = 50;
+
+test(`bulk_move newsletters → test (${MOVE_SAMPLE} emails, fingerprint verified)`, () => {
   const beforeSource = callTool('count_emails', { mailbox: 'newsletters' });
-  assert(beforeSource.count > 0, 'newsletters should have emails');
-  console.log(`\n     → newsletters before: ${beforeSource.count}`);
+  assert(beforeSource.count >= MOVE_SAMPLE, `newsletters needs at least ${MOVE_SAMPLE} emails, has ${beforeSource.count}`);
+  console.log(`\n     → newsletters before: ${beforeSource.count} (moving ${MOVE_SAMPLE})`);
 
-  const moveResult = callTool('bulk_move', { sourceMailbox: 'newsletters', targetMailbox: 'test' });
+  const moveResult = callTool('bulk_move', { sourceMailbox: 'newsletters', targetMailbox: 'test', limit: MOVE_SAMPLE });
   console.log(`\n     → status: ${moveResult.status}, moved: ${moveResult.moved} of ${moveResult.total}`);
   assert(moveResult.status === 'complete', `expected complete, got ${moveResult.status}: ${moveResult.message || ''}`);
-  assert(moveResult.moved === beforeSource.count, `moved ${moveResult.moved} but expected ${beforeSource.count}`);
-  assert(moveResult.total === beforeSource.count, `total ${moveResult.total} should match source count ${beforeSource.count}`);
+  assert(moveResult.moved === MOVE_SAMPLE, `moved ${moveResult.moved} but expected ${MOVE_SAMPLE}`);
+  assert(moveResult.total === MOVE_SAMPLE, `total ${moveResult.total} should match limit ${MOVE_SAMPLE}`);
 
   const afterSource = callTool('count_emails', { mailbox: 'newsletters' });
-  console.log(`\n     → newsletters after (should be 0): ${afterSource.count}`);
-  assert(afterSource.count === 0, `newsletters should be empty, has ${afterSource.count}`);
+  console.log(`\n     → newsletters after: ${afterSource.count} (was ${beforeSource.count})`);
+  assert(afterSource.count === beforeSource.count - MOVE_SAMPLE, `newsletters should have ${beforeSource.count - MOVE_SAMPLE}, has ${afterSource.count}`);
 
   const afterTarget = callTool('count_emails', { mailbox: 'test' });
   console.log(`\n     → test folder after: ${afterTarget.count}`);
-  assert(afterTarget.count === beforeSource.count, `test should have ${beforeSource.count}, has ${afterTarget.count}`);
+  assert(afterTarget.count === MOVE_SAMPLE, `test should have ${MOVE_SAMPLE}, has ${afterTarget.count}`);
 });
 
 test('get_move_status (after completed move)', () => {
   const result = callTool('get_move_status');
-  // Current should be null (archived after completion), history should have the move
   assert(result.status === 'no_operation', `expected no_operation after completed move, got ${result.status}`);
   assert(result.history.length > 0, 'history should have at least one entry');
   const last = result.history[0];
   assert(last.status === 'complete', `last operation should be complete, got ${last.status}`);
   assert(last.source === 'newsletters', `source should be newsletters, got ${last.source}`);
   assert(last.target === 'test', `target should be test, got ${last.target}`);
+  assert(last.moved === MOVE_SAMPLE, `last op should have moved ${MOVE_SAMPLE}, got ${last.moved}`);
   console.log(`\n     → last op: ${last.status}, ${last.moved}/${last.total} moved from ${last.source} → ${last.target}`);
 });
 
-test('bulk_move test → newsletters (restore, fingerprint verified)', () => {
+test(`bulk_move test → newsletters (restore ${MOVE_SAMPLE} emails, fingerprint verified)`, () => {
   const beforeSource = callTool('count_emails', { mailbox: 'test' });
-  assert(beforeSource.count > 0, 'test folder should have emails to restore');
+  assert(beforeSource.count === MOVE_SAMPLE, `test should have ${MOVE_SAMPLE} emails, has ${beforeSource.count}`);
   console.log(`\n     → test before restore: ${beforeSource.count}`);
 
+  // No limit needed — test folder only has MOVE_SAMPLE emails; small folder = fast delete
   const moveBack = callTool('bulk_move', { sourceMailbox: 'test', targetMailbox: 'newsletters' });
   console.log(`\n     → status: ${moveBack.status}, moved: ${moveBack.moved} of ${moveBack.total}`);
   assert(moveBack.status === 'complete', `expected complete, got ${moveBack.status}: ${moveBack.message || ''}`);
-  assert(moveBack.moved === beforeSource.count, `moved ${moveBack.moved} but expected ${beforeSource.count}`);
+  assert(moveBack.moved === MOVE_SAMPLE, `moved ${moveBack.moved} but expected ${MOVE_SAMPLE}`);
 
   const afterSource = callTool('count_emails', { mailbox: 'test' });
   console.log(`\n     → test after (should be 0): ${afterSource.count}`);
   assert(afterSource.count === 0, `test should be empty, has ${afterSource.count}`);
-
-  const afterTarget = callTool('count_emails', { mailbox: 'newsletters' });
-  console.log(`\n     → newsletters restored: ${afterTarget.count}`);
-  assert(afterTarget.count === beforeSource.count, `newsletters should have ${beforeSource.count}, has ${afterTarget.count}`);
 });
 
 test('get_move_status (history has both moves)', () => {
@@ -470,8 +512,8 @@ test('get_move_status (history has both moves)', () => {
   assert(restore.source === 'test', `restore source should be test, got ${restore.source}`);
   assert(forward.status === 'complete', `forward op should be complete, got ${forward.status}`);
   assert(forward.source === 'newsletters', `forward source should be newsletters, got ${forward.source}`);
-  console.log(`\n     → history[0]: ${restore.source} → ${restore.target} (${restore.status})`);
-  console.log(`\n     → history[1]: ${forward.source} → ${forward.target} (${forward.status})`);
+  console.log(`\n     → history[0]: ${restore.source} → ${restore.target} (${restore.status}, ${restore.moved} emails)`);
+  console.log(`\n     → history[1]: ${forward.source} → ${forward.target} (${forward.status}, ${forward.moved} emails)`);
 });
 
 // ─── Session Log ─────────────────────────────────────────────────────────────
@@ -538,4 +580,4 @@ console.log(`\n✅ Passed: ${passed}`);
 console.log(`❌ Failed: ${failed}`);
 console.log(`📊 Total:  ${passed + failed}\n`);
 
-if (failed > 0) process.exit(1);
+if (failed > 0) process.exit(1);