@fink-andreas/pi-linear-tools 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## v0.4.2 (2026-03-26)
+
+Rate-limit resilience and API usage diagnostics release.
+
+### Bug Fixes
+- Hardened issue update flow when post-mutation refresh is rate-limited
+- Added explicit user-facing note when update succeeded but refresh is partial due to rate limits
+- Fixed per-command API usage metric keying so usage deltas report correctly
+
+### Performance / API Usage
+- Added short-lived in-memory caches for viewer, project list, team list, and team workflow states
+- Added direct-ID fast paths for project/team resolution to avoid full list fetches
+
+### Diagnostics
+- Added optional per-command usage summary output via `PI_LINEAR_TOOLS_USAGE_SUMMARY=true`
+- Added debug-level per-command request delta logging across issue/project/team/milestone tools
+
+### Documentation / Tests
+- Documented new diagnostics flag and cache behavior
+- Added regression tests for rate-limit fallback and API usage caching
+
 ## v0.4.0 (2026-03-23)
 
 Comprehensive error handling and file-first logging release.

package/README.md

@@ -7,14 +7,13 @@
 ### As a pi package (recommended)
 ```bash
 pi install npm:@fink-andreas/pi-linear-tools
-pi config
 ```
-Enable the `pi-linear-tools` extension resource.
 
 ### As an npm package
 ```bash
 npm install -g @fink-andreas/pi-linear-tools
 ```
+Use pi-linear-tools as a CLI tool.
 
 ## Initial configuration
 
@@ -54,10 +53,9 @@ Actions: `list`, `view`, `create`, `update`, `delete`
 
 ## CLI usage
 
-If installed globally via npm, you can run:
+If installed globally via ```npm install -g @fink-andreas/pi-linear-tools```, CLI command ```pi-linear-tools``` is available:
 
 ```bash
-npm install -g @fink-andreas/pi-linear-tools
 pi-linear-tools --help
 pi-linear-tools config
 pi-linear-tools config --api-key lin_xxx
@@ -65,12 +63,6 @@ pi-linear-tools config --default-team ENG
 pi-linear-tools config --team ENG --project "My Project"
 ```
 
-If `pi-linear-tools` is not found, run it from the repo:
-
-```bash
-node bin/pi-linear-tools.js --help
-```
-
 ### Issue commands
 
 ```bash
@@ -144,6 +136,12 @@ Settings path:
 Environment fallback:
 - `LINEAR_API_KEY` (takes precedence over settings)
 
+Debug/diagnostics environment flags:
+- `PI_LINEAR_TOOLS_USAGE_SUMMARY=true` — append per-command Linear API usage summary to tool output markdown and include `details.apiUsage`
+- `LOG_LEVEL=debug` — enable detailed file logging
+- `PI_LINEAR_TOOLS_LOG_TO_CONSOLE=true` — mirror logs to console (normally file-first logging)
+- `PI_LINEAR_TOOLS_LOG_FILE=/custom/path.log` — override log file path
+
 ## Development
 
 ```bash

package/extensions/pi-linear-tools.js

@@ -1,6 +1,6 @@
 import { loadSettings, saveSettings } from '../src/settings.js';
