@fink-andreas/pi-linear-tools 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## v0.6.0 (2026-04-23)
+
+Rate-limit resilience for milestone operations.
+
+### Bug Fixes
+- **Fixed linear_milestone view rate-limit crash**: `linear_milestone view` no longer crashes when hitting Linear API rate limits. Errors are now properly surfaced as safe tool results instead of propagating as crashes.
+- **Fixed milestone issues rate-limit swallowing**: `fetchMilestoneDetails()` now correctly propagates rate-limit errors from lazy-loaded issue data instead of silently returning partial results.
+
+### Performance / API Usage
+- **Replaced N+1 lazy loading with single GraphQL query**: Milestone details now fetch all issue state/assignee in ONE request instead of N+1 per-issue lazy loads. This dramatically reduces API calls and rate-limit exposure for large milestones.
+- **Added cached rate-limit pre-check**: `linear_milestone` now has the same cached pre-check that `linear_issue` uses to short-circuit before making API calls when the cache already knows about a rate limit.
+- **Exported `isRateLimitError()` helper**: Made available for consistent error handling across tools.
+
+### Documentation
+- **Reorganized README**: Moved Key Concepts section for better onboarding
+- **Added combined Linear+Pi logo**: Light/dark theme support for branding
+
+## v0.5.1 (2026-04-17)
+
+### Bug Fixes
+- **Prevent pi crashes from Linear tool errors**: Added `executeToolSafely` wrapper that catches errors and returns them as safe tool results instead of throwing, preventing pi from crashing on Linear API errors
+
 ## v0.5.0 (2026-04-17)
 
 Linear document sync, project lifecycle management, and estimate/story points support.

package/README.md

@@ -1,20 +1,14 @@
 # pi-linear-tools
 
