@enrichlayer/el-linear 1.44.1 → 1.45.1

package/dist/queries/catalog.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Fetch project summaries, embedded teams, and lead in one paginated request.
+ * The conditional team branch replaces SDK relation follow-ups and keeps both
+ * request count and GraphQL complexity visible at one catalog boundary.
+ */
+export declare const GET_PROJECTS_CATALOG_QUERY = "\n  query GetProjectsCatalog(\n    $filter: ProjectFilter\n\t\t$teamId: String!\n\t\t$teamScoped: Boolean!\n    $first: Int!\n    $after: String\n  ) {\n    projects(filter: $filter, first: $first, after: $after, orderBy: updatedAt, includeArchived: false) @skip(if: $teamScoped) {\n      nodes { \n  id\n  name\n  description\n  state\n  progress\n  targetDate\n  createdAt\n  updatedAt\n  lead { id name }\n  teams { nodes { id key name } }\n }\n      pageInfo { hasNextPage endCursor }\n    }\n    team(id: $teamId) @include(if: $teamScoped) {\n      projects(filter: $filter, first: $first, after: $after, orderBy: updatedAt, includeArchived: false) {\n        nodes { \n  id\n  name\n  description\n  state\n  progress\n  targetDate\n  createdAt\n  updatedAt\n  lead { id name }\n  teams { nodes { id key name } }\n }\n        pageInfo { hasNextPage endCursor }\n      }\n    }\n  }\n";
+/** Batch label metadata and parent/team relations into one bounded catalog read. */
+export declare const GET_LABELS_CATALOG_QUERY = "\n  query GetLabelsCatalog($filter: IssueLabelFilter, $first: Int!) {\n    issueLabels(filter: $filter, first: $first) {\n      nodes {\n        id\n        name\n        color\n        isGroup\n        parent { id name }\n        team { id key name }\n      }\n    }\n  }\n";
+/** Batch cycle summaries and their team relation instead of resolving each edge. */
+export declare const GET_CYCLES_CATALOG_QUERY = "\n  query GetCyclesCatalog($filter: CycleFilter, $first: Int!) {\n    cycles(filter: $filter, first: $first, orderBy: createdAt) {\n      nodes {\n        id\n        name\n        number\n        startsAt\n        endsAt\n        isActive\n        isPrevious\n        isNext\n        progress\n        issueCountHistory\n        team { id key name }\n      }\n    }\n  }\n";
+/**
+ * Read one cycle and its bounded issue catalog in a single query, avoiding the
+ * SDK's per-issue relation fan-out while keeping the issue page size explicit.
+ */
+export declare const GET_CYCLE_DETAIL_QUERY = "\n  query GetCycleDetail($id: String!, $issuesFirst: Int!) {\n    cycle(id: $id) {\n      id\n      name\n      number\n      startsAt\n      endsAt\n      isActive\n      isPrevious\n      isNext\n      progress\n      issueCountHistory\n      team { id key name }\n      issues(first: $issuesFirst) {\n        nodes {\n          id\n          identifier\n          url\n          title\n          description\n          priority\n          estimate\n          createdAt\n          updatedAt\n          state { id name }\n          assignee { id name }\n          team { id key name }\n          project { id name }\n          labels { nodes { id name } }\n        }\n      }\n    }\n  }\n";
+/**
+ * Resolve a project name/slug with one bounded query. The conditional team
+ * branch performs scoping server-side without a separate project catalog read.
+ */
+export declare const RESOLVE_PROJECT_QUERY = "\n  query ResolveProjectCatalog(\n    $filter: ProjectFilter!\n\t\t$teamId: String!\n\t\t$teamScoped: Boolean!\n    $includeArchived: Boolean!\n  ) {\n    projects(filter: $filter, first: 5, includeArchived: $includeArchived) @skip(if: $teamScoped) {\n      nodes {\n        id\n        name\n        teams { nodes { id key name } }\n      }\n    }\n    team(id: $teamId) @include(if: $teamScoped) {\n      projects(filter: $filter, first: 5, includeArchived: $includeArchived) {\n        nodes {\n          id\n          name\n          teams { nodes { id key name } }\n        }\n      }\n    }\n  }\n";

package/dist/queries/catalog.js

