@littlebearapps/outlook-assistant 3.10.0 → 3.11.1

package/.env.example

@@ -24,6 +24,13 @@ USE_TEST_MODE=false
 # Optional: Enable immutable IDs (IDs persist through folder moves)
 # OUTLOOK_IMMUTABLE_IDS=true
 
+# How many recent messages the client-side search fallback scans before giving
+# up. Personal Outlook.com rejects the server-side recipient filter, so a `to`
+# search is matched locally within this window — on a large archive the default
+# silently excludes older mail. Max 5000. Pair `to` with receivedAfter/
+# receivedBefore rather than raising this if you can.
+# OUTLOOK_SEARCH_SCAN_LIMIT=500
+
 # Optional: Default authentication method (device-code or browser)
 # device-code: No auth server needed, works remotely/headless
 # browser: Traditional OAuth redirect via localhost:3333

package/README.md

@@ -161,6 +161,17 @@ Or run directly without installing:
 npx @littlebearapps/outlook-assistant
 ```
 
+To check which version you have, or to see the available options:
+
+```bash
+outlook-assistant --version     # prints e.g. 3.11.1
+outlook-assistant --help        # usage, options and key environment variables
+```
+
+With no arguments the server speaks the Model Context Protocol over stdio. It's
+normally launched by your MCP client rather than run by hand — started from a
+terminal it will simply wait on stdin.
+
 ### 2. Register an Azure App
 
 You need a Microsoft Azure app registration to authenticate. See the **[Azure Setup Guide](docs/guides/azure-setup.md)** for a detailed walkthrough (including first-time Azure account creation), or if you've done this before:
@@ -278,6 +289,17 @@ cd outlook-assistant
 npm install
 ```
 
+### CLI options
+
+| Option | What it does |
+|--------|-------------|
+| `-v`, `--version` | Print the version to stdout and exit 0 |
+| `-h`, `--help` | Print usage, options and key environment variables, and exit 0 |
+| _(none)_ | Start the MCP server on stdio — the normal mode, invoked by your MCP client |
+
+An unrecognised argument is reported on stderr and exits 1, rather than starting
+a server that would ignore it.
+
 ## Azure App Registration
 
 > **First time with Azure?** The [Azure Setup Guide](docs/guides/azure-setup.md) covers everything from creating an account to your first authentication, including billing setup and common pitfalls.
@@ -344,6 +366,7 @@ USE_TEST_MODE=false
 | `OUTLOOK_DEFAULT_TIMEZONE` | IANA timezone applied to calendar events when callers don't pass one (e.g. `Europe/London`, `America/New_York`). | `Australia/Melbourne` |
 | `OUTLOOK_MAX_EMAILS_PER_SESSION` | Cap on `send-email` + `draft send` per MCP server lifetime. | unlimited |
 | `OUTLOOK_ALLOWED_RECIPIENTS` | Comma-separated allowlist of domains/addresses for sends, drafts, and rule forwards. | unrestricted |
+| `OUTLOOK_SEARCH_SCAN_LIMIT` | How many recent messages the client-side search fallback scans. Personal accounts match `to` locally within this window, so the default caps how far back a `to` search reaches. Max 5000. | `500` |
 
 ### MCP Client Configuration
 
@@ -446,7 +469,11 @@ npm run auth-server
 
 ### "Invalid client secret" (AADSTS7000215)
 
-You're using the Secret **ID** instead of the Secret **Value**. Go to Azure Portal > Certificates & secrets and copy the **Value** column.
+You're using the Secret **ID** instead of the Secret **Value**. Go to Azure Portal > Certificates & secrets and copy the **Value** column into `OUTLOOK_CLIENT_SECRET`.
+
+The Value is shown only once, when the secret is created — if you've navigated away it can't be read again, so create a new secret. An **expired** secret produces this same error, so check the Expires column too.
+
+Since v3.11.0 the server detects this error and appends the explanation to Microsoft's original message, so you see both the raw error code and what to do about it.
 
 ### Authentication URL doesn't work
 
@@ -497,7 +524,7 @@ USE_TEST_MODE=true npm start
 | [Getting Started](docs/how-to/getting-started/connect-outlook-to-claude.md) | Install, configure, and authenticate — start here |
 | [Azure Setup Guide](docs/guides/azure-setup.md) | Azure account creation, app registration, permissions, and secrets |
 | [How-To Guides](docs/how-to/index.md) | 29 practical guides for email, calendar, contacts, and settings |