-import { createLinearClient, checkAndClearRateLimit, markRateLimited } from '../src/linear-client.js';
-import { setQuietMode } from '../src/logger.js';
+import { createLinearClient, checkAndClearRateLimit, markRateLimited, getClientRequestMetrics } from '../src/linear-client.js';
+import { setQuietMode, debug } from '../src/logger.js';
 import {
   resolveProjectRef,
   fetchTeams,
@@ -65,6 +65,7 @@ import { authenticate, getAccessToken, logout } from '../src/auth/index.js';
 import { withMilestoneScopeHint } from '../src/error-hints.js';
 
 let cachedApiKey = null;
+const INCLUDE_USAGE_SUMMARY = String(process.env.PI_LINEAR_TOOLS_USAGE_SUMMARY || '').toLowerCase() === 'true';
 
 async function getLinearAuth() {
   const envKey = process.env.LINEAR_API_KEY;
@@ -106,6 +107,65 @@ async function createAuthenticatedClient() {
   return createLinearClient(await getLinearAuth());
 }
 
+async function withRequestUsageLogging(client, toolName, action, operation) {
+  const before = getClientRequestMetrics(client);
+
+  try {
+    const result = await operation();
+    const after = getClientRequestMetrics(client);
+
+    const usageDelta = {
+      tool: toolName,
+      action,
+      requestsDelta: after.total - before.total,
+      successDelta: after.success - before.success,
+      failedDelta: after.failed - before.failed,
+      rateLimitedDelta: after.rateLimited - before.rateLimited,
+      summary: `Linear API usage: ${after.total - before.total} req (${after.success - before.success} ok, ${after.failed - before.failed} failed, ${after.rateLimited - before.rateLimited} rate-limited)`,
+    };
+
+    debug('[pi-linear-tools] API usage per command', usageDelta);
+
+    if (!INCLUDE_USAGE_SUMMARY || !result || typeof result !== 'object') {
+      return result;
+    }
+
+    const details = (result.details && typeof result.details === 'object') ? 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;
+        return {
+          ...item,
+          text: `${item.text}\n\n_${usageDelta.summary}_`,
+        };
+      })
+      : result.content;
+
+    return {
+      ...result,
+      content,
+      details: {
+        ...details,
+        apiUsage: usageDelta,
+      },
+    };
+  } catch (error) {
+    const after = getClientRequestMetrics(client);
+
+    debug('[pi-linear-tools] API usage per command (error)', {
+      tool: toolName,
+      action,
+      requestsDelta: after.total - before.total,
+      successDelta: after.success - before.success,
+      failedDelta: after.failed - before.failed,
+      rateLimitedDelta: after.rateLimited - before.rateLimited,
+      error: String(error?.message || error || 'unknown'),
+    });
+
+    throw error;
+  }
+}
+
 async function resolveDefaultTeam(projectId) {
   const settings = await loadSettings();
 
@@ -552,28 +612,30 @@ async function registerLinearTools(pi) {
       try {
         const client = await createAuthenticatedClient();
 
-        switch (params.action) {
-          case 'list':
-            return await executeIssueList(client, params);
-          case 'view':
-            return await executeIssueView(client, params);
-          case 'create':
-            return await executeIssueCreate(client, params, { resolveDefaultTeam });
-          case 'update':
-            return await executeIssueUpdate(client, params);
-          case 'comment':
-            return await executeIssueComment(client, params);
-          case 'start':
-            return await executeIssueStart(client, params, {
-              gitExecutor: async (branchName, fromRef, onBranchExists) => {
-                return startGitBranchForIssue(pi, branchName, fromRef, onBranchExists);
-              },
-            });
-          case 'delete':
-            return await executeIssueDelete(client, params);
-          default:
-            throw new Error(`Unknown action: ${params.action}`);
-        }
+        return await withRequestUsageLogging(client, 'linear_issue', params.action, async () => {
+          switch (params.action) {
+            case 'list':
+              return await executeIssueList(client, params);
+            case 'view':
+              return await executeIssueView(client, params);
+            case 'create':
+              return await executeIssueCreate(client, params, { resolveDefaultTeam });
+            case 'update':
+              return await executeIssueUpdate(client, params);
+            case 'comment':
+              return await executeIssueComment(client, params);
+            case 'start':
+              return await executeIssueStart(client, params, {
+                gitExecutor: async (branchName, fromRef, onBranchExists) => {
+                  return startGitBranchForIssue(pi, branchName, fromRef, onBranchExists);
+                },
+              });
+            case 'delete':
+              return await executeIssueDelete(client, params);
+            default:
+              throw new Error(`Unknown action: ${params.action}`);
+          }
+        });
       } catch (error) {
         // Comprehensive error handling - catch ALL errors including SDK's RatelimitedLinearError
         const errorType = error?.type || '';
@@ -648,12 +710,14 @@ async function registerLinearTools(pi) {
       try {
         const client = await createAuthenticatedClient();
 
-        switch (params.action) {
-          case 'list':
-            return await executeProjectList(client);
-          default:
-            throw new Error(`Unknown action: ${params.action}`);
-        }
+        return await withRequestUsageLogging(client, 'linear_project', params.action, async () => {
+          switch (params.action) {
+            case 'list':
+              return await executeProjectList(client);
+            default:
+              throw new Error(`Unknown action: ${params.action}`);
+          }
+        });
       } catch (error) {
         // Comprehensive error handling - catch ALL errors
         const errorType = error?.type || '';
@@ -696,12 +760,14 @@ async function registerLinearTools(pi) {
       try {
         const client = await createAuthenticatedClient();
 
-        switch (params.action) {
-          case 'list':
-            return await executeTeamList(client);
-          default:
-            throw new Error(`Unknown action: ${params.action}`);
-        }
+        return await withRequestUsageLogging(client, 'linear_team', params.action, async () => {
+          switch (params.action) {
+            case 'list':
+              return await executeTeamList(client);
+            default:
+              throw new Error(`Unknown action: ${params.action}`);
+          }
+        });
       } catch (error) {
         // Comprehensive error handling - catch ALL errors
         const errorType = error?.type || '';
@@ -765,20 +831,22 @@ async function registerLinearTools(pi) {
         try {
           const client = await createAuthenticatedClient();
 
-          switch (params.action) {
-            case 'list':
-              return await executeMilestoneList(client, params);
-            case 'view':
-              return await executeMilestoneView(client, params);
-            case 'create':
-              return await executeMilestoneCreate(client, params);
-            case 'update':
-              return await executeMilestoneUpdate(client, params);
-            case 'delete':
-              return await executeMilestoneDelete(client, params);
-            default:
-              throw new Error(`Unknown action: ${params.action}`);
-          }
+          return await withRequestUsageLogging(client, 'linear_milestone', params.action, async () => {
+            switch (params.action) {
+              case 'list':
+                return await executeMilestoneList(client, params);
+              case 'view':
+                return await executeMilestoneView(client, params);
+              case 'create':
+                return await executeMilestoneCreate(client, params);
+              case 'update':
+                return await executeMilestoneUpdate(client, params);
+              case 'delete':
+                return await executeMilestoneDelete(client, params);
+              default:
+                throw new Error(`Unknown action: ${params.action}`);
+            }
+          });
         } catch (error) {
           // Apply milestone-specific hint, then wrap with operation context
           const hintError = withMilestoneScopeHint(error);

package/index.js

@@ -1,6 +1,6 @@
 import { loadSettings, saveSettings } from './src/settings.js';
-import { createLinearClient, checkAndClearRateLimit, markRateLimited } from './src/linear-client.js';
-import { setQuietMode } from './src/logger.js';
+import { createLinearClient, checkAndClearRateLimit, markRateLimited, getClientRequestMetrics } from './src/linear-client.js';
+import { setQuietMode, debug } from './src/logger.js';
 import {
   resolveProjectRef,
   fetchTeams,
@@ -65,6 +65,7 @@ import { authenticate, getAccessToken, logout } from './src/auth/index.js';
 import { withMilestoneScopeHint } from './src/error-hints.js';
 
 let cachedApiKey = null;
+const INCLUDE_USAGE_SUMMARY = String(process.env.PI_LINEAR_TOOLS_USAGE_SUMMARY || '').toLowerCase() === 'true';
 
 async function getLinearAuth() {
   const envKey = process.env.LINEAR_API_KEY;
@@ -106,6 +107,65 @@ async function createAuthenticatedClient() {
   return createLinearClient(await getLinearAuth());
 }
 
+async function withRequestUsageLogging(client, toolName, action, operation) {
+  const before = getClientRequestMetrics(client);
+
+  try {
+    const result = await operation();
+    const after = getClientRequestMetrics(client);
+
+    const usageDelta = {
+      tool: toolName,
+      action,
+      requestsDelta: after.total - before.total,
+      successDelta: after.success - before.success,
+      failedDelta: after.failed - before.failed,
+      rateLimitedDelta: after.rateLimited - before.rateLimited,
+      summary: `Linear API usage: ${after.total - before.total} req (${after.success - before.success} ok, ${after.failed - before.failed} failed, ${after.rateLimited - before.rateLimited} rate-limited)`,
+    };
+
+    debug('[pi-linear-tools] API usage per command', usageDelta);
+
+    if (!INCLUDE_USAGE_SUMMARY || !result || typeof result !== 'object') {
+      return result;
+    }
+
+    const details = (result.details && typeof result.details === 'object') ? 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;
+        return {
+          ...item,
+          text: `${item.text}\n\n_${usageDelta.summary}_`,
+        };
+      })
+      : result.content;
+
+    return {
+      ...result,
+      content,
+      details: {
+        ...details,
+        apiUsage: usageDelta,
+      },
+    };
+  } catch (error) {
+    const after = getClientRequestMetrics(client);
+
+    debug('[pi-linear-tools] API usage per command (error)', {
+      tool: toolName,
+      action,
+      requestsDelta: after.total - before.total,
+      successDelta: after.success - before.success,
+      failedDelta: after.failed - before.failed,
+      rateLimitedDelta: after.rateLimited - before.rateLimited,
+      error: String(error?.message || error || 'unknown'),
+    });
+
+    throw error;
+  }
+}
+
 async function resolveDefaultTeam(projectId) {
   const settings = await loadSettings();
 
@@ -552,28 +612,30 @@ async function registerLinearTools(pi) {
       try {
         const client = await createAuthenticatedClient();
 
-        switch (params.action) {
-          case 'list':
-            return await executeIssueList(client, params);
-          case 'view':
-            return await executeIssueView(client, params);
-          case 'create':
-            return await executeIssueCreate(client, params, { resolveDefaultTeam });
-          case 'update':
-            return await executeIssueUpdate(client, params);
-          case 'comment':
-            return await executeIssueComment(client, params);
-          case 'start':
-            return await executeIssueStart(client, params, {
-              gitExecutor: async (branchName, fromRef, onBranchExists) => {
-                return startGitBranchForIssue(pi, branchName, fromRef, onBranchExists);
-              },
-            });
-          case 'delete':
-            return await executeIssueDelete(client, params);
-          default:
-            throw new Error(`Unknown action: ${params.action}`);
-        }
+        return await withRequestUsageLogging(client, 'linear_issue', params.action, async () => {
+          switch (params.action) {
+            case 'list':
+              return await executeIssueList(client, params);
+            case 'view':
+              return await executeIssueView(client, params);
+            case 'create':
+              return await executeIssueCreate(client, params, { resolveDefaultTeam });
+            case 'update':
+              return await executeIssueUpdate(client, params);
+            case 'comment':
+              return await executeIssueComment(client, params);
+            case 'start':
+              return await executeIssueStart(client, params, {
+                gitExecutor: async (branchName, fromRef, onBranchExists) => {
+                  return startGitBranchForIssue(pi, branchName, fromRef, onBranchExists);
+                },
+              });
+            case 'delete':
+              return await executeIssueDelete(client, params);
+            default:
+              throw new Error(`Unknown action: ${params.action}`);
+          }
+        });
       } catch (error) {
         // Comprehensive error handling - catch ALL errors including SDK's RatelimitedLinearError
         const errorType = error?.type || '';
@@ -648,12 +710,14 @@ async function registerLinearTools(pi) {
       try {
         const client = await createAuthenticatedClient();
 
-        switch (params.action) {
-          case 'list':
-            return await executeProjectList(client);
-          default:
-            throw new Error(`Unknown action: ${params.action}`);
-        }
+        return await withRequestUsageLogging(client, 'linear_project', params.action, async () => {
+          switch (params.action) {
+            case 'list':
+              return await executeProjectList(client);
+            default:
+              throw new Error(`Unknown action: ${params.action}`);
+          }
+        });
       } catch (error) {
         // Comprehensive error handling - catch ALL errors
         const errorType = error?.type || '';
@@ -696,12 +760,14 @@ async function registerLinearTools(pi) {
       try {
         const client = await createAuthenticatedClient();
 
-        switch (params.action) {
-          case 'list':
-            return await executeTeamList(client);
-          default:
-            throw new Error(`Unknown action: ${params.action}`);
-        }
+        return await withRequestUsageLogging(client, 'linear_team', params.action, async () => {
+          switch (params.action) {
+            case 'list':
+              return await executeTeamList(client);
+            default:
+              throw new Error(`Unknown action: ${params.action}`);
+          }
+        });
       } catch (error) {
         // Comprehensive error handling - catch ALL errors
         const errorType = error?.type || '';
@@ -765,20 +831,22 @@ async function registerLinearTools(pi) {
         try {
           const client = await createAuthenticatedClient();
 
-          switch (params.action) {
-            case 'list':
-              return await executeMilestoneList(client, params);
-            case 'view':
-              return await executeMilestoneView(client, params);
-            case 'create':
-              return await executeMilestoneCreate(client, params);
-            case 'update':
-              return await executeMilestoneUpdate(client, params);
-            case 'delete':
-              return await executeMilestoneDelete(client, params);
-            default:
-              throw new Error(`Unknown action: ${params.action}`);
-          }
+          return await withRequestUsageLogging(client, 'linear_milestone', params.action, async () => {
+            switch (params.action) {
+              case 'list':
+                return await executeMilestoneList(client, params);
+              case 'view':
+                return await executeMilestoneView(client, params);
+              case 'create':
+                return await executeMilestoneCreate(client, params);
+              case 'update':
+                return await executeMilestoneUpdate(client, params);
+              case 'delete':
+                return await executeMilestoneDelete(client, params);
+              default:
+                throw new Error(`Unknown action: ${params.action}`);
+            }
+          });
         } catch (error) {
           // Apply milestone-specific hint, then wrap with operation context
           const hintError = withMilestoneScopeHint(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fink-andreas/pi-linear-tools",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Pi extension with Linear SDK tools and configuration commands",
   "type": "module",
   "engines": {
@@ -27,7 +27,7 @@
   },
   "scripts": {
     "start": "node index.js",
-    "test": "node tests/test-package-manifest.js && node tests/test-extension-registration.js && node tests/test-settings.js && node tests/test-assignee-update.js && node tests/test-full-assignee-flow.js && node tests/test-branch-param.js",
+    "test": "node tests/test-package-manifest.js && node tests/test-extension-registration.js && node tests/test-settings.js && node tests/test-api-usage-caching.js && node tests/test-assignee-update.js && node tests/test-rate-limit-fallback-update.js && node tests/test-full-assignee-flow.js && node tests/test-branch-param.js && node tests/test-team-filter.js",
     "dev:sync-local-extension": "node scripts/dev-sync-local-extension.mjs",
     "release:check": "npm test && npm pack --dry-run"
   },
@@ -44,6 +44,10 @@
     ]
   },
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fink-andreas/pi-linear-tools.git"
+  },
   "dependencies": {
     "@linear/sdk": "^75.0.0",
     "@github/keytar": "^7.10.6"

package/src/cli.js

@@ -149,7 +149,7 @@ Auth Actions:
   status   Show current authentication status
 
 Issue Actions:
-  list [--project X] [--states X,Y] [--assignee me|all] [--limit N]
+  list [--project X] [--states X,Y] [--assignee me|all] [--team X] [--limit N]
   view <issue> [--no-comments]
   create --title X [--team X] [--project X] [--description X] [--priority 0-4] [--assignee me|ID]
   update <issue> [--title X] [--description X] [--state X] [--priority 0-4]
@@ -217,6 +217,7 @@ List Options:
   --project X      Project name or ID (default: current directory name)
   --states X,Y     Filter by state names (comma-separated)
   --assignee X     Filter by assignee: "me" or "all"
+  --team X         Filter by team key (e.g., ENG) or ID
   --limit N        Max results (default: 50)
 
 View Options:
@@ -531,6 +532,7 @@ async function handleIssueList(args) {
     project: readFlag(args, '--project'),
     states: parseArrayValue(readFlag(args, '--states')),
     assignee: readFlag(args, '--assignee'),
+    team: readFlag(args, '--team'),
     limit: parseNumber(readFlag(args, '--limit')),
   };
 

package/src/handlers.js

@@ -27,6 +27,7 @@ import {
   deleteProjectMilestone,
   deleteIssue,
   withHandlerErrorHandling,
+  getViewer,
 } from './linear.js';
 import { debug } from './logger.js';
 
@@ -130,6 +131,14 @@ async function startGitBranch(branchName, fromRef = 'HEAD', onBranchExists = 'sw
 
 /**
  * List issues in a project
+ * @param {LinearClient} client - Linear SDK client
+ * @param {Object} params - Parameters
+ * @param {string} [params.project] - Project name or ID
+ * @param {string[]} [params.states] - State names to filter by
+ * @param {string} [params.assignee] - "me" or "all" for assignee filtering
+ * @param {string} [params.team] - Team key or ID to filter by
+ * @param {number} [params.limit] - Maximum results (default: 20)
+ * @returns {Promise<{content: Array, details: Object}>}
  */
 export async function executeIssueList(client, params) {
   return withHandlerErrorHandling(async () => {
@@ -142,12 +151,20 @@ export async function executeIssueList(client, params) {
 
     let assigneeId = null;
     if (params.assignee === 'me') {
-      const viewer = await client.viewer;
+      const viewer = await getViewer(client);
       assigneeId = viewer.id;
     }
 
+    // Resolve team if provided
+    let teamId = null;
+    if (params.team) {
+      const team = await resolveTeamRef(client, params.team);
+      teamId = team.id;
+    }
+
     const { issues, truncated } = await fetchIssuesByProject(client, resolved.id, params.states || null, {
       assigneeId,
+      teamId,
       limit: params.limit || 20,
     });
 
@@ -260,7 +277,7 @@ export async function executeIssueCreate(client, params, options = {}) {
   }
 
   if (params.assignee === 'me') {
-    const viewer = await client.viewer;
+    const viewer = await getViewer(client);
     createInput.assigneeId = viewer.id;
   } else if (params.assignee) {
     createInput.assigneeId = params.assignee;
@@ -358,7 +375,7 @@ export async function executeIssueUpdate(client, params) {
 
   // Handle assignee parameter
   if (params.assignee === 'me') {
-    const viewer = await client.viewer;
+    const viewer = await getViewer(client);
     updatePatch.assigneeId = viewer.id;
   } else if (params.assignee) {
     updatePatch.assigneeId = params.assignee;
@@ -413,8 +430,12 @@ export async function executeIssueUpdate(client, params) {
     ? ` (${changeSummaryParts.join(', ')})`
     : '';
 
+  const rateLimitNote = result.usedRateLimitFallback
+    ? '\n\n_Note: update succeeded, but detailed issue refresh was rate-limited. Some returned fields may be partial until rate limit resets._'
+    : '';
+
   return toTextResult(
-    `Updated issue ${result.issue.identifier}${suffix}`,
+    `Updated issue ${result.issue.identifier}${suffix}${rateLimitNote}`,
     {
       issueId: result.issue.id,
       identifier: result.issue.identifier,
@@ -422,6 +443,7 @@ export async function executeIssueUpdate(client, params) {
       state: result.issue.state,
       priority: result.issue.priority,
       projectMilestone: result.issue.projectMilestone,
+      usedRateLimitFallback: !!result.usedRateLimitFallback,
     }
   );
 }

package/src/linear-client.js

@@ -28,6 +28,10 @@ function getTrackerKey(apiKey) {
   return apiKey || 'default';
 }
 
+function getTrackerKeyFromClient(client) {
+  return client?.__piLinearTrackerKey || client?.apiKey || 'default';
+}
+
 function getRequestMetric(trackerKey) {
   let metric = requestMetrics.get(trackerKey);
   if (!metric) {
@@ -124,7 +128,7 @@ export function markRateLimited(resetAt) {
  * @returns {{remaining: number|null, resetAt: number|null, resetTime: string|null}}
  */
 export function getClientRateLimit(client) {
-  const trackerData = rateLimitTracker.get(client.apiKey || 'default');
+  const trackerData = rateLimitTracker.get(getTrackerKeyFromClient(client));
   if (trackerData) {
     return {
       remaining: trackerData.remaining,
@@ -140,7 +144,7 @@ export function getClientRateLimit(client) {
  * Expose per-client request counters for diagnostics
  */
 export function getClientRequestMetrics(client) {
-  const key = client?.apiKey || 'default';
+  const key = getTrackerKeyFromClient(client);
   const metric = requestMetrics.get(key);
   if (!metric) {
     return {
@@ -227,6 +231,7 @@ export function createLinearClient(auth) {
   const client = new LinearClient(clientConfig);
 
   const trackerKey = getTrackerKey(apiKey);
+  client.__piLinearTrackerKey = trackerKey;
   if (!rateLimitTracker.has(trackerKey)) {
     rateLimitTracker.set(trackerKey, { remaining: 5000, resetAt: Date.now() + 3600000 });
   }

package/src/linear.js

@@ -7,6 +7,39 @@
 
 import { warn, info, debug } from './logger.js';
 
+const CACHE_TTL_MS = {
+  viewer: 30_000,
+  projects: 60_000,
+  teams: 60_000,
+  teamStates: 60_000,
+};
+
+const viewerCache = new Map();
+const projectsCache = new Map();
+const teamsCache = new Map();
+const teamStatesCache = new Map();
+
+function getClientCacheKey(client) {
+  return client?.apiKey || 'default';
+}
+
+function getCache(map, key) {
+  const entry = map.get(key);
+  if (!entry) return null;
+  if (Date.now() > entry.expiresAt) {
+    map.delete(key);
+    return null;
+  }
+  return entry.value;
+}
+
+function setCache(map, key, value, ttlMs) {
+  map.set(key, {
+    value,
+    expiresAt: Date.now() + ttlMs,
+  });
+}
+
 // ===== OPTIMIZED GRAPHQL QUERIES =====
 // These queries fetch relations upfront to avoid N+1 API calls
 
@@ -510,15 +543,24 @@ function normalizeIssueRefList(value) {
  */
 export async function fetchViewer(client) {
   return withLinearErrorHandling(async () => {
+    const cacheKey = getClientCacheKey(client);
+    const cached = getCache(viewerCache, cacheKey);
+    if (cached) return cached;
+
     const viewer = await client.viewer;
-    return {
+    const result = {
       id: viewer.id,
       name: viewer.name,
       displayName: viewer.displayName,
     };
+
+    setCache(viewerCache, cacheKey, result, CACHE_TTL_MS.viewer);
+    return result;
   }, 'fetchViewer');
 }
 
+export const getViewer = fetchViewer;
+
 /**
  * Fetch issues in specific states, optionally filtered by assignee
  * OPTIMIZED: Uses rawRequest with custom GraphQL to fetch all relations in ONE request
@@ -580,12 +622,13 @@ export async function fetchIssues(client, assigneeId, openStates, limit) {
  * @param {Array<string>|null} states - List of state names to include (null = all states)
  * @param {Object} options
  * @param {string|null} options.assigneeId - Assignee ID to filter by (null = all assignees)
+ * @param {string|null} options.teamId - Team ID to filter by (null = all teams)
  * @param {number} options.limit - Maximum number of issues to fetch
  * @returns {Promise<{issues: Array, truncated: boolean}>}
  */
 export async function fetchIssuesByProject(client, projectId, states, options = {}) {
   return withLinearErrorHandling(async () => {
-    const { assigneeId = null, limit = 20 } = options;
+    const { assigneeId = null, teamId = null, limit = 20 } = options;
 
     const filter = {
       project: { id: { eq: projectId } },
@@ -599,6 +642,10 @@ export async function fetchIssuesByProject(client, projectId, states, options =
       filter.assignee = { id: { eq: assigneeId } };
     }
 
+    if (teamId) {
+      filter.team = { id: { eq: teamId } };
+    }
+
     // Use optimized rawRequest to fetch issues with ALL relations in ONE request
     // This eliminates the N+1 problem where each issue triggered 5 additional API calls
     const { data } = await executeOptimizedQuery(client, ISSUES_WITH_RELATIONS_QUERY, {
@@ -643,6 +690,10 @@ export async function fetchIssuesByProject(client, projectId, states, options =
  */
 export async function fetchProjects(client) {
   return withLinearErrorHandling(async () => {
+    const cacheKey = getClientCacheKey(client);
+    const cached = getCache(projectsCache, cacheKey);
+    if (cached) return cached;
+
     const result = await client.projects();
     const nodes = result.nodes ?? [];
 
@@ -651,7 +702,9 @@ export async function fetchProjects(client) {
       projects: nodes.map((p) => ({ id: p.id, name: p.name })),
     });
 
-    return nodes.map(p => ({ id: p.id, name: p.name }));
+    const projects = nodes.map(p => ({ id: p.id, name: p.name }));
+    setCache(projectsCache, cacheKey, projects, CACHE_TTL_MS.projects);
+    return projects;
   }, 'fetchProjects');
 }
 
@@ -687,6 +740,10 @@ export async function fetchWorkspaces(client) {
  */
 export async function fetchTeams(client) {
   return withLinearErrorHandling(async () => {
+    const cacheKey = getClientCacheKey(client);
+    const cached = getCache(teamsCache, cacheKey);
+    if (cached) return cached;
+
     const result = await client.teams();
     const nodes = result.nodes ?? [];
 
@@ -695,7 +752,9 @@ export async function fetchTeams(client) {
       teams: nodes.map((t) => ({ id: t.id, key: t.key, name: t.name })),
     });
 
-    return nodes.map(t => ({ id: t.id, key: t.key, name: t.name }));
+    const teams = nodes.map(t => ({ id: t.id, key: t.key, name: t.name }));
+    setCache(teamsCache, cacheKey, teams, CACHE_TTL_MS.teams);
+    return teams;
   }, 'fetchTeams');
 }
 
@@ -711,10 +770,17 @@ export async function resolveTeamRef(client, teamRef) {
     throw new Error('Missing team reference');
   }
 
-  const teams = await fetchTeams(client);
-
-  // If it looks like a Linear ID (UUID), try direct lookup first
+  // If it looks like a Linear ID (UUID), try direct lookup first (cheap)
   if (isLinearId(ref)) {
+    try {
+      const direct = await client.team(ref);
+      if (direct) {
+        return { id: direct.id, key: direct.key, name: direct.name };
+      }
+    } catch {
+      // fall back to cached/full-team lookup below
+    }
+
     const byId = teams.find((t) => t.id === ref);
     if (byId) {
       return byId;
@@ -722,6 +788,8 @@ export async function resolveTeamRef(client, teamRef) {
     throw new Error(`Team not found with ID: ${ref}`);
   }
 
+  const teams = await fetchTeams(client);
+
   // Try exact key match (e.g., "ENG")
   const byKey = teams.find((t) => t.key === ref);
   if (byKey) {
@@ -778,17 +846,24 @@ export async function resolveIssue(client, issueRef) {
  */
 export async function getTeamWorkflowStates(client, teamRef) {
   return withLinearErrorHandling(async () => {
+    const cacheKey = `${getClientCacheKey(client)}::${teamRef}`;
+    const cached = getCache(teamStatesCache, cacheKey);
+    if (cached) return cached;
+
     const team = await client.team(teamRef);
     if (!team) {
       throw new Error(`Team not found: ${teamRef}`);
     }
 
     const states = await team.states();
-    return (states.nodes || []).map(s => ({
+    const mapped = (states.nodes || []).map(s => ({
       id: s.id,
       name: s.name,
       type: s.type,
     }));
+
+    setCache(teamStatesCache, cacheKey, mapped, CACHE_TTL_MS.teamStates);
+    return mapped;
   }, 'getTeamWorkflowStates');
 }
 
@@ -804,17 +879,27 @@ export async function resolveProjectRef(client, projectRef) {
     throw new Error('Missing project reference');
   }
 
-  const projects = await fetchProjects(client);
-
-  // If it looks like a Linear ID (UUID), try direct lookup first
+  // If it looks like a Linear ID (UUID), try direct lookup first (cheap)
   if (isLinearId(ref)) {
-    const byId = projects.find((p) => p.id === ref);
+    try {
+      const direct = await client.project(ref);
+      if (direct) {
+        return { id: direct.id, name: direct.name };
+      }
+    } catch {
+      // fall back to cached/full-project lookup below
+    }
+
+    const projectsById = await fetchProjects(client);
+    const byId = projectsById.find((p) => p.id === ref);
     if (byId) {
       return byId;
     }
     throw new Error(`Project not found with ID: ${ref}`);
   }
 
+  const projects = await fetchProjects(client);
+
   // Try exact name match
   const exactName = projects.find((p) => p.name === ref);
   if (exactName) {
@@ -1114,6 +1199,47 @@ export async function addIssueComment(client, issueRef, body, parentCommentId) {
  * @param {Object} patch - Fields to update
  * @returns {Promise<{issue: Object, changed: Array<string>}>}
  */
+function buildFallbackUpdatedIssue(targetIssue, updateInput) {
+  const fallback = { ...(targetIssue || {}) };
+
+  if (Object.prototype.hasOwnProperty.call(updateInput, 'title')) {
+    fallback.title = updateInput.title;
+  }
+  if (Object.prototype.hasOwnProperty.call(updateInput, 'description')) {
+    fallback.description = updateInput.description;
+  }
+  if (Object.prototype.hasOwnProperty.call(updateInput, 'priority')) {
+    fallback.priority = updateInput.priority;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(updateInput, 'assigneeId')) {
+    const assigneeId = updateInput.assigneeId;
+    if (assigneeId === null) {
+      fallback.assignee = null;
+    } else if (typeof assigneeId === 'string' && assigneeId.trim()) {
+      fallback.assignee = {
+        id: assigneeId,
+        name: fallback.assignee?.name || 'Unknown',
+        displayName: fallback.assignee?.displayName || 'Unknown',
+      };
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(updateInput, 'projectMilestoneId')) {
+    const milestoneId = updateInput.projectMilestoneId;
+    if (milestoneId === null) {
+      fallback.projectMilestone = null;
+    } else if (typeof milestoneId === 'string' && milestoneId.trim()) {
+      fallback.projectMilestone = {
+        id: milestoneId,
+        name: fallback.projectMilestone?.name || 'Unknown',
+      };
+    }
+  }
+
+  return fallback;
+}
+
 export async function updateIssue(client, issueRef, patch = {}) {
   return withLinearErrorHandling(async () => {
     const targetIssue = await resolveIssue(client, issueRef);
@@ -1275,14 +1401,28 @@ export async function updateIssue(client, issueRef, patch = {}) {
     }
 
     // Prefer official data path: refetch the issue after successful mutation.
-    let updatedSdkIssue = null;
+    // If this extra fetch is rate-limited, keep operation successful and return fallback data.
+    let updatedIssue = null;
+    let usedRateLimitFallback = false;
     try {
-      updatedSdkIssue = await client.issue(targetIssue.id);
-    } catch {
-      updatedSdkIssue = null;
-    }
+      const updatedSdkIssue = await client.issue(targetIssue.id);
+      updatedIssue = await transformIssue(updatedSdkIssue);
+    } catch (refreshError) {
+      const refreshMessage = String(refreshError?.message || refreshError || 'unknown');
+      const isRefreshRateLimited = refreshError?.type === 'Ratelimited' || refreshMessage.toLowerCase().includes('rate limit');
+
+      if (!isRefreshRateLimited) {
+        throw refreshError;
+      }
 
-    const updatedIssue = await transformIssue(updatedSdkIssue);
+      debug('updateIssue: post-update refresh was rate-limited; returning fallback issue payload', {
+        issueRef,
+        issueId: targetIssue?.id,
+      });
+
+      usedRateLimitFallback = true;
+      updatedIssue = buildFallbackUpdatedIssue(targetIssue, updateInput);
+    }
 
     const changed = [...Object.keys(updateInput)];
     if (parentOfRefs.length > 0) changed.push('parentOf');
@@ -1294,6 +1434,7 @@ export async function updateIssue(client, issueRef, patch = {}) {
     return {
       issue: updatedIssue || targetIssue,
       changed,
+      usedRateLimitFallback,
     };
   }, 'updateIssue');
 }

package/FUNCTIONALITY.md

@@ -1,57 +0,0 @@
-# pi-linear-tools Functionality
-
-## Scope
-
-`pi-linear-tools` provides Linear SDK functionality as a pi extension package.
-
-Included:
-- extension configuration command (`/linear-tools-config`)
-- issue/project/milestone tools powered by `@linear/sdk`
-- issue start flow with optional git branch creation/switch
-- settings persistence for API key/default team/project team mapping
-
-Excluded:
-- daemon runtime
-- polling loop
-- systemd service installation/control
-- tmux/process session management
-- RPC process lifecycle management
-
-## Core modules
-
-- `src/linear-client.js`: Linear SDK client factory
-- `src/linear.js`: issue/project/milestone operations and formatting helpers
-- `src/settings.js`: settings defaults/validation/load/save
-- `src/logger.js`: structured logging
-- `extensions/pi-linear-tools.js`: command and tool registration
-- `src/cli.js`: optional local CLI for settings operations
-
-## Tool behavior notes
-
-- `LINEAR_API_KEY` is resolved from env first, then settings
-- project references may be project name or project ID
-- issue references may be identifier (`ABC-123`) or Linear issue ID
-- default team resolution order for issue creation:
-  1. explicit `team` parameter
-  2. project-level configured team
-  3. global `defaultTeam`
-- `linear_issue` `start` action:
-  - uses Linear branch name if available
-  - can create/switch git branch via `pi.exec("git", ...)`
-
-## Settings schema
-
-```json
-{
-  "schemaVersion": 1,
-  "linearApiKey": null,
-  "defaultTeam": null,
-  "projects": {
-    "<linear-project-id>": {
-      "scope": {
-        "team": "ENG"
-      }
-    }
-  }
-}
-```

package/POST_RELEASE_CHECKLIST.md

@@ -1,30 +0,0 @@
-# Post-release verification checklist
-
-## Registry and install checks
-
-```bash
-npm view @fink-andreas/pi-linear-tools version
-npm install -g @fink-andreas/pi-linear-tools
-pi-linear-tools --help
-```
-
-## pi package route smoke test
-
-```bash
-pi install git:github.com/fink-andreas/pi-linear-tools
-# then enable extension resource and run
-/linear-tools-help
-```
-
-## Basic command smoke test
-
-```bash
-pi-linear-tools project list
-pi-linear-tools team list
-```
-
-## Closeout
-
-- Capture any regressions as follow-up Linear issues
-- Post release summary to INN-234
-- Mark milestone complete

package/RELEASE.md

@@ -1,50 +0,0 @@
-# Release Runbook
-
-## npm publish (`v0.1.0`)
-
-1. Ensure clean working tree
-   ```bash
-   git status
-   ```
-2. Run pre-publish checks
-   ```bash
-   npm run release:check
-   ```
-3. Verify npm authentication
-   ```bash
-   npm whoami
-   ```
-4. Publish package
-   ```bash
-   npm publish --access public
-   ```
-5. Verify published version
-   ```bash
-   npm view @fink-andreas/pi-linear-tools version
-   ```
-
-## Post-publish quick validation
-
-```bash
-npm install -g @fink-andreas/pi-linear-tools
-pi-linear-tools --help
-```
-
-## GitHub release
-
-```bash
-git tag v0.1.0
-git push origin v0.1.0
-```
-
-Create release notes from `RELEASE_NOTES_v0.1.0.md`:
-
-```bash
-gh release create v0.1.0 --title "v0.1.0" --notes-file RELEASE_NOTES_v0.1.0.md
-```
-
-Verify release:
-
-```bash
-gh release view v0.1.0
-```