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

package/src/handlers.js

@@ -6,6 +6,7 @@
  */
 
 import path from 'path';
+import { mkdir, open, unlink } from 'node:fs/promises';
 import {
   prepareIssueStart,
   setIssueState,
@@ -20,9 +21,11 @@ import {
   resolveMilestoneRef,
   getTeamWorkflowStates,
   fetchIssueDetails,
+  fetchIssueImages,
   fetchIssueActivity,
   formatIssueAsMarkdown,
   formatIssueActivityAsMarkdown,
+  fetchIssues,
   fetchIssuesByProject,
   fetchProjectMilestones,
   fetchMilestoneDetails,
@@ -53,6 +56,20 @@ function toTextResult(text, details = {}) {
   };
 }
 
+const COMMENT_PREVIEW_LIMIT = 500;
+
+function formatCommentPreview(body, limit = COMMENT_PREVIEW_LIMIT) {
+  const text = String(body || '').trim();
+  if (text.length <= limit) {
+    return { text, truncated: false };
+  }
+
+  return {
+    text: `${text.slice(0, limit).trimEnd()}...`,
+    truncated: true,
+  };
+}
+
 function ensureNonEmpty(value, fieldName) {
   const text = String(value || '').trim();
   if (!text) throw new Error(`Missing required field: ${fieldName}`);
@@ -70,6 +87,210 @@ function parseRefList(value) {
     .filter(Boolean);
 }
 
+const DEFAULT_MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024;
+const DEFAULT_MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+
+function hasValue(value) {
+  return value !== undefined && value !== null && String(value).trim() !== '';
+}
+
+function resolveSafeRelativeDirectory(directory, cwd = process.cwd()) {
+  const requested = ensureNonEmpty(directory, 'directory');
+  if (path.isAbsolute(requested)) {
+    throw new Error('Download directory must be a relative path');
+  }
+
+  const resolvedCwd = path.resolve(cwd);
+  const resolvedDirectory = path.resolve(resolvedCwd, requested);
+  const relative = path.relative(resolvedCwd, resolvedDirectory);
+
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error('Download directory must stay within the current working directory');
+  }
+
+  return resolvedDirectory;
+}
+
+function sanitizeDownloadFilename(value) {
+  const text = String(value || '').trim();
+  if (!text) return '';
+
+  const basename = path.basename(text) || text;
+  const sanitized = basename
+    .replace(/[\\/\u0000-\u001f\u007f<>:"|?*]+/g, '_')
+    .replace(/^\.+$/, '')
+    .replace(/^\.+/, '')
+    .trim()
+    .slice(0, 180);
+
+  return sanitized || '';
+}
+
+function filenameFromAttachment(attachment, explicitFilename) {
+  const explicit = sanitizeDownloadFilename(explicitFilename);
+  if (explicit) return explicit;
+
+  const fromTitle = sanitizeDownloadFilename(attachment?.title);
+  if (fromTitle) return fromTitle;
+
+  try {
+    const url = new URL(attachment?.url || '');
+    const fromUrl = sanitizeDownloadFilename(url.pathname);
+    if (fromUrl) return fromUrl;
+  } catch {
+    // fall through to attachment id
+  }
+
+  const fromId = sanitizeDownloadFilename(attachment?.id);
+  if (fromId) return fromId;
+
+  throw new Error('Unable to derive a safe filename for attachment; provide filename explicitly');
+}
+
+function resolveSafeDestinationPath(directory, filename, cwd = process.cwd()) {
+  const resolvedDirectory = resolveSafeRelativeDirectory(directory, cwd);
+  const safeFilename = filenameFromAttachment({}, filename);
+  const destination = path.resolve(resolvedDirectory, safeFilename);
+  const relative = path.relative(resolvedDirectory, destination);
+
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error('Download filename must not escape the destination directory');
+  }
+
+  return { directory: resolvedDirectory, filename: safeFilename, filePath: destination };
+}
+
+function selectIssueAttachment(attachments, params) {
+  const list = Array.isArray(attachments) ? attachments : [];
+  if (list.length === 0) {
+    throw new Error('Issue has no Linear attachments to download');
+  }
+
+  const selectors = [
+    ['attachmentId', params.attachmentId],
+    ['attachmentTitle', params.attachmentTitle],
+    ['attachmentUrl', params.attachmentUrl],
+    ['attachmentIndex', params.attachmentIndex],
+  ].filter(([, value]) => hasValue(value));
+
+  if (selectors.length > 1) {
+    throw new Error('Provide only one attachment selector: attachmentId, attachmentTitle, attachmentUrl, or attachmentIndex');
+  }
+
+  if (selectors.length === 0) {
+    if (list.length === 1) return list[0];
+    throw new Error('Multiple attachments found; provide attachmentId, attachmentTitle, attachmentUrl, or attachmentIndex');
+  }
+
+  const [selector, rawValue] = selectors[0];
+  const value = String(rawValue).trim();
+  let matches = [];
+
+  if (selector === 'attachmentId') {
+    matches = list.filter((attachment) => attachment.id === value);
+  } else if (selector === 'attachmentTitle') {
+    const normalized = value.toLowerCase();
+    matches = list.filter((attachment) => String(attachment.title || '').toLowerCase() === normalized);
+  } else if (selector === 'attachmentUrl') {
+    matches = list.filter((attachment) => attachment.url === value);
+  } else if (selector === 'attachmentIndex') {
+    const index = Number.parseInt(value, 10);
+    if (!Number.isInteger(index) || index < 1 || index > list.length) {
+      throw new Error(`attachmentIndex must be between 1 and ${list.length}`);
+    }
+    return list[index - 1];
+  }
+
+  if (matches.length === 0) {
+    throw new Error(`No attachment matched ${selector}: ${value}`);
+  }
+  if (matches.length > 1) {
+    throw new Error(`Multiple attachments matched ${selector}: ${value}; use attachmentId instead`);
+  }
+  return matches[0];
+}
+
+function normalizeMaxBytes(value) {
+  if (value === undefined || value === null || value === '') return DEFAULT_MAX_DOWNLOAD_BYTES;
+  const maxBytes = Number(value);
+  if (!Number.isInteger(maxBytes) || maxBytes <= 0) {
+    throw new Error('maxBytes must be a positive integer');
+  }
+  if (maxBytes > DEFAULT_MAX_DOWNLOAD_BYTES) {
+    throw new Error(`maxBytes cannot exceed ${DEFAULT_MAX_DOWNLOAD_BYTES} bytes`);
+  }
+  return maxBytes;
+}
+
+function normalizeImageMaxBytes(value) {
+  if (value === undefined || value === null || value === '') return DEFAULT_MAX_IMAGE_BYTES;
+  const maxBytes = Number(value);
+  if (!Number.isInteger(maxBytes) || maxBytes <= 0) {
+    throw new Error('maxBytes must be a positive integer');
+  }
+  if (maxBytes > DEFAULT_MAX_IMAGE_BYTES) {
+    throw new Error(`maxBytes cannot exceed ${DEFAULT_MAX_IMAGE_BYTES} bytes for images`);
+  }
+  return maxBytes;
+}
+
+async function writeResponseBodyToFile(response, filePath, options) {
+  const { overwrite, maxBytes } = options;
+  const flags = overwrite ? 'w' : 'wx';
+  let fileHandle;
+  let bytesWritten = 0;
+
+  try {
+    fileHandle = await open(filePath, flags);
+  } catch (err) {
+    if (err?.code === 'EEXIST') {
+      throw new Error(`Destination file already exists: ${filePath}`);
+    }
+    throw err;
+  }
+
+  try {
+    if (!response.body) {
+      const buffer = Buffer.from(await response.arrayBuffer());
+      if (buffer.length > maxBytes) {
+        throw new Error(`Download exceeds maxBytes (${maxBytes} bytes)`);
+      }
+      await fileHandle.writeFile(buffer);
+      bytesWritten = buffer.length;
+      return bytesWritten;
+    }
+
+    const reader = response.body.getReader();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const buffer = Buffer.from(value);
+      bytesWritten += buffer.length;
+      if (bytesWritten > maxBytes) {
+        throw new Error(`Download exceeds maxBytes (${maxBytes} bytes)`);
+      }
+      await fileHandle.write(buffer);
+    }
+    return bytesWritten;
+  } catch (err) {
+    await fileHandle.close().catch(() => {});
+    await unlink(filePath).catch(() => {});
+    throw err;
+  } finally {
+    await fileHandle?.close?.().catch(() => {});
+  }
+}
+
+export const issueDownloadInternals = {
+  DEFAULT_MAX_DOWNLOAD_BYTES,
+  resolveSafeRelativeDirectory,
+  sanitizeDownloadFilename,
+  filenameFromAttachment,
+  resolveSafeDestinationPath,
+  selectIssueAttachment,
+  normalizeMaxBytes,
+};
+
 // ===== GIT OPERATIONS (for issue start) =====
 
 /**
@@ -169,12 +390,24 @@ async function startGitBranch(branchName, fromRef = 'HEAD', onBranchExists = 'sw
 export async function executeIssueList(client, params) {
   return withHandlerErrorHandling(async () => {
     let projectRef = params.project;
-    if (!projectRef) {
-      projectRef = path.basename(process.cwd());
+    let projectMode = false;
+
+    if (projectRef) {
+      // Explicit project specified - use project-scoped listing
+      projectMode = true;
+    } else {
+      // No explicit project - try cwd fallback
+      const cwdProject = path.basename(process.cwd());
+      try {
+        const resolved = await resolveProjectRef(client, cwdProject);
+        projectRef = resolved.name; // use resolved name for display
+        projectMode = true;
+      } catch {
+        // cwd doesn't match any project - fall back to workspace-level listing
+        projectMode = false;
+      }
     }
 
-    const resolved = await resolveProjectRef(client, projectRef);
-
     let assigneeId = null;
     if (params.assignee === 'me') {
       const viewer = await getViewer(client);
@@ -188,21 +421,50 @@ export async function executeIssueList(client, params) {
       teamId = team.id;
     }
 
-    const { issues, truncated } = await fetchIssuesByProject(client, resolved.id, params.states || null, {
-      assigneeId,
-      teamId,
-      limit: params.limit || 20,
-    });
+    const limit = params.limit || 20;
 
-    if (issues.length === 0) {
-      return toTextResult(`No issues found in project "${resolved.name}"`, {
-        projectId: resolved.id,
-        projectName: resolved.name,
-        issueCount: 0,
+    let issues;
+    let truncated;
+    let projectId = null;
+    let projectName = null;
+
+    if (projectMode) {
+      // Project-scoped listing
+      const resolved = await resolveProjectRef(client, projectRef);
+      projectId = resolved.id;
+      projectName = resolved.name;
+
+      const result = await fetchIssuesByProject(client, resolved.id, params.states || null, {
+        assigneeId,
+        teamId,
+        limit,
       });
+      issues = result.issues;
+      truncated = result.truncated;
+    } else {
+      // Workspace-level listing (no project filter)
+      // Default to open states if none specified
+      const workspaceStates = params.states || ['Backlog', 'Triage', 'In Progress', 'In Review'];
+      const result = await fetchIssues(client, assigneeId, workspaceStates, limit);
+      issues = result.issues;
+      truncated = result.truncated;
+    }
+
+    if (issues.length === 0) {
+      return toTextResult(
+        projectMode
+          ? `No issues found in project "${projectName}"`
+          : 'No issues found in workspace',
+        {
+          projectId,
+          projectName,
+          issueCount: 0,
+        }
+      );
     }
 
-    const lines = [`## Issues in project "${resolved.name}" (${issues.length}${truncated ? '+' : ''})\n`];
+    const scopeLabel = projectMode ? `project "${projectName}"` : 'workspace';
+    const lines = [`## Issues in ${scopeLabel} (${issues.length}${truncated ? '+' : ''})\n`];
 
     for (const issue of issues) {
       const stateLabel = issue.state?.name || 'Unknown';
@@ -222,8 +484,8 @@ export async function executeIssueList(client, params) {
     }
 
     return toTextResult(lines.join('\n'), {
-      projectId: resolved.id,
-      projectName: resolved.name,
+      projectId,
+      projectName,
       issueCount: issues.length,
       truncated,
     });
@@ -252,6 +514,126 @@ export async function executeIssueView(client, params) {
   };
 }
 
+export async function executeIssueImages(client, params) {
+  const issue = ensureNonEmpty(params.issue, 'issue');
+  const includeComments = params.includeComments !== false;
+  const maxBytes = normalizeImageMaxBytes(params.maxBytes);
+  const imageData = await fetchIssueImages(client, issue, {
+    includeComments,
+    limit: params.limit || 10,
+    maxBytes,
+  });
+
+  const lines = [
+    `# Images for ${imageData.issue.identifier}: ${imageData.issue.title}`,
+    '',
+  ];
+
+  if (imageData.images.length === 0) {
+    lines.push('No fetchable markdown images found.');
+  } else {
+    lines.push(`Fetched ${imageData.images.length} image${imageData.images.length === 1 ? '' : 's'}.`);
+    lines.push('');
+    imageData.images.forEach((image, index) => {
+      lines.push(`- **Image ${index + 1}**${image.alt ? ` (${image.alt})` : ''}: ${image.url}`);
+      lines.push(`  _${image.mimeType}, ${image.sizeBytes} bytes, source: ${image.source}_`);
+    });
+  }
+
+  if (imageData.failures.length > 0) {
+    lines.push('');
+    lines.push('## Failed image fetches');
+    lines.push('');
+    for (const failure of imageData.failures) {
+      lines.push(`- ${failure.url} — ${failure.error}`);
+    }
+  }
+
+  return {
+    content: [
+      { type: 'text', text: lines.join('\n') },
+      ...imageData.images.map((image) => ({
+        type: 'image',
+        data: image.data,
+        mimeType: image.mimeType,
+      })),
+    ],
+    details: {
+      issue: imageData.issue,
+      imageCount: imageData.images.length,
+      failureCount: imageData.failures.length,
+      totalCandidates: imageData.totalCandidates,
+      images: imageData.images.map(({ data, ...image }) => image),
+      failures: imageData.failures,
+    },
+  };
+}
+
+export async function executeIssueDownload(client, params, options = {}) {
+  const issue = ensureNonEmpty(params.issue, 'issue');
+  const directory = ensureNonEmpty(params.directory, 'directory');
+  const overwrite = params.overwrite === true;
+  const settings = options.settings || {};
+
+  if (overwrite && settings.allow_overwrite_files !== true) {
+    throw new Error('overwrite=true requires allow_overwrite_files=true. Enable it with /linear-tools-config --allow-overwrite-files true.');
+  }
+
+  const maxBytes = normalizeMaxBytes(params.maxBytes);
+  const issueData = await fetchIssueDetails(client, issue, { includeComments: false });
+  const attachment = selectIssueAttachment(issueData.attachments, params);
+  const filename = filenameFromAttachment(attachment, params.filename);
+  const destination = resolveSafeDestinationPath(directory, filename, options.cwd || process.cwd());
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('Fetch API is not available in this Node.js runtime');
+  }
+
+  await mkdir(destination.directory, { recursive: true });
+
+  const response = await fetchImpl(attachment.url, { redirect: 'follow' });
+  if (!response?.ok) {
+    const status = response?.status ? `HTTP ${response.status}` : 'request failed';
+    throw new Error(`Failed to download attachment "${attachment.title}": ${status}`);
+  }
+
+  const contentLengthHeader = response.headers?.get?.('content-length');
+  if (contentLengthHeader) {
+    const contentLength = Number.parseInt(contentLengthHeader, 10);
+    if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+      throw new Error(`Download exceeds maxBytes (${maxBytes} bytes)`);
+    }
+  }
+
+  const bytesWritten = await writeResponseBodyToFile(response, destination.filePath, { overwrite, maxBytes });
+  const relativePath = path.relative(options.cwd || process.cwd(), destination.filePath) || destination.filename;
+
+  return {
+    content: [{
+      type: 'text',
+      text: [
+        `Downloaded **${attachment.title}** to \`${relativePath}\``,
+        '',
+        `- bytes: ${bytesWritten}`,
+        `- source: ${attachment.url}`,
+      ].join('\n'),
+    }],
+    details: {
+      issueId: issueData.id,
+      identifier: issueData.identifier,
+      attachmentId: attachment.id,
+      attachmentTitle: attachment.title,
+      sourceUrl: attachment.url,
+      filePath: destination.filePath,
+      relativePath,
+      bytesWritten,
+      overwritten: overwrite,
+      maxBytes,
+    },
+  };
+}
+
 export async function executeIssueActivity(client, params) {
   const issue = ensureNonEmpty(params.issue, 'issue');
   const activityData = await fetchIssueActivity(client, issue, {
@@ -508,13 +890,18 @@ export async function executeIssueComment(client, params) {
   const issue = ensureNonEmpty(params.issue, 'issue');
   const body = ensureNonEmpty(params.body, 'body');
   const result = await addIssueComment(client, issue, body, params.parentCommentId);
+  const commentBody = String(result.comment?.body || body).trim();
+  const preview = formatCommentPreview(commentBody);
 
   return toTextResult(
-    `Added comment to issue ${result.issue.identifier}`,
+    `Added comment to issue ${result.issue.identifier}\n\n${preview.text}`,
     {
       issueId: result.issue.id,
       identifier: result.issue.identifier,
       commentId: result.comment.id,
+      commentBody,
+      commentPreview: preview.text,
+      commentPreviewTruncated: preview.truncated,
     }
   );
 }

package/src/linear-client.js

@@ -11,7 +11,11 @@ import { debug, warn, info } from './logger.js';
 /** @type {Function|null} Test-only client factory override */
 let _testClientFactory = null;
 
-/** @type {Map<string, {remaining: number, resetAt: number}>} Per-client rate limit tracking */
+const DEFAULT_REQUEST_LIMIT = 5000;
+const LOW_RATE_LIMIT_THRESHOLD = 0.10;
+const RATE_LIMIT_WARN_MIN_MS = 30000;
+
+/** @type {Map<string, {limit: number, remaining: number, resetAt: number, lastWarnAt?: number}>} Per-client request rate limit tracking */
 const rateLimitTracker = new Map();
 
 /** @type {Map<string, {total: number, success: number, failed: number, rateLimited: number, windowStart: number, lastSummaryAt: number}>} */
@@ -32,6 +36,33 @@ function getTrackerKeyFromClient(client) {
   return client?.__piLinearTrackerKey || client?.apiKey || 'default';
 }
 
+function parseHeaderNumber(value) {
+  if (value === null || value === undefined) return null;
+  const parsed = Number.parseInt(String(value), 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function getTrackerLimit(tracker) {
+  return tracker?.limit || tracker?.total || DEFAULT_REQUEST_LIMIT;
+}
+
+function getUsedRequests(tracker) {
+  const limit = getTrackerLimit(tracker);
+  const remaining = tracker?.remaining;
+  if (!Number.isFinite(remaining)) return 0;
+  return Math.max(0, limit - remaining);
+}
+
+function getUsagePercent(tracker) {
+  const limit = getTrackerLimit(tracker);
+  if (!limit) return null;
+  return Math.round((getUsedRequests(tracker) / limit) * 100);
+}
+
+function getLowRequestThreshold(tracker) {
+  return Math.max(1, Math.floor(getTrackerLimit(tracker) * LOW_RATE_LIMIT_THRESHOLD));
+}
+
 function getRequestMetric(trackerKey) {
   let metric = requestMetrics.get(trackerKey);
   if (!metric) {
@@ -60,7 +91,8 @@ function maybeLogRequestSummary(trackerKey) {
   if (!shouldLogByCount && !shouldLogByTime) return;
 
   metric.lastSummaryAt = now;
-  const used = Math.max(0, 5000 - (tracker.remaining ?? 5000));
+  const used = getUsedRequests(tracker);
+  const limit = getTrackerLimit(tracker);
 
   info('[pi-linear-tools] Linear API usage summary', {
     trackerKey,
@@ -68,6 +100,7 @@ function maybeLogRequestSummary(trackerKey) {
     requestsSuccess: metric.success,
     requestsFailed: metric.failed,
     requestsRateLimited: metric.rateLimited,
+    requestsLimit: limit,
     requestsRemaining: tracker.remaining,
     requestsUsed: used,
     resetAt: tracker.resetAt,
@@ -125,19 +158,20 @@ export function markRateLimited(resetAt) {
  * Extract rate limit info from SDK client response
  * The Linear SDK stores response metadata on the client after requests
  * @param {LinearClient} client - Linear SDK client
- * @returns {{remaining: number|null, resetAt: number|null, resetTime: string|null}}
+ * @returns {{limit: number|null, remaining: number|null, resetAt: number|null, resetTime: string|null}}
  */
 export function getClientRateLimit(client) {
   const trackerData = rateLimitTracker.get(getTrackerKeyFromClient(client));
   if (trackerData) {
     return {
+      limit: getTrackerLimit(trackerData),
       remaining: trackerData.remaining,
       resetAt: trackerData.resetAt,
       resetTime: trackerData.resetAt ? new Date(trackerData.resetAt).toLocaleTimeString() : null,
     };
   }
 
-  return { remaining: null, resetAt: null, resetTime: null };
+  return { limit: null, remaining: null, resetAt: null, resetTime: null };
 }
 
 /**
@@ -147,12 +181,12 @@ export function getClientRateLimit(client) {
  */
 export function getClientRateLimitInfo(client) {
   const trackerData = rateLimitTracker.get(getTrackerKeyFromClient(client));
-  const total = 5000; // Linear's hourly request limit
+  const total = getTrackerLimit(trackerData);
 
   if (trackerData && trackerData.remaining !== undefined) {
     const remaining = trackerData.remaining;
-    const used = Math.max(0, total - remaining);
-    const usagePercent = Math.round((used / total) * 100);
+    const used = getUsedRequests(trackerData);
+    const usagePercent = getUsagePercent(trackerData);
 
     return {
       remaining,
@@ -206,11 +240,12 @@ export function getClientRequestMetrics(client) {
  * @returns {boolean} True if warning was issued
  */
 export function checkAndWarnRateLimit(client) {
-  const { remaining, resetTime } = getClientRateLimit(client);
+  const rateLimitInfo = getClientRateLimitInfo(client);
+  const { remaining, resetTime, usagePercent } = rateLimitInfo;
 
-  if (remaining !== null && remaining <= 500) {
-    const usagePercent = Math.round(((5000 - remaining) / 5000) * 100);
+  if (remaining !== null && remaining <= getLowRequestThreshold(rateLimitInfo)) {
     warn(`Linear API rate limit running low: ${remaining} requests remaining (~${usagePercent}% used). Resets at ${resetTime}`, {
+      limit: rateLimitInfo.total,
       remaining,
       resetTime,
       usagePercent,
@@ -267,7 +302,12 @@ export function createLinearClient(auth) {
   const trackerKey = getTrackerKey(apiKey);
   client.__piLinearTrackerKey = trackerKey;
   if (!rateLimitTracker.has(trackerKey)) {
-    rateLimitTracker.set(trackerKey, { remaining: 5000, resetAt: Date.now() + 3600000 });
+    rateLimitTracker.set(trackerKey, {
+      limit: DEFAULT_REQUEST_LIMIT,
+      remaining: DEFAULT_REQUEST_LIMIT,
+      resetAt: Date.now() + 3600000,
+      lastWarnAt: 0,
+    });
   }
   getRequestMetric(trackerKey);
 
@@ -288,22 +328,34 @@ export function createLinearClient(auth) {
       metric.success += 1;
 
       if (response.headers) {
-        const remaining = response.headers.get('X-RateLimit-Requests-Remaining');
-        const resetAt = response.headers.get('X-RateLimit-Requests-Reset');
+        const limit = parseHeaderNumber(response.headers.get('X-RateLimit-Requests-Limit'));
+        const remaining = parseHeaderNumber(response.headers.get('X-RateLimit-Requests-Remaining'));
+        const resetAt = parseHeaderNumber(response.headers.get('X-RateLimit-Requests-Reset'));
 
         const tracker = rateLimitTracker.get(trackerKey);
+        if (tracker && limit !== null) {
+          tracker.limit = limit;
+        }
         if (tracker && remaining !== null) {
-          tracker.remaining = parseInt(remaining, 10);
+          tracker.remaining = remaining;
         }
         if (tracker && resetAt !== null) {
-          tracker.resetAt = parseInt(resetAt, 10);
+          tracker.resetAt = resetAt;
         }
       }
 
       const tracker = rateLimitTracker.get(trackerKey);
-      if (tracker && tracker.remaining <= 500 && tracker.remaining > 0) {
-        const usagePercent = Math.round(((5000 - tracker.remaining) / 5000) * 100);
+      const now = Date.now();
+      if (
+        tracker &&
+        tracker.remaining <= getLowRequestThreshold(tracker) &&
+        tracker.remaining > 0 &&
+        now - (tracker.lastWarnAt || 0) >= RATE_LIMIT_WARN_MIN_MS
+      ) {
+        tracker.lastWarnAt = now;
+        const usagePercent = getUsagePercent(tracker);
         warn(`Linear API rate limit running low: ${tracker.remaining} requests remaining (~${usagePercent}% used). Resets at ${new Date(tracker.resetAt).toLocaleTimeString()}`, {
+          limit: getTrackerLimit(tracker),
           remaining: tracker.remaining,
           resetTime: new Date(tracker.resetAt).toLocaleTimeString(),
           usagePercent,
@@ -322,9 +374,12 @@ export function createLinearClient(auth) {
         metric.rateLimited += 1;
         const resetAt = Number(error?.requestsResetAt) || Date.now() + 3600000;
         const remaining = Number.isFinite(error?.requestsRemaining) ? error.requestsRemaining : 0;
+        const previousTracker = rateLimitTracker.get(trackerKey);
         rateLimitTracker.set(trackerKey, {
+          limit: getTrackerLimit(previousTracker),
           remaining,
           resetAt,
+          lastWarnAt: previousTracker?.lastWarnAt || 0,
         });
         markRateLimited(resetAt);
       }