@@ -0,0 +1,140 @@
+const PROJECT_FIELDS = `
+  id
+  name
+  description
+  state
+  progress
+  targetDate
+  createdAt
+  updatedAt
+  lead { id name }
+  teams { nodes { id key name } }
+`;
+/**
+ * Fetch project summaries, embedded teams, and lead in one paginated request.
+ * The conditional team branch replaces SDK relation follow-ups and keeps both
+ * request count and GraphQL complexity visible at one catalog boundary.
+ */
+export const GET_PROJECTS_CATALOG_QUERY = `
+  query GetProjectsCatalog(
+    $filter: ProjectFilter
+		$teamId: String!
+		$teamScoped: Boolean!
+    $first: Int!
+    $after: String
+  ) {
+    projects(filter: $filter, first: $first, after: $after, orderBy: updatedAt, includeArchived: false) @skip(if: $teamScoped) {
+      nodes { ${PROJECT_FIELDS} }
+      pageInfo { hasNextPage endCursor }
+    }
+    team(id: $teamId) @include(if: $teamScoped) {
+      projects(filter: $filter, first: $first, after: $after, orderBy: updatedAt, includeArchived: false) {
+        nodes { ${PROJECT_FIELDS} }
+        pageInfo { hasNextPage endCursor }
+      }
+    }
+  }
+`;
+/** Batch label metadata and parent/team relations into one bounded catalog read. */
+export const GET_LABELS_CATALOG_QUERY = `
+  query GetLabelsCatalog($filter: IssueLabelFilter, $first: Int!) {
+    issueLabels(filter: $filter, first: $first) {
+      nodes {
+        id
+        name
+        color
+        isGroup
+        parent { id name }
+        team { id key name }
+      }
+    }
+  }
+`;
+/** Batch cycle summaries and their team relation instead of resolving each edge. */
+export const GET_CYCLES_CATALOG_QUERY = `
+  query GetCyclesCatalog($filter: CycleFilter, $first: Int!) {
+    cycles(filter: $filter, first: $first, orderBy: createdAt) {
+      nodes {
+        id
+        name
+        number
+        startsAt
+        endsAt
+        isActive
+        isPrevious
+        isNext
+        progress
+        issueCountHistory
+        team { id key name }
+      }
+    }
+  }
+`;
+/**
+ * Read one cycle and its bounded issue catalog in a single query, avoiding the
+ * SDK's per-issue relation fan-out while keeping the issue page size explicit.
+ */
+export const GET_CYCLE_DETAIL_QUERY = `
+  query GetCycleDetail($id: String!, $issuesFirst: Int!) {
+    cycle(id: $id) {
+      id
+      name
+      number
+      startsAt
+      endsAt
+      isActive
+      isPrevious
+      isNext
+      progress
+      issueCountHistory
+      team { id key name }
+      issues(first: $issuesFirst) {
+        nodes {
+          id
+          identifier
+          url
+          title
+          description
+          priority
+          estimate
+          createdAt
+          updatedAt
+          state { id name }
+          assignee { id name }
+          team { id key name }
+          project { id name }
+          labels { nodes { id name } }
+        }
+      }
+    }
+  }
+`;
+/**
+ * Resolve a project name/slug with one bounded query. The conditional team
+ * branch performs scoping server-side without a separate project catalog read.
+ */
+export const RESOLVE_PROJECT_QUERY = `
+  query ResolveProjectCatalog(
+    $filter: ProjectFilter!
+		$teamId: String!
+		$teamScoped: Boolean!
+    $includeArchived: Boolean!
+  ) {
+    projects(filter: $filter, first: 5, includeArchived: $includeArchived) @skip(if: $teamScoped) {
+      nodes {
+        id
+        name
+        teams { nodes { id key name } }
+      }
+    }
+    team(id: $teamId) @include(if: $teamScoped) {
+      projects(filter: $filter, first: 5, includeArchived: $includeArchived) {
+        nodes {
+          id
+          name
+          teams { nodes { id key name } }
+        }
+      }
+    }
+  }
+`;

package/dist/utils/disk-cache.js

@@ -24,6 +24,7 @@
 import { randomBytes } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { withFileLock } from "../auth/oauth-fs.js";
 import { resolveActiveProfile } from "../config/paths.js";
 import { logger } from "./logger.js";
 const CACHE_VERSION = 1;