-`pi-linear-tools` is a Pi extension for the [Pi coding agent](https://github.com/badlogic/pi-mono) that lets you manage [Linear](https://linear.app/about) issues, projects, and milestones via LLM tools and CLI commands.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/images/linear-pi-combined-white.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/images/linear-pi-combined-black.svg">
+    <img src="docs/images/linear-pi-combined-black.svg" alt="Linear + Pi" width="340">
+  </picture>
+</p>
 
-Useful mental model:
-- `issue update` changes issue fields; `issue comment` adds discussion; `issue activity` reads the Activity timeline
-- `project update` changes project fields; `project-update` manages Updates tab entries
-- `project-update` maps to Linear project updates in the Updates tab
-- `sync-doc init` scaffolds `.linear-tools/config.json` in the folder you point at
-- `sync-doc run` and `sync-doc check` default to all configured targets in `.linear-tools/config.json`
-- `sync-doc --target X` narrows the operation to one configured target
-
-Reference conventions:
-- issues use issue key or issue ID
-- projects use project name or project ID
-- project updates use project update ID
-- milestones use milestone ID
+`pi-linear-tools` is a token eficcient Pi extension for the [Pi coding agent](https://github.com/badlogic/pi-mono) that lets you manage [Linear](https://linear.app/about) issues, projects, and milestones via LLM tool calls and CLI commands.
 
 ## Install
 
@@ -54,6 +48,22 @@ Optional non-interactive commands:
 - `/linear-tools-config`
 - `/linear-tools-help`
 
+## Key Concepts
+
+Useful mental model:
+- `issue update` changes issue fields; `issue comment` adds discussion; `issue activity` reads the Activity timeline
+- `project update` changes project fields; `project-update` manages Updates tab entries
+- `project-update` maps to Linear project updates in the Updates tab
+- `sync-doc init` scaffolds `.linear-tools/config.json` in the folder you point at
+- `sync-doc run` and `sync-doc check` default to all configured targets in `.linear-tools/config.json`
+- `sync-doc --target X` narrows the operation to one configured target
+
+Reference conventions:
+- issues use issue key or issue ID
+- projects use project name or project ID
+- project updates use project update ID
+- milestones use milestone ID
+
 ## LLM-callable tools
 
 ### `linear_issue`

package/extensions/pi-linear-tools.js

@@ -1,5 +1,5 @@
 import { loadSettings, saveSettings } from '../src/settings.js';
-import { createLinearClient, checkAndClearRateLimit, markRateLimited, getClientRequestMetrics } from '../src/linear-client.js';
+import { createLinearClient, checkAndClearRateLimit, markRateLimited, getClientRequestMetrics, getClientRateLimitInfo } from '../src/linear-client.js';
 import { setQuietMode, debug } from '../src/logger.js';
 import {
   resolveProjectRef,
@@ -120,12 +120,13 @@ async function createAuthenticatedClient() {
   return createLinearClient(await getLinearAuth());
 }
 
-async function withRequestUsageLogging(client, toolName, action, operation) {
+async function withRequestUsageLogging(client, toolName, action, operation, rateLimitDebug = false) {
   const before = getClientRequestMetrics(client);
 
   try {
     const result = await operation();
     const after = getClientRequestMetrics(client);
+    const rateLimitInfo = rateLimitDebug ? getClientRateLimitInfo(client) : null;
 
     const usageDelta = {
       tool: toolName,
@@ -139,17 +140,54 @@ async function withRequestUsageLogging(client, toolName, action, operation) {
 
     debug('[pi-linear-tools] API usage per command', usageDelta);
 
-    if (!INCLUDE_USAGE_SUMMARY || !result || typeof result !== 'object') {
+    if (rateLimitDebug && rateLimitInfo) {
+      debug('[pi-linear-tools] Rate limit status', {
+        tool: toolName,
+        action,
+        rateLimitUsed: rateLimitInfo.used,
+        rateLimitRemaining: rateLimitInfo.remaining,
+        rateLimitPercent: rateLimitInfo.usagePercent,
+        rateLimitResetAt: rateLimitInfo.resetTime,
+      });
+    }
+
+    // When rateLimitDebug is true, always include rate limit info in result details
+    // even if INCLUDE_USAGE_SUMMARY is disabled
+    if (!result || typeof result !== 'object') {
       return result;
     }
 
     const details = (result.details && typeof result.details === 'object') ? result.details : {};
+
+    // Add rate limit info to details if debug is enabled
+    if (rateLimitDebug && rateLimitInfo) {
+      details.rateLimit = rateLimitInfo;
+    }
+
+    if (!INCLUDE_USAGE_SUMMARY && !rateLimitDebug) {
+      return {
+        ...result,
+        details,
+      };
+    }
+
     const content = Array.isArray(result.content)
       ? result.content.map((item, idx) => {
         if (idx !== 0 || item?.type !== 'text' || typeof item.text !== 'string') return item;
+        let appendedText = item.text;
+
+        if (INCLUDE_USAGE_SUMMARY) {
+          appendedText += `\n\n_${usageDelta.summary}_`;
+        }
+
+        if (rateLimitDebug && rateLimitInfo) {
+          const percent = rateLimitInfo.usagePercent;
+          appendedText += `\n\n---\n**Rate Limit**: ${rateLimitInfo.used}/${rateLimitInfo.total} used (${percent}%) • Resets at ${rateLimitInfo.resetTime}`;
+        }
+
         return {
           ...item,
-          text: `${item.text}\n\n_${usageDelta.summary}_`,
+          text: appendedText,
         };
       })
       : result.content;
@@ -159,11 +197,12 @@ async function withRequestUsageLogging(client, toolName, action, operation) {
       content,
       details: {
         ...details,
-        apiUsage: usageDelta,
+        ...(INCLUDE_USAGE_SUMMARY ? { apiUsage: usageDelta } : {}),
       },
     };
   } catch (error) {
     const after = getClientRequestMetrics(client);
+    const rateLimitInfo = rateLimitDebug ? getClientRateLimitInfo(client) : null;
 
     debug('[pi-linear-tools] API usage per command (error)', {
       tool: toolName,
@@ -173,6 +212,11 @@ async function withRequestUsageLogging(client, toolName, action, operation) {
       failedDelta: after.failed - before.failed,
       rateLimitedDelta: after.rateLimited - before.rateLimited,
       error: String(error?.message || error || 'unknown'),
+      ...(rateLimitDebug && rateLimitInfo ? {
+        rateLimitUsed: rateLimitInfo.used,
+        rateLimitRemaining: rateLimitInfo.remaining,
+        rateLimitPercent: rateLimitInfo.usagePercent,
+      } : {}),
     });
 
     throw error;
@@ -460,21 +504,35 @@ function toToolTextResult(text, details = {}) {
 }
 
 function buildRateLimitToolResult(error, options = {}) {
-  const { cached = false } = options;
+  const { cached = false, viaCachedPreCheck = false } = options;
   const resetTimestamp = error?.requestsResetAt || Date.now() + 3600000;
   const resetTime = new Date(resetTimestamp).toLocaleTimeString();
 
   markRateLimited(resetTimestamp);
 
   return toToolTextResult(
-    cached
-      ? `Linear API rate limit exceeded (cached).\n\nThe rate limit resets at: ${resetTime}\n\nPlease wait before making more requests.`
-      : `Linear API rate limit exceeded.\n\nThe rate limit resets at: ${resetTime}\n\nPlease wait before making more requests, or reduce the frequency of API calls.`,
+    viaCachedPreCheck
+      ? `Linear API rate limit exceeded (cached — this request was not sent to Linear).
+
+The rate limit resets at: ${resetTime}
+
+Please wait before making more requests.`
+      : cached
+        ? `Linear API rate limit exceeded (cached).
+
+The rate limit resets at: ${resetTime}
+
+Please wait before making more requests.`
+        : `Linear API rate limit exceeded.
+
+The rate limit resets at: ${resetTime}
+
+Please wait before making more requests, or reduce the frequency of API calls.`,
     {
       error: true,
       errorType: 'Ratelimited',
       rateLimited: true,
-      cached,
+      cached: viaCachedPreCheck || cached,
       requestsResetAt: resetTimestamp,
       resetTime,
     }
@@ -487,7 +545,7 @@ function handleToolExecutionError(error, operationLabel, options = {}) {
   const errorMessage = String(transformedError?.message || transformedError || 'Unknown error');
 
   if (errorType === 'Ratelimited' || errorMessage.toLowerCase().includes('rate limit')) {
-    return buildRateLimitToolResult(error);
+    return buildRateLimitToolResult(transformedError, { viaCachedPreCheck: options.viaCachedPreCheck });
   }
 
   if (errorMessage.includes('Linear API error:')) {
@@ -497,6 +555,40 @@ function handleToolExecutionError(error, operationLabel, options = {}) {
   throw new Error(`${operationLabel}: ${errorMessage}`);
 }
 
+function buildGenericToolErrorResult(error, operationLabel) {
+  const errorType = error?.type || error?.name || 'Error';
+  const errorMessage = String(error?.message || error || 'Unknown error');
+
+  return toToolTextResult(`${operationLabel}: ${errorMessage}`, {
+    error: true,
+    errorType,
+    rateLimited: false,
+  });
+}
+
+async function executeToolSafely(operationLabel, operation, options = {}) {
+  try {
+    return await operation();
+  } catch (error) {
+    debug('[pi-linear-tools] tool execution failed', {
+      operationLabel,
+      errorType: error?.type || error?.name || null,
+      error: String(error?.message || error || 'unknown'),
+    });
+
+    try {
+      return handleToolExecutionError(error, operationLabel, options);
+    } catch (handledError) {
+      debug('[pi-linear-tools] returning generic safe tool error result', {
+        operationLabel,
+        errorType: handledError?.type || handledError?.name || null,
+        error: String(handledError?.message || handledError || 'unknown'),
+      });
+      return buildGenericToolErrorResult(handledError, operationLabel);
+    }
+  }
+}
+
 function renderMarkdownResult(result, _options, _theme) {
   const text = result.content?.[0]?.text || '';
 
@@ -666,13 +758,15 @@ async function registerLinearTools(pi) {
     },
     renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
-      try {
+      return executeToolSafely('Linear issue operation failed', async () => {
         // Pre-check: skip API calls if we know we're rate limited
         const { isRateLimited, resetAt } = checkAndClearRateLimit();
         if (isRateLimited) {
           return buildRateLimitToolResult({ requestsResetAt: resetAt.getTime(), type: 'Ratelimited' }, { cached: true });
         }
 
+        const settings = await loadSettings();
+        const rateLimitDebug = settings.rateLimitDebug || false;
         const client = await createAuthenticatedClient();
 
         return await withRequestUsageLogging(client, 'linear_issue', params.action, async () => {
@@ -700,39 +794,8 @@ async function registerLinearTools(pi) {
             default:
               throw new Error(`Unknown action: ${params.action}`);
           }
-        });
-      } catch (error) {
-        // Comprehensive error handling - catch ALL errors including SDK's RatelimitedLinearError
-        const errorType = error?.type || '';
-        const errorMessage = String(error?.message || error || 'Unknown error');
-
-        // Authentication/Forbidden errors (handles SDK's ForbiddenLinearError)
-        if (errorType === 'Forbidden' || errorType === 'AuthenticationError' ||
-          errorMessage.toLowerCase().includes('forbidden') || errorMessage.toLowerCase().includes('unauthorized')) {
-          throw new Error(
-            `Linear API authentication failed: ${errorMessage}\n\n` +
-            `Please check your API key or OAuth token permissions.`
-          );
-        }
-
-        // Network errors (handles SDK's NetworkError)
-        if (errorType === 'NetworkError' || errorMessage.toLowerCase().includes('network')) {
-          throw new Error(
-            `Network error communicating with Linear API.\n\n` +
-            `Please check your internet connection and try again.`
-          );
-        }
-
-        // Internal server errors (handles SDK's InternalError)
-        if (errorType === 'InternalError' || (error?.status >= 500 && error?.status < 600)) {
-          throw new Error(
-            `Linear API server error (${error?.status || 'unknown'}).\n\n` +
-            `Linear may be experiencing issues. Please try again later.`
-          );
-        }
-
-        return handleToolExecutionError(error, 'Linear issue operation failed');
-      }
+        }, rateLimitDebug);
+      });
     },
   });
 
@@ -798,7 +861,9 @@ async function registerLinearTools(pi) {
     },
     renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
-      try {
+      return executeToolSafely('Linear project operation failed', async () => {
+        const settings = await loadSettings();
+        const rateLimitDebug = settings.rateLimitDebug || false;
         const client = await createAuthenticatedClient();
 
         return await withRequestUsageLogging(client, 'linear_project', params.action, async () => {
@@ -820,10 +885,8 @@ async function registerLinearTools(pi) {
             default:
               throw new Error(`Unknown action: ${params.action}`);
           }
-        });
-      } catch (error) {
-        return handleToolExecutionError(error, 'Linear project operation failed');
-      }
+        }, rateLimitDebug);
+      });
     },
   });
 
@@ -877,7 +940,9 @@ async function registerLinearTools(pi) {
     },
     renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
-      try {
+      return executeToolSafely('Linear project update operation failed', async () => {
+        const settings = await loadSettings();
+        const rateLimitDebug = settings.rateLimitDebug || false;
         const client = await createAuthenticatedClient();
 
         return await withRequestUsageLogging(client, 'linear_project_update', params.action, async () => {
@@ -897,10 +962,8 @@ async function registerLinearTools(pi) {
             default:
               throw new Error(`Unknown action: ${params.action}`);
           }
-        });
-      } catch (error) {
-        return handleToolExecutionError(error, 'Linear project update operation failed');
-      }
+        }, rateLimitDebug);
+      });
     },
   });
 
