Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Bound Linear requests during reporter reconciliation (#4985)
Andrew Mikofalvy11af2ea08903
diff --git a/.github/scripts/write-back.mjs b/.github/scripts/write-back.mjsindex 053468569..33a0afeba 100644--- a/.github/scripts/write-back.mjs+++ b/.github/scripts/write-back.mjs@@ -47,6 +47,7 @@ export const CANDIDATE_QUERY = `state { type }labels { nodes { name } }attachments { nodes { url } }+ children(first: 1) { nodes { id } pageInfo { hasNextPage } }}}}@@ -288,6 +289,27 @@ export class NeedsHumanError extends Error {}}+export class LinearRateLimitError extends Error {+ constructor(headers) {+ const read = (name) => headers?.get?.(name);+ const windows = [+ ['request reset epoch ms', read('x-ratelimit-requests-reset')],+ [+ `endpoint ${read('x-ratelimit-endpoint-name') ?? 'unspecified'} reset epoch ms`,+ read('x-ratelimit-endpoint-requests-reset'),+ ],+ ['complexity reset epoch ms', read('x-ratelimit-complexity-reset')],+ ['retry-after', read('retry-after')],+ ]+ .filter(([, value]) => value)+ .map(([label, value]) => `${label}: ${value}`);+ super(+ `Linear rate limit reached${windows.length ? ` (${windows.join('; ')})` : ''}; stopping reconciliation and leaving remaining candidates for a later run.`,+ );+ this.name = 'LinearRateLimitError';+ }+}+export async function runWriteBack({listCandidates,listChildren,@@ -349,7 +371,7 @@ export async function runWriteBack({return;}- const children = await listChildren(candidate.id);+ const children = candidate.hasChildren === false ? [] : await listChildren(candidate.id);const considered = children.length > 0 ? children : [candidate];@@ -522,7 +544,27 @@ export async function runWriteBack({}};- for (const candidate of await listCandidates()) {+ let candidates;+ try {+ candidates = await listCandidates();+ } catch (error) {+ if (!(error instanceof LinearRateLimitError)) throw error;+ return {+ posted,+ skipped,+ errored: [+ {+ identifier: 'candidate-enumeration',+ message: error.message,+ disposition: 'retried-next-run',+ },+ ],+ deferred: null,+ dryRun: !live,+ };+ }+ let deferred = 0;+ for (const [index, candidate] of candidates.entries()) {try {await processCandidate(candidate);} catch (err) {@@ -531,14 +573,21 @@ export async function runWriteBack({`::warning::write-back: ${candidate.identifier} could not be processed (${disposition}): ${err.message}`,);errored.push({ identifier: candidate.identifier, message: err.message, disposition });+ if (err instanceof LinearRateLimitError) {+ deferred = candidates.length - index - 1;+ break;+ }}}- return { posted, skipped, errored, dryRun: !live };+ return { posted, skipped, errored, deferred, dryRun: !live };}-export function runFailureMessage({ errored = [] } = {}) {+export function runFailureMessage({ errored = [], deferred } = {}) {if (errored.length === 0) return null;+ if (deferred === null) {+ return `Candidate enumeration stopped: ${errored[0].message} The remaining count is unknown; no marker was written, and a later reconciliation can retry.`;+ }const head =`${errored.length} of the candidates could not be processed: ` +errored.map((e) => `${e.identifier} (${e.message})`).join('; ');@@ -561,7 +610,7 @@ export const LINEAR_RETRY_CAP_MS = 8000;export const REQUEST_TIMEOUT_MS = 15_000;export function isRetryableStatus(status) {- return status === 429 || (status >= 500 && status < 600);+ return status >= 500 && status < 600;}const RETRYABLE_NETWORK_CODES = new Set([@@ -657,14 +706,29 @@ export async function linearGraphql({if (!res.ok) {let body = '';try {- body = (await res.text()).slice(0, 400);+ body = await res.text();} catch (err) {body = `<body unreadable: ${err.message}>`;}- throw new LinearRequestError(`Linear GraphQL returned HTTP ${res.status}: ${body}`, {- retryable: isRetryableStatus(res.status),- retryAfterSeconds: parseRetryAfterSeconds(res.headers?.get?.('retry-after')),- });+ let payload;+ try {+ payload = JSON.parse(body);+ } catch {+ payload = null;+ }+ if (+ res.status === 429 ||+ payload?.errors?.some((error) => error.extensions?.code === 'RATELIMITED')+ ) {+ throw new LinearRateLimitError(res.headers);+ }+ throw new LinearRequestError(+ `Linear GraphQL returned HTTP ${res.status}: ${body.slice(0, 400)}`,+ {+ retryable: isRetryableStatus(res.status),+ retryAfterSeconds: parseRetryAfterSeconds(res.headers?.get?.('retry-after')),+ },+ );}let payload;@@ -676,6 +740,9 @@ export async function linearGraphql({});}if (payload.errors?.length) {+ if (payload.errors.some((error) => error.extensions?.code === 'RATELIMITED')) {+ throw new LinearRateLimitError(res.headers);+ }throw new LinearRequestError(`Linear GraphQL error: ${payload.errors.map((e) => e.message).join('; ')}`,{@@ -696,21 +763,30 @@ export async function linearGraphql({}}-function toNode(raw) {+export function toNode(raw) {return {id: raw.id,identifier: raw.identifier,stateType: raw.state?.type ?? 'unknown',labels: (raw.labels?.nodes ?? []).map((l) => l.name),attachmentUrls: (raw.attachments?.nodes ?? []).map((a) => a.url),+ hasChildren: Array.isArray(raw.children?.nodes)+ ? raw.children.nodes.length > 0 || raw.children.pageInfo?.hasNextPage !== false+ : undefined,};}-async function paginate({ apiKey, query, variables, log }) {+async function paginate({ apiKey, query, variables, log, fetchImpl }) {const collected = [];let after = null;do {- const data = await linearGraphql({ apiKey, query, variables: { ...variables, after }, log });+ const data = await linearGraphql({+ apiKey,+ query,+ variables: { ...variables, after },+ log,+ fetchImpl,+ });const page = data?.issues;if (!page)throw new Error(@@ -958,10 +1034,16 @@ async function main() {);}+ let linearRequests = 0;+ const fetchImpl = (...args) => {+ linearRequests++;+ return fetch(...args);+ };const result = await runWriteBack({- listCandidates: () => paginate({ apiKey, query: CANDIDATE_QUERY, variables: {}, log }),+ listCandidates: () =>+ paginate({ apiKey, query: CANDIDATE_QUERY, variables: {}, log, fetchImpl }),listChildren: (parentId) =>- paginate({ apiKey, query: CHILDREN_QUERY, variables: { parentId }, log }),+ paginate({ apiKey, query: CHILDREN_QUERY, variables: { parentId }, log, fetchImpl }),versionFor: (node) => versionFor(node, channel),stableVersionFor: (node) => versionFor(node, 'stable'),isPublishedVersion: (version) => stableTags.includes(`v${version}`),@@ -971,6 +1053,7 @@ async function main() {postReply: realPostReply,recordNotification: async ({ issueId, url, title }) => {const data = await linearGraphql({+ fetchImpl,apiKey,query:'mutation Mark($input: AttachmentCreateInput!) { attachmentCreate(input: $input) { success } }',@@ -988,6 +1071,8 @@ async function main() {console.log(JSON.stringify({dryRun: result.dryRun,+ linearRequests,+ deferred: result.deferred,posted: result.posted.length,skipped: result.skipped,errored: result.errored,diff --git a/.github/scripts/write-back.test.mjs b/.github/scripts/write-back.test.mjsindex f76d71cca..1db7c47d6 100644--- a/.github/scripts/write-back.test.mjs+++ b/.github/scripts/write-back.test.mjs@@ -16,6 +16,7 @@ import {isStableVersion,LINEAR_RETRY_ATTEMPTS,LINEAR_RETRY_CAP_MS,+ LinearRateLimitError,linearGraphql,makeReleaseWindow,notificationMarkerUrl,@@ -26,6 +27,7 @@ import {runFailureMessage,runWriteBack,selectGhToken,+ toNode,} from './write-back.mjs';import { composeReply } from './write-back-gate.mjs';@@ -72,6 +74,23 @@ function harness(overrides = {}) {}describe('candidate enumeration', () => {+ test('the candidate page proves whether a child lookup is necessary without filtering child states', () => {+ expect(CANDIDATE_QUERY).toContain(+ 'children(first: 1) { nodes { id } pageInfo { hasNextPage } }',+ );+ expect(toNode({ children: { nodes: [], pageInfo: { hasNextPage: false } } }).hasChildren).toBe(+ false,+ );+ expect(+ toNode({ children: { nodes: [{ id: 'child' }], pageInfo: { hasNextPage: false } } })+ .hasChildren,+ ).toBe(true);+ expect(toNode({ children: { nodes: [], pageInfo: { hasNextPage: true } } }).hasChildren).toBe(+ true,+ );+ expect(toNode({ children: { nodes: [] } }).hasChildren).toBe(true);+ expect(toNode({}).hasChildren).toBeUndefined();+ });test('candidates come from a Linear ticket query, never from a walk over release commits', () => {expect(CANDIDATE_QUERY).toContain('issues(');expect(CANDIDATE_QUERY).toContain('state: { type: { eq: "completed" } }');@@ -461,6 +480,92 @@ describe('idempotency marker', () => {});describe('write-back run', () => {+ test('an enumeration throttle returns an unknown deferred count without processing or writing', async () => {+ const h = harness({+ live: true,+ listCandidates: async () => {+ throw new LinearRateLimitError();+ },+ });+ const result = await h.run();+ expect(result.deferred).toBeNull();+ expect(result.errored).toHaveLength(1);+ expect(h.writes).toEqual([]);+ expect(runFailureMessage(result)).toContain('remaining count is unknown');+ });++ test('quota diagnostics retain endpoint and complexity windows without mislabelling them as global', () => {+ const headers = {+ 'x-ratelimit-endpoint-name': 'attachmentCreate',+ 'x-ratelimit-endpoint-requests-reset': '123',+ 'x-ratelimit-complexity-reset': '456',+ 'retry-after': '2',+ };+ const error = new LinearRateLimitError({ get: (name) => headers[name] });+ expect(error.message).toContain('endpoint attachmentCreate reset epoch ms: 123');+ expect(error.message).toContain('complexity reset epoch ms: 456');+ expect(error.message).toContain('retry-after: 2');+ expect(error.message).not.toContain('(request reset');+ });+ test('leaf issues spend no separate child-query request', async () => {+ let calls = 0;+ const leaf = toNode({+ id: 'leaf',+ identifier: 'PRD-7539',+ state: { type: 'completed' },+ attachments: { nodes: [{ url: GH_ISSUE }, { url: GH_PULL }] },+ children: { nodes: [], pageInfo: { hasNextPage: false } },+ });+ const h = harness({+ listCandidates: async () => [leaf],+ listChildren: async () => {+ calls++;+ return [];+ },+ });+ const result = await h.run();+ expect(result.posted).toHaveLength(1);+ expect(calls).toBe(0);+ });++ test.each([true, undefined])(+ 'a parent or unknown child hint still loads every child (hint=%s)',+ async (hasChildren) => {+ let calls = 0;+ const h = harness({+ listCandidates: async () => [candidate({ hasChildren })],+ listChildren: async () => {+ calls++;+ return [candidate({ id: 'child', identifier: 'PRD-0002', stateType: 'started' })];+ },+ });+ const result = await h.run();+ expect(calls).toBe(1);+ expect(result.posted).toEqual([]);+ },+ );++ test('a Linear quota refusal stops the entire scan instead of querying every remaining candidate', async () => {+ let calls = 0;+ const h = harness({+ live: true,+ listCandidates: async () => [+ candidate(),+ candidate({ id: '2', identifier: 'PRD-2' }),+ candidate({ id: '3', identifier: 'PRD-3' }),+ ],+ listChildren: async () => {+ calls++;+ throw new LinearRateLimitError({ get: () => '1790326800000' });+ },+ });+ const result = await h.run();+ expect(calls).toBe(1);+ expect(result.deferred).toBe(2);+ expect(result.errored).toHaveLength(1);+ expect(result.errored[0].message).toContain('1790326800000');+ expect(h.writes).toEqual([]);+ });test('with no explicit live mode it composes and logs but performs no writes at all', async () => {const h = harness();const result = await h.run();@@ -922,19 +1027,39 @@ describe('a Linear call that failed for reasons unrelated to the request', () =>expect(h.slept).toEqual([]);});- test('every 4xx that is not 429 fails fast, and every 5xx is retried', () => {- for (const status of [400, 401, 403, 404, 409, 422])+ test('4xx fails fast, while transient 5xx remains retryable', () => {+ for (const status of [400, 401, 403, 404, 409, 422, 429])expect(isRetryableStatus(status)).toBe(false);- for (const status of [429, 500, 502, 503, 504]) expect(isRetryableStatus(status)).toBe(true);+ for (const status of [500, 502, 503, 504]) expect(isRetryableStatus(status)).toBe(true);expect(isRetryableStatus(200)).toBe(false);});- test('a 429 waits as long as Linear asked rather than as long as the backoff computed', async () => {+ test('a 429 stops without spending more quota or sleeping past the job budget', async () => {const h = callLinear([fail(429, 'slow down', { 'retry-after': '2' }), ok({ issues: {} })]);- await h.call;- expect(h.slept).toEqual([2000]);+ await expect(h.call).rejects.toBeInstanceOf(LinearRateLimitError);+ expect(h.attemptCount()).toBe(1);+ expect(h.slept).toEqual([]);});+ test.each([400, 200])(+ 'Linear GraphQL RATELIMITED on HTTP %s stops without retries',+ async (status) => {+ const payload = {+ errors: [+ { message: 'Rate limit exceeded', extensions: { code: 'RATELIMITED', statusCode: 429 } },+ ],+ };+ const response =+ status === 400+ ? fail(400, JSON.stringify(payload))+ : { ok: true, status: 200, json: async () => payload, headers: { get: () => null } };+ const h = callLinear([response, ok({ issues: {} })]);+ await expect(h.call).rejects.toBeInstanceOf(LinearRateLimitError);+ expect(h.attemptCount()).toBe(1);+ expect(h.slept).toEqual([]);+ },+ );+test('an outsized Retry-After is capped, so one reply cannot park the job', () => {expect(retryDelayMs({ attempt: 1, retryAfterSeconds: 3600 })).toBe(LINEAR_RETRY_CAP_MS);expect(parseRetryAfterSeconds('2')).toBe(2);