@@ -117,31 +118,64 @@ export async function cached(key, ttlSeconds, fetcher, options) {
     if (ttlSeconds <= 0) {
         return fetcher();
     }
-    const now = Date.now();
     if (!options?.bypass) {
         const envelope = await readEnvelope(key);
-        if (envelope && envelope.expiresAt > now) {
+        if (envelope && envelope.expiresAt > Date.now()) {
             return envelope.data;
         }
     }
-    const data = await fetcher();
-    const envelope = {
-        v: CACHE_VERSION,
-        key,
-        fetchedAt: now,
-        expiresAt: now + ttlSeconds * 1000,
-        data,
+    const fetchAndStore = async () => {
+        const data = await fetcher();
+        const now = Date.now();
+        const envelope = {
+            v: CACHE_VERSION,
+            key,
+            fetchedAt: now,
+            expiresAt: now + ttlSeconds * 1000,
+            data,
+        };
+        try {
+            await writeEnvelope(key, envelope);
+        }
+        catch (err) {
+            // Cache writes are best-effort — log to stderr and return the data
+            // anyway so a flaky disk doesn't break the user's command.
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error(`[disk-cache] write failed for "${key}": ${msg}`);
+        }
+        return data;
     };
+    // `--no-cache` is an explicit request to bypass both the cached value and
+    // cache coordination. Preserve that contract instead of making two forced
+    // refreshes wait on one another.
+    if (options?.bypass)
+        return fetchAndStore();
+    // Cold-cache single flight across processes. Re-read only after acquiring
+    // the sidecar lock: another el-linear invocation may have populated the
+    // envelope while this process was waiting. Without this second read, a
+    // burst of identical commands still sends one Linear request per process.
+    let enteredCriticalSection = false;
     try {
-        await writeEnvelope(key, envelope);
+        await fs.mkdir(cacheDir(), { recursive: true, mode: CACHE_DIR_MODE });
+        return await withFileLock(cachePath(key), async () => {
+            enteredCriticalSection = true;
+            const winner = await readEnvelope(key);
+            if (winner && winner.expiresAt > Date.now())
+                return winner.data;
+            return fetchAndStore();
+        });
     }
     catch (err) {
-        // Cache writes are best-effort — log to stderr and return the data
-        // anyway so a flaky disk doesn't break the user's command.
+        // Never retry a failed fetcher: a write may have reached Linear before
+        // throwing, so replaying it would be unsafe. Only coordination failures
+        // that happen before entering the critical section degrade to the old
+        // uncoordinated read-through behavior.
+        if (enteredCriticalSection)
+            throw err;
         const msg = err instanceof Error ? err.message : String(err);
-        logger.error(`[disk-cache] write failed for "${key}": ${msg}`);
+        logger.error(`[disk-cache] single-flight unavailable for "${key}": ${msg}`);
+        return fetchAndStore();
     }
-    return data;
 }
 /**
  * Clear cached entries. With no `prefix`, removes the entire cache

package/dist/utils/graphql-service.d.ts

@@ -1,6 +1,10 @@
+import { LinearClient } from "@linear/sdk";
 import type { LinearCredential } from "../auth/linear-credential.js";
+import type { OAuthState } from "../auth/oauth-storage.js";
 import type { GraphQLResponseData, GraphQLVariables } from "../types/linear.js";
 import type { AuthOptions } from "./auth.js";
+import { type RateLimitInfo } from "./output.js";
+import { type RateLimitAdmission } from "./rate-limit-admission.js";
 export interface GraphQLRequestOptions {
     /**
      * Retry only an operation whose mutation is safe to repeat. Callers must
@@ -13,8 +17,30 @@ export interface GraphQLRequestOptions {
 interface GraphQLServiceRuntimeOptions {
     retryDelaysMs?: readonly number[];
     sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Test/embedding seam; production derives this from EL_LINEAR_RATE_LIMIT_HEADROOM. */
+    admission?: RateLimitAdmission;
+    /** Reacquire an app-user client-credentials token after HTTP 401. */
+    renewAccessToken?: () => Promise<string>;
 }
-/** True only for failures where retrying a known-idempotent request is useful. */
+type OAuthStateRenewal = (state: OAuthState, options: {
+    forceOAuthRenewal: true;
+}) => Promise<OAuthState>;
+/**
+ * Keep the last persisted client-credentials state in a long-lived service.
+ * Each forced 401 renewal must advance from the previous renewal, not from the
+ * state captured when the service was constructed.
+ */
+export declare function createClientCredentialsTokenRenewal(initialState: OAuthState, renew?: OAuthStateRenewal): (() => Promise<string>) | undefined;
+export declare function extractRateLimitInfo(source: unknown, now: () => number): RateLimitInfo | undefined;
+/** True for both HTTP and GraphQL representations of Linear rate limiting. */
+export declare function isRateLimitGraphQLError(error: unknown): boolean;
+/**
+ * True only for failures where retrying a known-idempotent request immediately
+ * is useful. This deliberately differs from published `errorDetail.retryable`:
+ * a rate limit is transient for an external caller with reset-aware backoff,
+ * but must never enter this CLI's 150 ms / 400 ms retry loop.
+ */
 export declare function isTransientGraphQLError(error: unknown): boolean;
 /**
  * Constructor arg for `GraphQLService`. Re-exported alias of the shared
@@ -28,11 +54,26 @@ export declare function isTransientGraphQLError(error: unknown): boolean;
  * semantic change — same `Authorization: <token>` header is emitted).
  */
 export type GraphQLServiceAuth = LinearCredential;
+/**
+ * Put SDK-backed LinearService calls through the same quota admission and
+ * response-header observer as custom GraphQLService calls. The SDK's public
+ * `request()` discards response headers, so this narrow transport adapter uses
+ * its own public-ish rawRequest escape hatch and returns only `data` to the
+ * generated SDK models, preserving their existing contract.
+ */
+export declare function instrumentLinearClient(client: LinearClient, auth: GraphQLServiceAuth, options?: {
+    admission?: RateLimitAdmission;
+    now?: () => number;
+}): LinearClient;
 export declare class GraphQLService {
     private readonly graphQLClient;
     private readonly retryDelaysMs;
     private readonly sleep;
+    private readonly now;
+    private readonly admission;
+    private readonly renewAccessToken?;
     constructor(auth: GraphQLServiceAuth, options?: GraphQLServiceRuntimeOptions);
+    private observeRateLimit;
     rawRequest<T = GraphQLResponseData>(query: string, variables?: GraphQLVariables, options?: GraphQLRequestOptions): Promise<T>;
 }
 export declare function createGraphQLService(options: AuthOptions): Promise<GraphQLService>;

package/dist/utils/graphql-service.js

@@ -1,19 +1,180 @@
 import { LinearClient } from "@linear/sdk";
-import { getActiveAuth } from "../auth/token-resolver.js";
+import { print } from "graphql";
+import { ensureFreshAccessToken, getActiveAuth, } from "../auth/token-resolver.js";
+import { graphQLErrorCode, graphQLErrorHttpStatus, toLinearGraphQLError, } from "./linear-graphql-error.js";
+import { logger } from "./logger.js";
+import { recordRateLimitInfo } from "./output.js";
+import { createOAuthProfileRateLimitAdmission, createRateLimitAdmission, RateLimitAdmissionRefusal, } from "./rate-limit-admission.js";
 const DEFAULT_SAFE_MUTATION_RETRY_DELAYS_MS = [150, 400];
+/**
+ * Keep the last persisted client-credentials state in a long-lived service.
+ * Each forced 401 renewal must advance from the previous renewal, not from the
+ * state captured when the service was constructed.
+ */
+export function createClientCredentialsTokenRenewal(initialState, renew = ensureFreshAccessToken) {
+    if (initialState.grantType !== "client_credentials")
+        return undefined;
+    let currentState = initialState;
+    return async () => {
+        currentState = await renew(currentState, { forceOAuthRenewal: true });
+        return currentState.accessToken;
+    };
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
-/** True only for failures where retrying a known-idempotent request is useful. */
+function errorDetail(error) {
+    return error;
+}
+function errorResponse(error) {
+    const detail = errorDetail(error);
+    return detail.response ?? detail.raw?.response;
+}
+function headerValue(headers, name) {
+    if (!headers)
+        return undefined;
+    if ("get" in headers && typeof headers.get === "function") {
+        return headers.get(name) ?? undefined;
+    }
+    const expected = name.toLowerCase();
+    const entry = Object.entries(headers).find(([key]) => key.toLowerCase() === expected);
+    return entry?.[1];
+}
+function finiteNumber(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    const parsed = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function resetAtFromRetryAfter(value, now) {
+    if (value === undefined)
+        return undefined;
+    const seconds = finiteNumber(value);
+    if (seconds !== undefined) {
+        return new Date(now() + seconds * 1_000).toISOString();
+    }
+    if (typeof value === "string") {
+        const timestamp = Date.parse(value);
+        if (Number.isFinite(timestamp))
+            return new Date(timestamp).toISOString();
+    }
+    return undefined;
+}
+export function extractRateLimitInfo(source, now) {
+    const detail = errorDetail(source);
+    const response = errorResponse(source) ?? source;
+    const headers = response?.headers;
+    const limit = finiteNumber(detail.requestsLimit ?? headerValue(headers, "x-ratelimit-requests-limit"));
+    const remaining = finiteNumber(detail.requestsRemaining ??
+        headerValue(headers, "x-ratelimit-requests-remaining"));
+    const resetTimestamp = finiteNumber(detail.requestsResetAt ??
+        headerValue(headers, "x-ratelimit-requests-reset"));
+    const resetAt = resetTimestamp !== undefined
+        ? new Date(resetTimestamp).toISOString()
+        : resetAtFromRetryAfter(detail.retryAfter ?? headerValue(headers, "retry-after"), now);
+    const complexityCost = finiteNumber(headerValue(headers, "x-complexity"));
+    const complexityLimit = finiteNumber(headerValue(headers, "x-ratelimit-complexity-limit"));
+    const complexityRemaining = finiteNumber(headerValue(headers, "x-ratelimit-complexity-remaining"));
+    const complexityResetTimestamp = finiteNumber(headerValue(headers, "x-ratelimit-complexity-reset"));
+    const endpointName = headerValue(headers, "x-ratelimit-endpoint-name");
+    const endpointLimit = finiteNumber(headerValue(headers, "x-ratelimit-endpoint-requests-limit"));
+    const endpointRemaining = finiteNumber(headerValue(headers, "x-ratelimit-endpoint-requests-remaining"));
+    const endpointResetTimestamp = finiteNumber(headerValue(headers, "x-ratelimit-endpoint-requests-reset"));
+    const hasComplexity = complexityCost !== undefined ||
+        complexityLimit !== undefined ||
+        complexityRemaining !== undefined ||
+        complexityResetTimestamp !== undefined;
+    const hasEndpoint = endpointName !== undefined ||
+        endpointLimit !== undefined ||
+        endpointRemaining !== undefined ||
+        endpointResetTimestamp !== undefined;
+    if (limit === undefined &&
+        remaining === undefined &&
+        resetAt === undefined &&
+        !hasComplexity &&
+        !hasEndpoint) {
+        return undefined;
+    }
+    return {
+        limit,
+        remaining,
+        resetAt,
+        observedRequests: 1,
+        minimumRemaining: remaining,
+        ...(hasComplexity
+            ? {
+                complexity: {
+                    cost: complexityCost,
+                    totalCost: complexityCost,
+                    limit: complexityLimit,
+                    remaining: complexityRemaining,
+                    minimumRemaining: complexityRemaining,
+                    resetAt: complexityResetTimestamp === undefined
+                        ? undefined
+                        : new Date(complexityResetTimestamp).toISOString(),
+                },
+            }
+            : {}),
+        ...(hasEndpoint
+            ? {
+                endpoints: {
+                    [endpointName ?? "unknown"]: {
+                        limit: endpointLimit,
+                        remaining: endpointRemaining,
+                        minimumRemaining: endpointRemaining,
+                        resetAt: endpointResetTimestamp === undefined
+                            ? undefined
+                            : new Date(endpointResetTimestamp).toISOString(),
+                        observedRequests: 1,
+                    },
+                },
+            }
+            : {}),
+    };
+}
+/** True for both HTTP and GraphQL representations of Linear rate limiting. */
+export function isRateLimitGraphQLError(error) {
+    const detail = errorDetail(error);
+    if (graphQLErrorHttpStatus(error) === 429 ||
+        graphQLErrorCode(error)?.toUpperCase() === "RATELIMITED" ||
+        detail.type?.toLowerCase() === "ratelimited") {
+        return true;
+    }
+    return /\b(?:429|rate[- ]?limit(?:ed| exceeded))\b/i.test(errorMessage(error));
+}
+/**
+ * True only for failures where retrying a known-idempotent request immediately
+ * is useful. This deliberately differs from published `errorDetail.retryable`:
+ * a rate limit is transient for an external caller with reset-aware backoff,
+ * but must never enter this CLI's 150 ms / 400 ms retry loop.
+ */
 export function isTransientGraphQLError(error) {
-    const detail = error;
-    const status = detail.response?.status ?? detail.response?.statusCode;
-    if (status === 408 ||
-        status === 429 ||
-        (status !== undefined && status >= 500)) {
+    if (isRateLimitGraphQLError(error))
+        return false;
+    const status = graphQLErrorHttpStatus(error);
+    if (status === 408 || (status !== null && status >= 500)) {
         return true;
     }
-    return /\b(?:408|429|500|502|503|504)\b|(?:ECONNRESET|ECONNREFUSED|ETIMEDOUT|fetch failed|network error|connection termination)/i.test(errorMessage(error));
+    return /\b(?:408|500|502|503|504)\b|(?:ECONNRESET|ECONNREFUSED|ETIMEDOUT|fetch failed|network error|connection termination)/i.test(errorMessage(error));
+}
+function isMutationOperation(query) {
+    const withoutLeadingComments = query.replace(/^(?:\s*#[^\n]*(?:\n|$))*/, "");
+    return /^\s*mutation\b/i.test(withoutLeadingComments);
+}
+function rateLimitError(error, query, now) {
+    const rateLimit = extractRateLimitInfo(error, now);
+    const details = [];
+    if (rateLimit?.remaining !== undefined && rateLimit.limit !== undefined) {
+        details.push(`${rateLimit.remaining}/${rateLimit.limit} requests remain in the current window`);
+    }
+    if (rateLimit?.resetAt) {
+        details.push(`the request limit resets at ${rateLimit.resetAt}`);
+    }
+    const suffix = details.length > 0 ? ` ${details.join("; ")}.` : "";
+    const ambiguity = isMutationOperation(query)
+        ? " This mutation may have been applied; verify its outcome before retrying."
+        : "";
+    return toLinearGraphQLError(error, `GraphQL request failed: Rate limit exceeded.${suffix}${ambiguity}`);
 }
 function buildLinearClient(auth) {
     const baseHeaders = { "public-file-urls-expire-in": "3600" };
@@ -29,10 +190,61 @@ function buildLinearClient(auth) {
     }
     return new LinearClient({ apiKey: auth.apiKey, headers: baseHeaders });
 }
+async function persistRateLimitObservation(admission, info) {
+    recordRateLimitInfo(info);
+    try {
+        await admission.observe(info);
+    }
+    catch (error) {
+        // The request already completed. Never turn an observation write
+        // failure into a replayable command failure (especially for mutations).
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error(`[rate-limit] could not persist quota observation: ${message}`);
+    }
+}
+/**
+ * Put SDK-backed LinearService calls through the same quota admission and
+ * response-header observer as custom GraphQLService calls. The SDK's public
+ * `request()` discards response headers, so this narrow transport adapter uses
+ * its own public-ish rawRequest escape hatch and returns only `data` to the
+ * generated SDK models, preserving their existing contract.
+ */
+export function instrumentLinearClient(client, auth, options = {}) {
+    const transport = client
+        .client;
+    // Unit-test doubles and future SDK versions may not expose the escape hatch.
+    // Leave them untouched rather than manufacturing a partial transport.
+    if (!transport?.rawRequest || !transport.request)
+        return client;
+    const originalRawRequest = transport.rawRequest.bind(transport);
+    const admission = options.admission ?? createRateLimitAdmission(auth, { now: options.now });
+    const now = options.now ?? Date.now;
+    transport.request = async (document, variables, requestHeaders) => {
+        await admission.admit();
+        const query = typeof document === "string" ? document : print(document);
+        try {
+            const response = await originalRawRequest(query, variables, requestHeaders);
+            const rateLimit = extractRateLimitInfo(response, now);
+            if (rateLimit)
+                await persistRateLimitObservation(admission, rateLimit);
+            return response.data;
+        }
+        catch (error) {
+            const rateLimit = extractRateLimitInfo(error, now);
+            if (rateLimit)
+                await persistRateLimitObservation(admission, rateLimit);
+            throw error;
+        }
+    };
+    return client;
+}
 export class GraphQLService {
     graphQLClient;
     retryDelaysMs;
     sleep;
+    now;
+    admission;
+    renewAccessToken;
     constructor(auth, options = {}) {
         const client = buildLinearClient(auth);
         // LinearClient stores a private graphql-request client — access via escape hatch
@@ -42,18 +254,43 @@ export class GraphQLService {
         this.sleep =
             options.sleep ??
                 ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.now = options.now ?? Date.now;
+        this.admission =
+            options.admission ?? createRateLimitAdmission(auth, { now: this.now });
+        this.renewAccessToken = options.renewAccessToken;
+    }
+    async observeRateLimit(info) {
+        await persistRateLimitObservation(this.admission, info);
     }
     // Default type allows property access on raw GraphQL responses.
     // Callers can narrow with explicit type parameter: rawRequest<{ issues: { nodes: T[] } }>(...)
     async rawRequest(query, variables, options = {}) {
         let attempt = 0;
+        let renewedAfterUnauthorized = false;
         try {
             while (true) {
                 try {
+                    await this.admission.admit();
                     const response = await this.graphQLClient.rawRequest(query, variables);
+                    const rateLimit = extractRateLimitInfo(response, this.now);
+                    if (rateLimit)
+                        await this.observeRateLimit(rateLimit);
                     return response.data;
                 }
                 catch (error) {
+                    if (error instanceof RateLimitAdmissionRefusal)
+                        throw error;
+                    const rateLimit = extractRateLimitInfo(error, this.now);
+                    if (rateLimit)
+                        await this.observeRateLimit(rateLimit);
+                    if (!renewedAfterUnauthorized &&
+                        this.renewAccessToken &&
+                        graphQLErrorHttpStatus(error) === 401) {
+                        const token = await this.renewAccessToken();
+                        this.graphQLClient.setHeader("authorization", `Bearer ${token}`);
+                        renewedAfterUnauthorized = true;
+                        continue;
+                    }
                     if (!options.retrySafeMutation ||
                         attempt >= this.retryDelaysMs.length ||
                         !isTransientGraphQLError(error)) {
@@ -65,19 +302,35 @@ export class GraphQLService {
             }
         }
         catch (error) {
-            const err = error;
-            if (err.response?.errors) {
-                const graphQLError = err.response.errors[0];
-                throw new Error(graphQLError.message || "GraphQL query failed");
+            if (error instanceof RateLimitAdmissionRefusal)
+                throw error;
+            if (isRateLimitGraphQLError(error)) {
+                throw rateLimitError(error, query, this.now);
             }
-            throw new Error(`GraphQL request failed: ${err.message}`);
+            const err = error;
+            // The message text is byte-identical to what the plain `Error`
+            // carried before DEV-7987; only the classification is new, so
+            // callers matching on the message are untouched.
+            const message = err.response?.errors
+                ? err.response.errors[0]?.message || "GraphQL query failed"
+                : `GraphQL request failed: ${err.message}`;
+            // This is the ONLY place a Linear GraphQL failure leaves the
+            // service, so it is the only place that has to attach the
+            // classification. Any future branch that throws its own shaped
+            // message from here must go through `toLinearGraphQLError` too, or
+            // that failure silently loses its `errorDetail` on the envelope.
+            throw toLinearGraphQLError(error, message);
         }
     }
 }
 export async function createGraphQLService(options) {
     const auth = await getActiveAuth(options);
     if (auth.kind === "oauth") {
-        return new GraphQLService({ oauthToken: auth.token });
+        const credential = { oauthToken: auth.token };
+        return new GraphQLService(credential, {
+            admission: createOAuthProfileRateLimitAdmission(credential, auth.oauth.clientId, auth.oauth.viewerId),
+            renewAccessToken: createClientCredentialsTokenRenewal(auth.oauth),
+        });
     }
     return new GraphQLService({ apiKey: auth.token });
 }