@@ -923,7 +986,9 @@ async function registerLinearTools(pi) {
     },
     renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
-      try {
+      return executeToolSafely('Linear team operation failed', async () => {
+        const settings = await loadSettings();
+        const rateLimitDebug = settings.rateLimitDebug || false;
         const client = await createAuthenticatedClient();
 
         return await withRequestUsageLogging(client, 'linear_team', params.action, async () => {
@@ -933,10 +998,8 @@ async function registerLinearTools(pi) {
             default:
               throw new Error(`Unknown action: ${params.action}`);
           }
-        });
-      } catch (error) {
-        return handleToolExecutionError(error, 'Linear team operation failed');
-      }
+        }, rateLimitDebug);
+      });
     },
   });
 
@@ -980,9 +1043,18 @@ async function registerLinearTools(pi) {
       },
       renderResult: renderMarkdownResult,
       async execute(_toolCallId, params) {
-        try {
+        return executeToolSafely('Linear milestone operation failed', async () => {
+          // Pre-check: skip API calls if we know we're rate limited
+          const { isRateLimited, resetAt } = checkAndClearRateLimit();
+          if (isRateLimited) {
+            return buildRateLimitToolResult({ requestsResetAt: resetAt.getTime(), type: 'Ratelimited' }, { viaCachedPreCheck: true });
+          }
+
+          const settings = await loadSettings();
+          const rateLimitDebug = settings.rateLimitDebug || false;
           const client = await createAuthenticatedClient();
 
+
           return await withRequestUsageLogging(client, 'linear_milestone', params.action, async () => {
             switch (params.action) {
               case 'list':
@@ -998,12 +1070,10 @@ async function registerLinearTools(pi) {
               default:
                 throw new Error(`Unknown action: ${params.action}`);
             }
-          });
-        } catch (error) {
-          return handleToolExecutionError(error, 'Linear milestone operation failed', {
-            transformError: withMilestoneScopeHint,
-          });
-        }
+          }, rateLimitDebug);
+        }, {
+          transformError: withMilestoneScopeHint,
+        });
       },
     });
   }