-| [Roadmap](ROADMAP.md) | Active milestones (v3.7.5, v3.8.x, v3.11.0+) and recent releases |
+| [Roadmap](ROADMAP.md) | Active milestones (v3.11.2, v3.8.x, v3.12.0+) and recent releases |
 | [Troubleshooting & FAQ](docs/how-to/getting-started/verify-your-connection.md#common-connection-problems) | Common problems, re-authentication, and frequently asked questions |
 | [Tools Reference](docs/quickrefs/tools-reference.md) | All 22 tools with parameters |
 | [AI Agent Guide](docs/how-to/ai-agents/using-outlook-assistant-in-agents.md) | Tool selection and workflow patterns for AI agents |
@@ -506,7 +533,8 @@ Full documentation: [docs/](docs/README.md)
 
 ## Known Limitations
 
-- **Personal account search**: Free-text `query` and the raw `searchExpression` (formerly `kqlQuery`) rely on Microsoft's `$search` API, which has limited support on personal Outlook.com accounts. `query` mitigates this with progressive fallback (OData filters, boolean filters, then a client-side scan). Field-scoped `$search` (e.g. `subject:"…"`) is rejected outright there; since v3.10.0 `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried, but boolean operators, grouping, wildcards and other field prefixes are not — those still terminate with an explicit no-results rather than a silent broader search. Structured filters (`from`, `subject`, `to`, `receivedAfter`) remain the most direct route. Cross-folder search (`searchAllFolders: true`) returns a superset of inbox-only results.
+- **Personal account search**: Free-text `query` and the raw `searchExpression` (formerly `kqlQuery`) rely on Microsoft's `$search` API, which has limited support on personal Outlook.com accounts. `query` mitigates this with progressive fallback (OData filters, boolean filters, then a client-side scan). Field-scoped `$search` (e.g. `subject:"…"`) is rejected outright there; since v3.10.0 `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried, but boolean operators, grouping, wildcards and other field prefixes are not — those still terminate with an explicit no-results rather than a silent broader search. Structured filters (`from`, `subject`, `to`, `receivedAfter`) remain the most direct route. Cross-folder search (`searchAllFolders: true`) returns a superset of inbox-only results. Note that `query` and `searchExpression` are not interchangeable there: `searchExpression` goes to `$search`, which matches the whole message including the body and ranks by relevance rather than date, while `query` falls back to a subject substring match that never reads bodies.
+- **`to` search depth on personal accounts**: the server-side recipient filter is rejected, so `to` is matched locally over the 500 most recent messages (`OUTLOOK_SEARCH_SCAN_LIMIT`, max 5000). On a large archive that excludes older mail — pair `to` with `receivedAfter`/`receivedBefore`. Since v3.11.1 the response says so whenever the scan was truncated, whether or not it matched.
 - **Focused Inbox**: Only available on work/school Microsoft 365 accounts.
 - **Shared mailboxes**: Require `Mail.Read.Shared` permission and a work/school account.
 - **Meeting room search**: Requires `Place.Read.All` permission with admin consent (work/school accounts only).

package/auth/auth-errors.js

@@ -0,0 +1,89 @@
+/**
+ * Azure AD (AADSTS) error translation.
+ *
+ * Microsoft's identity platform returns accurate but unfriendly errors: the
+ * error_description is a wall of prose ending in a correlation ID, and the
+ * single most common setup mistake — pasting the client secret's *ID* instead
+ * of its *Value* — surfaces only as `AADSTS7000215: Invalid client secret
+ * provided`. (#69)
+ *
+ * This module maps known codes to actionable remediation text. It only ever
+ * *adds* to the original message; the raw Azure error is always preserved so
+ * that searching for the code still works.
+ */
+
+/**
+ * Known Azure error signatures and their remediation hints.
+ * Ordered most-specific first; every matching entry contributes a hint.
+ */
+const AUTH_ERROR_HINTS = [
+  {
+    // The Secret ID vs Secret Value mistake. First row of docs/troubleshooting.md.
+    test: /AADSTS7000215/i,
+    hint:
+      'Invalid client secret. The usual cause is pasting the **Secret ID** (a UUID like `a1b2c3d4-…`) instead of the **Secret Value** (a longer string with mixed case and symbols). ' +
+      'In Azure → App registrations → your app → Certificates & secrets → Client secrets, copy the *Value* column into `OUTLOOK_CLIENT_SECRET`. ' +
+      'The Secret Value is shown only once, when the secret is created — if you have navigated away it can no longer be read, so create a new secret. ' +
+      'An expired secret produces this same error, so check the Expires column too. ' +
+      'See docs/guides/azure-setup.md#4-create-a-client-secret.',
+  },
+  {
+    test: /AADSTS9002331|personal.*account/i,
+    hint: 'This app registration appears to accept personal Microsoft accounts only. Set `OUTLOOK_AUTH_AUDIENCE=consumers` (or the correct tenant GUID) in your MCP env and retry.',
+  },
+  {
+    test: /AADSTS7000218|unauthorized_client|invalid_client/i,
+    // AADSTS7000215 is also delivered as error=invalid_client, but it means the
+    // secret is wrong, not that public client flows are disabled. Suppress the
+    // generic hint so the specific one above is not drowned out.
+    notWhen: /AADSTS7000215/i,
+    hint: "Enable 'Allow public client flows' under Azure → App registration → Authentication → Advanced settings, and add the `nativeclient` redirect URI (Mobile and desktop applications platform).",
+  },
+  {
+    test: /AADSTS700016/i,
+    hint: 'The application was not found in this directory. Check `OUTLOOK_CLIENT_ID` matches the Application (client) ID in Azure, and that `OUTLOOK_AUTH_AUDIENCE` targets the right tenant.',
+  },
+  {
+    test: /invalid_grant|AADSTS700082|AADSTS50173/i,
+    hint: 'The refresh token is expired or has been revoked (refresh tokens last ~90 days). Re-authenticate with the `auth` tool: `action=authenticate`, then `action=device-code-complete`.',
+  },
+];
+
+/** Normalise an Error or string into a searchable message. */
+function toMessage(input) {
+  if (input === null || input === undefined) return '';
+  if (input instanceof Error) return input.message || String(input);
+  if (typeof input === 'object' && input.message) return String(input.message);
+  return String(input);
+}
+
+/**
+ * Return remediation hints for a Microsoft auth error.
+ * @param {Error|string|null|undefined} input - Error or error_description
+ * @returns {string[]} - Zero or more hints; empty when the error is unknown
+ */
+function getAuthErrorHints(input) {
+  const msg = toMessage(input);
+  if (!msg) return [];
+  return AUTH_ERROR_HINTS.filter(
+    (e) => e.test.test(msg) && !(e.notWhen && e.notWhen.test(msg))
+  ).map((e) => e.hint);
+}
+
+/**
+ * Append any known remediation hints to an auth error message.
+ * Returns the message unchanged when nothing is known, so callers can use this
+ * unconditionally without polluting unrelated errors.
+ * @param {Error|string} input
+ * @returns {string}
+ */
+function describeAuthError(input) {
+  const msg = toMessage(input);
+  const hints = getAuthErrorHints(msg);
+  if (!hints.length) return msg;
+  return [msg, '', 'Suggested fixes:', ...hints.map((h) => `- ${h}`)].join(
+    '\n'
+  );
+}
+
+module.exports = { getAuthErrorHints, describeAuthError, AUTH_ERROR_HINTS };

package/auth/oauth-server.js

@@ -38,7 +38,8 @@ const templates = {
       <body style="font-family: Arial, sans-serif; text-align: center; margin-top: 50px;">
         <h1 style="color: #e74c3c;">❌ Token Exchange Failed</h1>
         <p>Failed to exchange authorization code for access token.</p>
-        <p><strong>Error:</strong> ${escapeHtml(error instanceof Error ? error.message : String(error))}</p>
+        <p><strong>Error:</strong></p>
+        <pre style="white-space: pre-wrap; text-align: left; display: inline-block; max-width: 40em; font-family: inherit;">${escapeHtml(error instanceof Error ? error.message : String(error))}</pre>
         <p>You can close this window and try again.</p>
       </body>
     </html>`,
@@ -227,7 +228,7 @@ function setupOAuthRoutes(
 module.exports = {
   setupOAuthRoutes,
   createAuthConfig,
-  // Exporting templates for potential direct use or testing, though not typical
-  // templates
+  // Exported so the rendered error pages can be asserted on directly (#69).
+  templates,
 };
 // Adding a newline at the end of the file as requested by Gemini Code Assist

package/auth/token-storage.js

@@ -3,6 +3,7 @@ const fsSync = require('fs');
 const path = require('path');
 const https = require('https');
 const querystring = require('querystring');
+const { describeAuthError } = require('./auth-errors');
 
 class TokenStorage {
   constructor(config) {
@@ -131,16 +132,22 @@ class TokenStorage {
           return await this.refreshAccessToken();
         } catch (refreshError) {
           console.error('Failed to refresh access token:', refreshError);
-          this.tokens = null; // Invalidate tokens on refresh failure
-          await this._saveTokensToFile(); // Persist invalidation
+          // Drop the in-memory tokens so callers re-authenticate. The save
+          // below is intentionally a no-op — `_saveTokensToFile` returns early
+          // when `tokens` is null — which is the behaviour we want: a transient
+          // network failure must not erase a still-valid refresh token from
+          // disk. The next process start reloads it and retries. (#72)
+          this.tokens = null;
+          await this._saveTokensToFile();
           return null;
         }
       } else {
         console.warn(
           'No refresh token available. Cannot refresh access token.'
         );
-        this.tokens = null; // Invalidate tokens as they are expired and cannot be refreshed
-        await this._saveTokensToFile(); // Persist invalidation
+        // Same as above: clears memory, leaves the file alone. (#72)
+        this.tokens = null;
+        await this._saveTokensToFile();
         return null;
       }
     }
@@ -226,8 +233,10 @@ class TokenStorage {
                 console.error('Error refreshing token:', responseBody);
                 reject(
                   new Error(
-                    responseBody.error_description ||
-                      `Token refresh failed with status ${res.statusCode}`
+                    describeAuthError(
+                      responseBody.error_description ||
+                        `Token refresh failed with status ${res.statusCode}`
+                    )
                   )
                 );
               }
@@ -320,8 +329,10 @@ class TokenStorage {
                 );
                 reject(
                   new Error(
-                    responseBody.error_description ||
-                      `Token exchange failed with status ${res.statusCode}`
+                    describeAuthError(
+                      responseBody.error_description ||
+                        `Token exchange failed with status ${res.statusCode}`
+                    )
                   )
                 );
               }

package/auth/tools.js

@@ -2,6 +2,7 @@
  * Authentication-related tools for the Outlook Assistant server
  */
 const config = require('../config');
+const { getAuthErrorHints } = require('./auth-errors');
 const fs = require('fs');
 const path = require('path');
 const tokenManager = require('./token-manager');
@@ -264,20 +265,10 @@ async function handleDeviceCodeAuth() {
 function buildDeviceCodeErrorResponse(error) {
   const msg = (error && error.message) || String(error);
   const code = error && error.code;
-  const hints = [];
+  // Shared AADSTS hint table (#69) so this path and the token-endpoint paths in
+  // token-storage.js cannot drift apart.
+  const hints = getAuthErrorHints(msg);
 
-  if (/AADSTS9002331/i.test(msg) || /personal.*account/i.test(msg)) {
-    hints.push(
-      'This app registration appears to accept personal Microsoft accounts only. Set `OUTLOOK_AUTH_AUDIENCE=consumers` (or the correct tenant GUID) in your MCP env and retry.'
-    );
-  }
-  if (
-    /invalid_client|unauthorized_client|AADSTS7000218|AADSTS700016/i.test(msg)
-  ) {
-    hints.push(
-      "Enable 'Allow public client flows' under Azure → App registration → Authentication → Advanced settings, and add the `nativeclient` redirect URI (Mobile and desktop applications platform)."
-    );
-  }
   if (
     code === 'ENOTFOUND' ||
     code === 'ETIMEDOUT' ||

package/email/export.js

@@ -78,26 +78,32 @@ async function handleExportEmail(args) {
       };
     }
 
-    // Generate filename based on email metadata
-    const timestamp = new Date(email.receivedDateTime)
-      .toISOString()
-      .slice(0, 10);
+    // Generate filename based on email metadata. The time matters: a
+    // date-only name collides across any same-day reply chain, and the old
+    // behaviour was to overwrite silently.
+    const timestamp = filenameTimestamp(email.receivedDateTime);
     const safeSubject = sanitizeFilename(email.subject || 'no-subject');
     const extension = getExtension(format);
-    const defaultFilename = `${timestamp}_${safeSubject}.${extension}`;
+    const defaultBase = `${timestamp}_${safeSubject}`;
+
+    // Paths claimed while writing this message (main file + attachments).
+    const claimedPaths = new Set();
 
     // Determine final save path
     let finalPath;
-    if (savePath) {
-      // If savePath is a directory, append filename
-      if (fs.existsSync(savePath) && fs.statSync(savePath).isDirectory()) {
-        finalPath = path.join(savePath, defaultFilename);
-      } else {
-        finalPath = savePath;
-      }
+    if (
+      savePath &&
+      !(fs.existsSync(savePath) && fs.statSync(savePath).isDirectory())
+    ) {
+      // An explicit file path is the caller's to control — honour it exactly,
+      // including overwriting, since that is what an explicit path means.
+      finalPath = savePath;
     } else {
-      // Default to OS temp directory to avoid polluting the working directory
-      finalPath = path.join(os.tmpdir(), defaultFilename);
+      // A directory (or the default temp dir) means we choose the name, so
+      // never clobber a file that is already there.
+      const dir = savePath || os.tmpdir();
+      fs.mkdirSync(dir, { recursive: true });
+      finalPath = claimUniquePath(dir, defaultBase, extension, claimedPaths);
     }
 
     // Export based on format
@@ -152,7 +158,8 @@ async function handleExportEmail(args) {
       attachmentsSaved = await saveAttachments(
         accessToken,
         emailId,
-        path.dirname(finalPath)
+        path.dirname(finalPath),
+        claimedPaths
       );
     }
 
@@ -372,6 +379,21 @@ async function handleBatchExportEmails(args) {
     );
     resultText += `| Total Size | ${(totalBytes / 1024).toFixed(1)} KB |\n`;
 
+    // Requested id -> written path, so a caller can reconcile without
+    // listing the directory. A batch that silently lost messages to
+    // filename collisions still reported "Successful N / Failed 0", and the
+    // loss was only ever caught by counting distinct Message-IDs by hand.
+    const manifest = successful.map((r) => ({
+      emailId: r.emailId,
+      filePath: r.filePath,
+    }));
+    const disambiguated = manifest.filter((entry) =>
+      /_\d+\.[^.]+$/.test(entry.filePath)
+    );
+    if (disambiguated.length > 0) {
+      resultText += `\n> ${disambiguated.length} file name(s) were disambiguated with a numeric suffix — messages sharing a timestamp and subject, or names already present in the output directory. Nothing was overwritten.\n`;
+    }
+
     if (failed.length > 0) {
       resultText += `\n### Failed Exports\n\n`;
       for (const f of failed.slice(0, 10)) {
@@ -396,6 +418,7 @@ async function handleBatchExportEmails(args) {
         successful: successful.length,
         failed: failed.length,
         totalBytes: totalBytes,
+        manifest,
       },
     };
   } catch (error) {
@@ -488,6 +511,8 @@ async function exportWithConcurrency(
 ) {
   const results = [];
   const inProgress = new Set();
+  // Shared across the batch so concurrent exports cannot claim the same path.
+  const claimedPaths = new Set();
   let index = 0;
 
   while (index < emailIds.length || inProgress.size > 0) {
@@ -499,7 +524,8 @@ async function exportWithConcurrency(
         emailId,
         format,
         outputDir,
-        includeAttachments
+        includeAttachments,
+        claimedPaths
       ).then((result) => {
         inProgress.delete(promise);
         results.push(result);
@@ -526,7 +552,8 @@ async function exportSingleForBatch(
   emailId,
   format,
   outputDir,
-  includeAttachments
+  includeAttachments,
+  claimedPaths
 ) {
   try {
     const selectFields = getEmailFields('export');
@@ -538,13 +565,15 @@ async function exportSingleForBatch(
       { $select: selectFields }
     );
 
-    const timestamp = new Date(email.receivedDateTime)
-      .toISOString()
-      .slice(0, 10);
+    const timestamp = filenameTimestamp(email.receivedDateTime);
     const safeSubject = sanitizeFilename(email.subject || 'no-subject');
     const extension = getExtension(format);
-    const filename = `${timestamp}_${safeSubject}.${extension}`;
-    const filePath = path.join(outputDir, filename);
+    const filePath = claimUniquePath(
+      outputDir,
+      `${timestamp}_${safeSubject}`,
+      extension,
+      claimedPaths
+    );
 
     let content;
     if (format === EXPORT_FORMATS.MIME || format === EXPORT_FORMATS.EML) {
@@ -562,7 +591,12 @@ async function exportSingleForBatch(
     // Handle attachments if requested
     let attachmentCount = 0;
     if (includeAttachments && email.hasAttachments) {
-      const saved = await saveAttachments(accessToken, emailId, outputDir);
+      const saved = await saveAttachments(
+        accessToken,
+        emailId,
+        outputDir,
+        claimedPaths
+      );
       attachmentCount = saved.length;
     }
 
@@ -585,7 +619,7 @@ async function exportSingleForBatch(
 /**
  * Save email attachments to directory
  */
-async function saveAttachments(accessToken, emailId, outputDir) {
+async function saveAttachments(accessToken, emailId, outputDir, claimedPaths) {
   const saved = [];
 
   try {
@@ -602,9 +636,16 @@ async function saveAttachments(accessToken, emailId, outputDir) {
     for (const att of response.value) {
       if (att.contentBytes) {
         const safeFilename = sanitizeFilename(att.name || 'attachment');
-        const filePath = path.join(
+        // `emailId.substring(0, 8)` was not a disambiguator: Graph message ids
+        // within one mailbox share a long common prefix, so every message's
+        // `invoice.pdf` resolved to the same path and all but the last were
+        // overwritten. Claim a unique path instead.
+        const { base, extension } = splitExtension(safeFilename);
+        const filePath = claimUniquePath(
           outputDir,
-          `${emailId.substring(0, 8)}_${safeFilename}`
+          `${emailId.substring(0, 8)}_${base}`,
+          extension,
+          claimedPaths || new Set()
         );
         const buffer = Buffer.from(att.contentBytes, 'base64');
         fs.writeFileSync(filePath, buffer);
@@ -622,6 +663,63 @@ async function saveAttachments(accessToken, emailId, outputDir) {
   return saved;
 }
 
+/**
+ * Format a message timestamp for use in a filename.
+ *
+ * Date-only was the collision: a same-day reply chain is extremely common, and
+ * every message in it normalises to the same `<date>_<subject>` name. Keeping
+ * the time disambiguates the realistic case. Mirrors the sanitisation #82
+ * applied to the aggregated CSV name.
+ *
+ * @param {string} isoDateTime - Message receivedDateTime
+ * @returns {string} - e.g. `2023-06-15T01-26-00`
+ */
+function filenameTimestamp(isoDateTime) {
+  const parsed = new Date(isoDateTime);
+  if (Number.isNaN(parsed.getTime())) return 'undated';
+  return parsed.toISOString().slice(0, 19).replace(/[:.]/g, '-');
+}
+
+/**
+ * Claim a not-yet-used path in `outputDir`, appending `_2`, `_3`, ... until the
+ * name is free both on disk and among the paths already claimed in this batch.
+ *
+ * Silent overwrite is the dangerous part of the collision defect: the exporter
+ * reported `Successful N / Failed 0` while messages vanished. Never overwrite —
+ * disambiguate instead, and let the caller reconcile via the manifest.
+ *
+ * The claim is synchronous, so it is atomic with respect to the event loop and
+ * safe under the batch exporter's 4-way concurrency even though the write
+ * itself happens after an await.
+ *
+ * @param {string} outputDir - Target directory
+ * @param {string} base - Filename without extension
+ * @param {string} extension - Extension without a leading dot
+ * @param {Set<string>} claimed - Paths already claimed by this batch
+ * @returns {string} - An unused absolute path, now claimed
+ */
+function claimUniquePath(outputDir, base, extension, claimed) {
+  let candidate = path.join(outputDir, `${base}.${extension}`);
+  let suffix = 1;
+  while (claimed.has(candidate) || fs.existsSync(candidate)) {
+    suffix += 1;
+    candidate = path.join(outputDir, `${base}_${suffix}.${extension}`);
+  }
+  claimed.add(candidate);
+  return candidate;
+}
+
+/**
+ * Split a filename into base and extension for collision-safe claiming.
+ * @param {string} name - Sanitised filename, possibly with an extension
+ * @returns {{base: string, extension: string}}
+ */
+function splitExtension(name) {
+  const dot = name.lastIndexOf('.');
+  if (dot <= 0) return { base: name, extension: '' };
+  return { base: name.slice(0, dot), extension: name.slice(dot + 1) };
+}
+
 /**
  * Sanitize filename for filesystem
  */

package/email/index.js

@@ -68,12 +68,13 @@ const emailTools = [
         // Search/list params
         query: {
           type: 'string',
-          description: 'Search query text. Omit for list mode.',
+          description:
+            'Search query text. Omit for list mode. On personal Outlook.com accounts Graph `$search` is unavailable, so this falls back to a subject substring match (all words must appear in the subject) — precise, but it does NOT search message bodies. Use `searchExpression` when you need body content.',
         },
         searchExpression: {
           type: 'string',
           description:
-            'Raw Microsoft Graph `$search` expression for advanced server-side search, e.g. `subject:"invoice"`, `from:github.com`, or `foo OR bar`. Quote your own phrases; a single bare token is auto-quoted. Pair with `searchAllFolders: true` for cross-folder search. Bypasses other search params. NOTE: personal Outlook.com accounts reject field-scoped `$search` outright; since v3.10.0 recognised `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried automatically (a `subject:` term becomes a substring match, so it is close but not identical) (reported as strategy `raw-kql-translated`). Expressions that cannot be translated exactly — free text, `AND`/`OR`, unknown prefixes — are not retried, so use `query` for those there.',
+            'Raw Microsoft Graph `$search` expression for advanced server-side search, e.g. `subject:"invoice"`, `from:github.com`, or `foo OR bar`. Quote your own phrases; a single bare token is auto-quoted. Pair with `searchAllFolders: true` for cross-folder search. Bypasses other search params. NOTE: personal Outlook.com accounts reject field-scoped `$search` outright; since v3.10.0 recognised `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried automatically (a `subject:` term becomes a substring match, so it is close but not identical) (reported as strategy `raw-kql-translated`). Expressions that cannot be translated exactly — free text, `AND`/`OR`, unknown prefixes — are not retried, so use `query` for those there. RELEVANCE, NOT RECENCY: an untranslated expression is answered by Graph `$search` over the whole message including the body, ranked by relevance and not sorted by date, so top hits can look unrelated to a caller expecting a subject match. `query` is the more predictable choice for a term you expect in a subject line; `searchExpression` is the one that reaches body text.',
         },
         kqlQuery: {
           type: 'string',
@@ -90,7 +91,8 @@ const emailTools = [
         },
         to: {
           type: 'string',
-          description: 'Filter by recipient email/name',
+          description:
+            'Filter by recipient email/name. Personal Outlook.com accounts reject the server-side recipient filter, in which case this is matched locally over the 500 most recent messages only (raise with `OUTLOOK_SEARCH_SCAN_LIMIT`). On a large archive, pair `to` with `receivedAfter`/`receivedBefore` to reach older mail; the response says so when the scan was truncated.',
         },
         subject: {
           type: 'string',

package/email/search.js

@@ -79,9 +79,19 @@ async function handleSearchEmails(args) {
   // this, a `from`+`to` search would drop every row at default verbosity and
   // return "No emails found" — making `outputVerbosity`, a presentation
   // parameter, decide which messages are found.
+  //
+  // A SINGLE term needs the richer preset too when it is `to` or `query`. The
+  // date/boolean rung applies no search term server-side, so it narrows by
+  // every supplied term locally — and `filterToClientSide` reads
+  // `toRecipients` while `filterQueryClientSide` reads `bodyPreview`, neither
+  // of which the `list` preset requests. Left lean, those matchers see
+  // `undefined` on every row and drop the entire result set.
   const searchTermCount = [query, from, to, subject].filter(Boolean).length;
+  const needsMatcherFields = Boolean(to) || Boolean(query);
   const selectFields = getEmailFields(
-    verbosity === VERBOSITY.FULL || searchTermCount > 1 ? 'search' : 'list'
+    verbosity === VERBOSITY.FULL || searchTermCount > 1 || needsMatcherFields
+      ? 'search'
+      : 'list'
   );
 
   try {
@@ -1300,9 +1310,20 @@ function addBooleanFilters(params, filterTerms) {
     }
   }
 
-  // Add $filter parameter if we have any filter conditions
+  // AND onto any $filter the caller already built — never replace it.
+  //
+  // The single-term rung sets `$filter` from the search term (e.g.
+  // `toRecipients/any(...)`) and then calls this to add the date/boolean
+  // window. Assigning here silently dropped that term, so a `to` + date-window
+  // search issued a DATE-ONLY request and returned the whole window labelled
+  // `single-term-to` with `appliedTerms: ['to']` — a superset presented as a
+  // filtered result. Affected `from`, `to`, `subject` and `query` alike.
+  //
+  // Every condition either side is a conjunct, so a flat ' and ' join is
+  // sound; there is no top-level `or` that would need parenthesising.
   if (filterConditions.length > 0) {
-    params.$filter = filterConditions.join(' and ');
+    const added = filterConditions.join(' and ');
+    params.$filter = params.$filter ? `${params.$filter} and ${added}` : added;
   }
 }
 
@@ -1506,6 +1527,17 @@ function formatSearchResults(response, folder, verbosity, searchAllFolders) {
     } else {
       searchNote = `\n\n_Search strategy: ${strategy}_`;
     }
+
+    // A local scan that filled its budget did not see the whole mailbox, so
+    // these results are a bounded sample rather than the complete set. #231
+    // says so only when the search returns nothing; a truncated scan that
+    // DID match is exactly as incomplete and reads as authoritative. On a
+    // large archive that silently caps historical searches.
+    if (response._searchInfo.truncated) {
+      const scanned = response._searchInfo.candidatesScanned;
+      const limit = response._searchInfo.scanLimit;
+      searchNote += `\n\n> **Partial coverage**: matched locally within the ${scanned} most recent messages, hitting the ${limit} scan limit — older matches were not seen. Narrow with \`receivedAfter\`/\`receivedBefore\` to search further back.`;
+    }
   }
 
   // Format results using shared formatter

package/index.js

@@ -5,6 +5,65 @@
  * A Model Context Protocol server that provides access to
  * Microsoft Outlook through the Microsoft Graph API.
  */
+// CLI flag handling (#68).
+//
+// Deliberately the first thing that runs: it must complete before the SDK
+// imports, before the auth modules load, and before the startup banner below
+// writes to stderr — otherwise `--version` output is buried in server noise and
+// the process never exits (the SIGTERM handler below keeps it alive).
+//
+// `config.js` is required lazily here so this costs nothing on the normal
+// server path; it is the single source of truth for the version, which it
+// reads from package.json.
+const cliArgs = process.argv.slice(2);
+if (cliArgs.length > 0) {
+  const HELP_TEXT = `outlook-assistant — MCP server for Microsoft Outlook via the Microsoft Graph API.
+
+Usage:
+  outlook-assistant [options]
+
+Options:
+  -v, --version   Print the version and exit
+  -h, --help      Show this help and exit
+
+With no options the server starts and speaks the Model Context Protocol over
+stdio. It is normally launched by an MCP client (Claude Desktop, Claude Code)
+rather than run by hand — started from a terminal it will simply wait on stdin.
+
+Key environment variables:
+  OUTLOOK_CLIENT_ID                 Azure app registration client ID
+  OUTLOOK_CLIENT_SECRET             Client secret VALUE (not the Secret ID)
+  OUTLOOK_AUTH_METHOD               device-code (default) | browser
+  OUTLOOK_AUTH_AUDIENCE             common | consumers | organizations | <tenant-guid>
+  OUTLOOK_MAX_EMAILS_PER_SESSION    Cap on sends per session
+  OUTLOOK_ALLOWED_RECIPIENTS        Comma-separated recipient allowlist
+  USE_TEST_MODE                     Set to "true" to run against mock data
+
+Documentation: https://github.com/littlebearapps/outlook-assistant`;
+
+  const KNOWN_FLAGS = new Set(['--version', '-v', '--help', '-h']);
+
+  // Validate every argument before acting on any of them. Checking for a
+  // recognised flag first would let `--version --nope` succeed and silently
+  // swallow the typo — an unrecognised argument is a user error regardless of
+  // what else is on the command line.
+  const unknown = cliArgs.find((arg) => !KNOWN_FLAGS.has(arg));
+  if (unknown) {
+    console.error(
+      `outlook-assistant: unrecognised argument '${unknown}'\nRun 'outlook-assistant --help' for usage.`
+    );
+    process.exit(1);
+  }
+
+  if (cliArgs.includes('--version') || cliArgs.includes('-v')) {
+    console.log(require('./config').SERVER_VERSION);
+    process.exit(0);
+  }
+
+  console.log(HELP_TEXT);
+  process.exit(0);
+}
+
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const {
   StdioServerTransport,

package/llms-install.md

@@ -83,7 +83,7 @@ After authentication, test with:
 
 | Problem | Solution |
 |---------|----------|
-| "Invalid client secret" (AADSTS7000215) | Use the secret **Value**, not the Secret ID |
+| "Invalid client secret" (AADSTS7000215) | Use the secret **Value**, not the Secret ID. Also check it hasn't expired. v3.11.0+ appends an explanation to Microsoft's raw error |
 | Auth URL doesn't work | Start the auth server first |
 | "EADDRINUSE :3333" | Run `npx kill-port 3333` then restart auth server |
 | Empty API responses | Run `auth` tool with `action=status` to check token |

package/llms.txt

@@ -79,6 +79,6 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 - [FAQ](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/faq/faq.md): Frequently asked questions — install, accounts, permissions, tokens, send safety, updates, uninstall (also at <https://littlebearapps.com/help/outlook-assistant/faq/>)
 - [CLAUDE.md](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CLAUDE.md): Quick reference for development
 - [CONTRIBUTING](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CONTRIBUTING.md): Contribution guidelines
-- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.10.0 — search correctness: field-scoped `searchExpression` translated to OData filters and retried on personal accounts (#217); two-filter searches no longer return the single-filter superset, with `searchMetadata.droppedFilters` reporting anything unhonoured (#229); `from`/`to` filter values OData-escaped (#230); no-results guidance derived from what was actually attempted (#231); production `npm audit` gate cleared plus a weekly watchdog (#215). Preceded by v3.9.1 — packaging hotfix restoring `request-handler.js` in the published tarball (#223) — and v3.9.0 — nested folder addressing by path/ID (#216) and reliable cross-folder search with `kqlQuery` renamed to `searchExpression` (#169))
-- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.7.5 polish, v3.8.x carry-over, v3.11.0+ new Graph APIs)
+- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.11.1 — search and export correctness: a search term combined with a date or boolean filter was silently overwritten, so the request carried only the date window and the whole window came back reported as a filtered result; batch export named files `<date>_<subject>`, so a same-day reply chain overwrote itself on disk while the summary reported `Failed 0` — filenames now carry the time, collisions get a numeric suffix instead of clobbering, and a manifest maps each requested ID to the file actually written; a truncated local scan is now disclosed when it matched, not only when it returned nothing; `query` versus `searchExpression` and the 500-message `to` scan cap documented. Preceded by v3.11.0 — fixes & polish: `--version`/`--help` CLI flags (#68), `AADSTS7000215` explaining the Secret ID vs Secret Value mistake via one shared AADSTS hint table (#69), token-refresh round trip covered end to end (#72), and all 17 development-dependency advisories cleared; and v3.10.0 — search correctness: field-scoped `searchExpression` translated to OData filters and retried on personal accounts (#217), two-filter searches no longer returning the single-filter superset (#229), `from`/`to` filter values OData-escaped (#230), no-results guidance derived from what was actually attempted (#231))
+- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.11.2 tool description audit, v3.8.x carry-over, v3.12.0+ new Graph APIs)
 - [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy, token handling, and MCP safety controls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.10.0",
+  "version": "3.11.1",
   "mcpName": "io.github.littlebearapps/outlook-assistant",
   "description": "Outlook Assistant — MCP server with 22 tools for email, calendar, contacts, and settings via Microsoft Graph API",
   "main": "index.js",