@@ -1013,13 +1083,14 @@ export default async function piLinearToolsExtension(pi) {
   // Safety wrapper: never let extension errors crash pi
   try {
   pi.registerCommand('linear-tools-config', {
-    description: 'Configure pi-linear-tools settings (API key and default team mappings)',
+    description: 'Configure pi-linear-tools settings (API key, default team, rate limit debug)',
     handler: async (argsText, ctx) => {
       const args = parseArgs(argsText);
       const apiKey = readFlag(args, '--api-key');
       const defaultTeam = readFlag(args, '--default-team');
       const projectTeam = readFlag(args, '--team');
       const projectName = readFlag(args, '--project');
+      const rateLimitDebug = readFlag(args, '--rate-limit-debug');
 
       if (apiKey) {
         const settings = await loadSettings();
@@ -1040,6 +1111,17 @@ export default async function piLinearToolsExtension(pi) {
         return;
       }
 
+      if (rateLimitDebug) {
+        const settings = await loadSettings();
+        const enabled = rateLimitDebug === 'true' || rateLimitDebug === '1';
+        settings.rateLimitDebug = enabled;
+        await saveSettings(settings);
+        if (ctx?.hasUI) {
+          ctx.ui.notify(`Rate limit debug ${enabled ? 'enabled' : 'disabled'}`, 'info');
+        }
+        return;
+      }
+
       if (defaultTeam) {
         const settings = await loadSettings();
         settings.defaultTeam = defaultTeam;
@@ -1083,18 +1165,24 @@ export default async function piLinearToolsExtension(pi) {
         return;
       }
 
-      if (!apiKey && !defaultTeam && !projectTeam && !projectName && ctx?.hasUI && ctx?.ui) {
+      if (!apiKey && !defaultTeam && !projectTeam && !projectName && !rateLimitDebug && ctx?.hasUI && ctx?.ui) {
         await runInteractiveConfigFlow(ctx, pi);
         return;
       }
 
+      // Show current settings if no valid action was specified
+      if (apiKey || defaultTeam || projectTeam || projectName || rateLimitDebug) {
+        // Actions above already handled and returned
+        return;
+      }
+
       const settings = await loadSettings();
       const hasKey = !!(settings.apiKey || settings.linearApiKey || process.env.LINEAR_API_KEY);
       const keySource = process.env.LINEAR_API_KEY ? 'environment' : (settings.apiKey || settings.linearApiKey ? 'settings' : 'not set');
 
       pi.sendMessage({
         customType: 'pi-linear-tools',
-        content: `Configuration:\n  LINEAR_API_KEY: ${hasKey ? 'configured' : 'not set'} (source: ${keySource})\n  Default workspace: ${settings.defaultWorkspace?.name || 'not set'}\n  Default team: ${settings.defaultTeam || 'not set'}\n  Project team mappings: ${Object.keys(settings.projects || {}).length}\n\nCommands:\n  /linear-tools-config --api-key lin_xxx\n  /linear-tools-config --default-team ENG\n  /linear-tools-config --team ENG --project MyProject\n\nNote: environment LINEAR_API_KEY takes precedence over settings file.`,
+        content: `Configuration:\n  LINEAR_API_KEY: ${hasKey ? 'configured' : 'not set'} (source: ${keySource})\n  Default workspace: ${settings.defaultWorkspace?.name || 'not set'}\n  Default team: ${settings.defaultTeam || 'not set'}\n  Rate limit debug: ${settings.rateLimitDebug ? 'enabled' : 'disabled'}\n  Project team mappings: ${Object.keys(settings.projects || {}).length}\n\nCommands:\n  /linear-tools-config --api-key lin_xxx\n  /linear-tools-config --default-team ENG\n  /linear-tools-config --team ENG --project MyProject\n  /linear-tools-config --rate-limit-debug true|false\n\nNote: environment LINEAR_API_KEY takes precedence over settings file.`,
         display: true,
       });
     },
@@ -1139,6 +1227,7 @@ export default async function piLinearToolsExtension(pi) {
           '  /linear-tools-config --api-key <key>',
           '  /linear-tools-config --default-team <team-key>',
           '  /linear-tools-config --team <team-key> --project <project-name-or-id>',
+          '  /linear-tools-config --rate-limit-debug true|false',
           '  /linear-tools-help',
           '  /linear-tools-reload',
           '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fink-andreas/pi-linear-tools",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Pi extension with Linear SDK tools and configuration commands",
   "type": "module",
   "engines": {

package/src/linear-client.js

@@ -140,6 +140,40 @@ export function getClientRateLimit(client) {
   return { remaining: null, resetAt: null, resetTime: null };
 }
 
+/**
+ * Get detailed rate limit info including usage percentage
+ * @param {LinearClient} client - Linear SDK client
+ * @returns {{remaining: number|null, resetAt: number|null, resetTime: string|null, used: number, usagePercent: number|null, total: number}}
+ */
+export function getClientRateLimitInfo(client) {
+  const trackerData = rateLimitTracker.get(getTrackerKeyFromClient(client));
+  const total = 5000; // Linear's hourly request limit
+
+  if (trackerData && trackerData.remaining !== undefined) {
+    const remaining = trackerData.remaining;
+    const used = Math.max(0, total - remaining);
+    const usagePercent = Math.round((used / total) * 100);
+
+    return {
+      remaining,
+      resetAt: trackerData.resetAt,
+      resetTime: trackerData.resetAt ? new Date(trackerData.resetAt).toLocaleTimeString() : null,
+      used,
+      usagePercent,
+      total,
+    };
+  }
+
+  return {
+    remaining: null,
+    resetAt: null,
+    resetTime: null,
+    used: 0,
+    usagePercent: null,
+    total,
+  };
+}
+
 /**
  * Expose per-client request counters for diagnostics
  */
@@ -317,3 +351,20 @@ export function setTestClientFactory(factory) {
 export function resetTestClientFactory() {
   _testClientFactory = null;
 }
+
+/**
+ * Set rate limit tracker state for testing (TEST ONLY)
+ * @param {string} apiKey - API key used to create the client
+ * @param {{remaining: number, resetAt: number}} state - Tracker state
+ */
+export function setTestRateLimitTracker(apiKey, state) {
+  const trackerKey = getTrackerKey(apiKey);
+  rateLimitTracker.set(trackerKey, state);
+}
+
+/**
+ * Clear rate limit tracker for testing (TEST ONLY)
+ */
+export function clearTestRateLimitTracker() {
+  rateLimitTracker.clear();
+}

package/src/linear.js

@@ -235,6 +235,45 @@ const PROJECT_UPDATE_MUTATION = `
   }
 `;
 
+
+const MILESTONE_DETAILS_QUERY = `
+  query MilestoneDetails($id: String!, $issueLimit: Int!) {
+    projectMilestone(id: $id) {
+      id
+      name
+      description
+      progress
+      sortOrder
+      targetDate
+      status
+      project {
+        id
+        name
+      }
+      issues(first: $issueLimit) {
+        nodes {
+          id
+          identifier
+          title
+          priority
+          estimate
+          state {
+            id
+            name
+            color
+            type
+          }
+          assignee {
+            id
+            name
+            displayName
+          }
+        }
+      }
+    }
+  }
+`;
+
 const PROJECT_DELETE_MUTATION = `
   mutation ProjectDelete($id: String!) {
     projectDelete(id: $id) {
@@ -1331,7 +1370,7 @@ function checkRateLimitWarning() {
  * @param {Error} error - The error to check
  * @returns {boolean}
  */
-function isLinearError(error) {
+export function isLinearError(error) {
   return error?.constructor?.name?.includes('LinearError') ||
     error?.name?.includes('LinearError') ||
     error?.type?.startsWith?.('Ratelimited') ||
@@ -1342,6 +1381,19 @@ function isLinearError(error) {
     error?.type === 'InternalError';
 }
 
+
+/**
+ * Check if an error is a rate-limit error
+ * @param {Error} error - The error to check
+ * @returns {boolean}
+ */
+export function isRateLimitError(error) {
+  return (
+    isLinearError(error) &&
+    (error?.type === 'Ratelimited' || String(error?.message || '').toLowerCase().includes('rate limit'))
+  );
+}
+
 /**
  * Format a Linear API error into a user-friendly message
  * @param {Error} error - The original error
@@ -3527,24 +3579,90 @@ export async function fetchProjectMilestones(client, projectId) {
  */
 export async function fetchMilestoneDetails(client, milestoneId) {
   return withLinearErrorHandling(async () => {
+    // Prefer raw GraphQL: one request instead of N+1 SDK lazy loads.
+    // This dramatically reduces rate-limit exposure for milestone view.
+    if (getRawRequest(client)) {
+      try {
+        const data = await executeGraphQL(client, MILESTONE_DETAILS_QUERY, {
+          id: milestoneId,
+          issueLimit: 250,
+        });
+
+        const raw = data?.projectMilestone;
+        if (!raw) {
+          throw new Error(`Milestone not found: ${milestoneId}`);
+        }
+
+        const project = raw.project ? { id: raw.project.id, name: raw.project.name } : null;
+        const issues = (raw.issues?.nodes || []).map((issue) => ({
+          id: issue.id,
+          identifier: issue.identifier,
+          title: issue.title,
+          state: issue.state ? { name: issue.state.name, color: issue.state.color, type: issue.state.type } : null,
+          assignee: issue.assignee ? { id: issue.assignee.id, name: issue.assignee.name, displayName: issue.assignee.displayName } : null,
+          priority: issue.priority ?? null,
+          estimate: issue.estimate ?? null,
+        }));
+
+        return {
+          id: raw.id,
+          name: raw.name,
+          description: raw.description ?? null,
+          progress: raw.progress ?? null,
+          order: raw.sortOrder ?? null,
+          targetDate: raw.targetDate ?? null,
+          status: raw.status ?? null,
+          project,
+          issues,
+        };
+      } catch (err) {
+        // If raw GraphQL fails (e.g., network error), fall through to SDK path.
+        // Rate-limit errors are re-thrown by executeGraphQL -> withLinearErrorHandling.
+        if (!isLinearError(err)) {
+          debug('fetchMilestoneDetails: raw GraphQL unavailable, falling back to SDK', { error: err?.message });
+        } else {
+          throw err; // re-throw Linear errors including rate limits
+        }
+      }
+    }
+
+    // SDK fallback: the rate-limit propagation logic for lazy loads is preserved.
     const milestone = await client.projectMilestone(milestoneId);
     if (!milestone) {
       throw new Error(`Milestone not found: ${milestoneId}`);
     }
 
     // Fetch project and issues in parallel
-    const [project, issuesResult] = await Promise.all([
+    const [projectResult, issuesResult] = await Promise.all([
       milestone.project?.catch?.(() => null) ?? milestone.project,
-      milestone.issues?.()?.catch?.(() => ({ nodes: [] })) ?? milestone.issues?.() ?? { nodes: [] },
+      milestone.issues?.()?.catch?.((err) => {
+        if (isRateLimitError(err)) {
+          // Propagate rate-limit errors so the caller can surface a safe user message
+          // instead of silently swallowing the issue list.
+          throw err;
+        }
+        return { nodes: [] };
+      }) ?? { nodes: [] },
     ]);
 
+    const project = projectResult;
+
     const issues = await Promise.all(
       (issuesResult.nodes || []).map(async (issue) => {
+        // Propagate rate-limit errors from per-issue lazy loads so the caller can surface
+        // a safe user message. Silently degrading to partial data masks the problem.
         const [state, assignee] = await Promise.all([
-          issue.state?.catch?.(() => null) ?? issue.state,
-          issue.assignee?.catch?.(() => null) ?? issue.assignee,
+          issue.state?.catch?.((err) => {
+            if (isRateLimitError(err)) throw err;
+            return null;
+          }) ?? issue.state,
+          issue.assignee?.catch?.((err) => {
+            if (isRateLimitError(err)) throw err;
+            return null;
+          }) ?? issue.assignee,
         ]);
 
+
         return {
           id: issue.id,
           identifier: issue.identifier,

package/src/settings.js

@@ -21,6 +21,7 @@ export function getDefaultSettings() {
     defaultTeam: null,
     defaultWorkspace: null,
     projects: {},
+    rateLimitDebug: false, // Enable detailed rate limit info per tool call
   };
 }
 
@@ -111,6 +112,11 @@ function migrateSettings(settings) {
     migrated.projects = {};
   }
 
+  // Ensure rateLimitDebug is a boolean
+  if (migrated.rateLimitDebug === undefined) {
+    migrated.rateLimitDebug = false;
+  }
+
   // Migrate project scopes
   for (const [projectId, cfg] of Object.entries(migrated.projects)) {
     if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) {
@@ -216,6 +222,11 @@ export function validateSettings(settings) {
     }
   }
 
+  // Validate rateLimitDebug
+  if (settings.rateLimitDebug !== undefined && typeof settings.rateLimitDebug !== 'boolean') {
+    errors.push('settings.rateLimitDebug must be a boolean');
+  }
+
   return { valid: errors.length === 0, errors };
 }