Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(github): proactive rate budget, capped waits, visible throttle

review246191ab366d
diff --git a/src/core/github/client.test.ts b/src/core/github/client.test.ts
index 397f0abf5..1e472ee3e 100644
--- a/src/core/github/client.test.ts
+++ b/src/core/github/client.test.ts
@@ -234,4 +234,60 @@ describe('GitHubIssuesClient', () => {
expect(headers?.has('if-none-match')).toBe(false)
})
})
+ describe('rate-limit observation', () => {
+ const rateHeaders = {
+ 'x-ratelimit-limit': '5000',
+ 'x-ratelimit-remaining': '4968',
+ 'x-ratelimit-reset': '1790625711',
+ 'x-ratelimit-resource': 'core'
+ }
+ const expected = { resource: 'core', limit: 5000, remaining: 4968, resetAt: 1_790_625_711_000 }
+
+ it.each([
+ ['a 200', () => response([], { headers: rateHeaders }), 4968],
+ ['a 304', () => new Response(null, { status: 304, headers: rateHeaders }), 4968],
+ ['a 500', () => new Response('{}', { status: 500, headers: rateHeaders }), 4968],
+ ['a rate-limited 403', () => new Response('{}', {
+ status: 403, headers: { ...rateHeaders, 'x-ratelimit-remaining': '0' }
+ }), 0]
+ ] as const)('reports the budget carried by %s', async (_name, make, remaining) => {
+ const samples: unknown[] = []
+ const client = new GitHubIssuesClient({
+ token: 'secret',
+ fetch: async () => make(),
+ onRateLimit: (sample) => samples.push(sample)
+ })
+ await client.issuesHeartbeat('nodeterm/nodeterm', 'W/"x"').catch(() => undefined)
+ expect(samples).toEqual([{ ...expected, remaining }])
+ })
+
+ it('ignores absent or malformed rate headers instead of recording a zero budget', async () => {
+ const samples: unknown[] = []
+ for (const headers of [
+ {},
+ { ...rateHeaders, 'x-ratelimit-remaining': 'lots' },
+ { ...rateHeaders, 'x-ratelimit-remaining': '9000' },
+ { ...rateHeaders, 'x-ratelimit-resource': 'core; evil' }
+ ]) {
+ const client = new GitHubIssuesClient({
+ token: 'secret',
+ fetch: async () => response([], { headers }),
+ onRateLimit: (sample) => samples.push(sample)
+ })
+ await client.issuesHeartbeat('nodeterm/nodeterm')
+ }
+ expect(samples).toEqual([])
+ })
+
+ it('never lets a throwing observer break the request', async () => {
+ const client = new GitHubIssuesClient({
+ token: 'secret',
+ fetch: async () => response([], { headers: { ...rateHeaders, etag: 'W/"a"' } }),
+ onRateLimit: () => { throw new Error('observer bug') }
+ })
+ await expect(client.issuesHeartbeat('nodeterm/nodeterm')).resolves.toEqual({
+ notModified: false, etag: 'W/"a"'
+ })
+ })
+ })
})
diff --git a/src/core/github/client.ts b/src/core/github/client.ts
index ba83d5d68..c5a6d4d3e 100644
--- a/src/core/github/client.ts
+++ b/src/core/github/client.ts
@@ -34,6 +34,30 @@ type ClientOptions = {
fetch?: typeof fetch
maxResponseBytes?: number
timeoutMs?: number
+ /** Called with the rate budget every response carries — 200, 304 and errors alike — so the
+ * request coordinator can pace work BEFORE GitHub has to refuse it. */
+ onRateLimit?: (sample: GitHubRateSample) => void
+}
+
+/** One reading of `x-ratelimit-*`. `resetAt` is epoch milliseconds. */
+export interface GitHubRateSample {
+ resource: string
+ limit: number
+ remaining: number
+ resetAt: number
+}
+
+/** Parses the rate headers, or null when any is absent or implausible. A missing header must never
+ * read as "zero left": that would pause sync on every response that simply does not carry one. */
+export function rateSampleFrom(headers: Headers): GitHubRateSample | null {
+ const limit = Number(headers.get('x-ratelimit-limit') ?? NaN)
+ const remaining = Number(headers.get('x-ratelimit-remaining') ?? NaN)
+ const reset = Number(headers.get('x-ratelimit-reset') ?? NaN)
+ const resource = headers.get('x-ratelimit-resource') ?? 'core'
+ if (!Number.isSafeInteger(limit) || limit <= 0 || !Number.isSafeInteger(remaining) ||
+ remaining < 0 || remaining > limit || !Number.isSafeInteger(reset) || reset <= 0 ||
+ !/^[a-z_]{1,32}$/.test(resource)) return null
+ return { resource, limit, remaining, resetAt: reset * 1_000 }
}
function safeRepository(repository: string): string {
@@ -442,6 +466,10 @@ export class GitHubIssuesClient {
} finally {
clearTimeout(timer)
}
+ const sample = rateSampleFrom(response.headers)
+ if (sample && this.options.onRateLimit) {
+ try { this.options.onRateLimit(sample) } catch { /* an observer never breaks a request */ }
+ }
if (response.status === 304) return response
if (response.status === 403 || response.status === 429) {
const retryAfter = Number(response.headers.get('retry-after'))
diff --git a/src/core/github/credentials.test.ts b/src/core/github/credentials.test.ts
index 23367af2d..386c46bd4 100644
--- a/src/core/github/credentials.test.ts
+++ b/src/core/github/credentials.test.ts
@@ -158,7 +158,9 @@ describe('GitHubCredentialResolver', () => {
ghAuthenticated: false,
tokenPresent: true,
storage: 'restricted-file',
- login: 'login-pat-user'
+ login: 'login-pat-user',
+ // Not credential material: the host uses it to look up the rate budget and strips it.
+ userId: 'pat-user'
})
expect(JSON.stringify(status)).not.toContain('super-secret-token')
})
diff --git a/src/core/github/credentials.ts b/src/core/github/credentials.ts
index 6566ab655..1b604921b 100644
--- a/src/core/github/credentials.ts
+++ b/src/core/github/credentials.ts
@@ -101,7 +101,7 @@ export class GitHubCredentialResolver {
return (await this.fromGitHubCli()) ?? this.fromStoredToken()
}
- async status(provider: GitHubAuthProvider): Promise<GitHubAuthStatus> {
+ async status(provider: GitHubAuthProvider): Promise<GitHubAuthStatus & { userId?: string }> {
const gh = await this.fromGitHubCli()
const stored = await this.dependencies.secret.readForHost()
const tokenIdentity = stored ? await this.dependencies.validate(stored) : null
@@ -118,7 +118,7 @@ export class GitHubCredentialResolver {
ghAuthenticated: gh !== null,
tokenPresent: stored !== null,
storage: this.dependencies.secret.availability,
- ...(active ? { login: active.login } : {})
+ ...(active ? { login: active.login, userId: active.userId } : {})
}
}
diff --git a/src/core/github/host.test.ts b/src/core/github/host.test.ts
index e19de2d9b..b82d8c7c4 100644
--- a/src/core/github/host.test.ts
+++ b/src/core/github/host.test.ts
@@ -107,7 +107,13 @@ function fixture() {
validateToken: vi.fn(async (value: string) => value === 'valid-token'
? { userId: '1', login: 'octocat' }
: null),
- client: vi.fn(() => client)
+ client: vi.fn(() => client),
+ rate: (userId: string) => userId === '1'
+ ? {
+ status: { resource: 'core', limit: 5_000, remaining: 7, resetAt: 9, observedAt: 1 },
+ throttle: { until: 9, kind: 'low-budget' as const }
+ }
+ : {}
})
return { controller, controls, resolver, secret, client }
}
@@ -124,6 +130,18 @@ describe('GitHubHostController', () => {
expect(resolver.status).not.toHaveBeenCalled()
})
+ it('strips the resolver identity from the wire and attaches that identity rate budget', async () => {
+ const { controller, resolver } = fixture()
+ resolver.status.mockResolvedValueOnce({
+ selectedProvider: 'auto', activeProvider: 'token', ghAuthenticated: false,
+ tokenPresent: true, storage: 'encrypted', login: 'octocat', userId: '1'
+ } as never)
+ const view = await controller.status()
+ expect(view.auth).not.toHaveProperty('userId')
+ expect(view.rate).toEqual({ resource: 'core', limit: 5_000, remaining: 7, resetAt: 9, observedAt: 1 })
+ expect(view.throttle).toEqual({ until: 9, kind: 'low-budget' })
+ })
+
it('requires exact local approval before creating a service context', async () => {
const { controller } = fixture()
await expect(controller.contextForProject('project-1')).rejects.toMatchObject({ code: 'not-approved' })
diff --git a/src/core/github/host.ts b/src/core/github/host.ts
index 5afd5cc0a..2b0d9be7d 100644
--- a/src/core/github/host.ts
+++ b/src/core/github/host.ts
@@ -3,7 +3,9 @@ import type {
GitHubAuthProvider,
GitHubAuthStatus,
GitHubControlState,
- GitHubControlView
+ GitHubControlView,
+ GitHubRateStatus,
+ GitHubThrottle
} from '../../shared/github-issues'
import { normaliseProjectKanbanGitHub, parseGitHubRepository } from './config'
import type { GitHubSecretStore, ResolvedGitHubCredential } from './credentials'
@@ -51,7 +53,9 @@ type ControlStoreLike = {
type CredentialResolverLike = {
resolve(provider: GitHubAuthProvider): Promise<ResolvedGitHubCredential | null>
- status(provider: GitHubAuthProvider): Promise<GitHubAuthStatus>
+ /** `userId` is the active credential's GitHub id — used here to find its rate budget, and
+ * stripped before the status leaves the host. */
+ status(provider: GitHubAuthProvider): Promise<GitHubAuthStatus & { userId?: string }>
}
type HostDependencies = {
@@ -61,7 +65,11 @@ type HostDependencies = {
resolver: CredentialResolverLike
secret: GitHubSecretStore
validateToken(token: string): Promise<{ userId: string; login: string } | null>
- client(token: string): GitHubIssuesClientLike
+ /** Builds the API client for a resolved credential. The identity comes with the token so the
+ * client can report every response's rate budget against the right account. */
+ client(credential: { token: string; userId: string }): GitHubIssuesClientLike
+ /** The request budget last seen for an identity, and why sync is held (if it is). */
+ rate?(userId: string): { status?: GitHubRateStatus; throttle?: GitHubThrottle }
onCredentialBoundaryChange?(): void
}
@@ -81,7 +89,7 @@ export class GitHubHostController {
if (!projectId) {
return {
control: { revision: state.revision, authProvider: state.authProvider },
- auth: await this.dependencies.resolver.status(state.authProvider)
+ ...this.authView(await this.dependencies.resolver.status(state.authProvider))
}
}
@@ -97,18 +105,20 @@ export class GitHubHostController {
projectId,
repository
})
- const auth = approved
- ? await this.dependencies.resolver.status(state.authProvider)
+ const authed = approved
+ ? this.authView(await this.dependencies.resolver.status(state.authProvider))
: {
- selectedProvider: state.authProvider,
- activeProvider: null,
- ghAuthenticated: false,
- tokenPresent: false,
- storage: this.dependencies.secret.availability
+ auth: {
+ selectedProvider: state.authProvider,
+ activeProvider: null,
+ ghAuthenticated: false,
+ tokenPresent: false,
+ storage: this.dependencies.secret.availability
+ }
}
return {
control: { revision: state.revision, authProvider: state.authProvider },
- auth,
+ ...authed,
project: {
projectId,
...(repository ? { repository } : {}),
@@ -183,7 +193,21 @@ export class GitHubHostController {
...project,
credentialGeneration: this.credentialGeneration,
userId: credential.userId,
- client: this.dependencies.client(credential.token)
+ client: this.dependencies.client({ token: credential.token, userId: credential.userId })
+ }
+ }
+
+ /** Splits the resolver's answer into the wire auth block (identity stripped) and the active
+ * identity's rate budget. */
+ private authView(resolved: GitHubAuthStatus & { userId?: string }): Pick<
+ GitHubControlView, 'auth' | 'rate' | 'throttle'
+ > {
+ const { userId, ...auth } = resolved
+ const rate = userId ? this.dependencies.rate?.(userId) : undefined
+ return {
+ auth,
+ ...(rate?.status ? { rate: rate.status } : {}),
+ ...(rate?.throttle ? { throttle: rate.throttle } : {})
}
}
diff --git a/src/core/github/integration.test.ts b/src/core/github/integration.test.ts
index 2740b1993..3e9484898 100644
--- a/src/core/github/integration.test.ts
+++ b/src/core/github/integration.test.ts
@@ -118,3 +118,50 @@ describe('registerGitHubIntegration', () => {
await expect(controller.contextForProject('project-1')).rejects.toThrow('not-authenticated')
})
})
+
+describe('registerGitHubIntegration rate budget', () => {
+ it('feeds each response budget to the coordinator under the credential identity, and shows it in status', async () => {
+ const reset = Math.floor(Date.now() / 1_000) + 3_600
+ globalThis.fetch = (async (input: RequestInfo | URL) => {
+ const url = String(input)
+ if (url.endsWith('/user')) {
+ return new Response(JSON.stringify({ id: 1, login: 'octocat' }), { status: 200 })
+ }
+ return new Response('[]', {
+ status: 200,
+ headers: {
+ etag: 'W/"top"',
+ 'x-ratelimit-limit': '5000',
+ 'x-ratelimit-remaining': '12',
+ 'x-ratelimit-reset': String(reset),
+ 'x-ratelimit-resource': 'core'
+ }
+ })
+ }) as typeof globalThis.fetch
+ const secret: GitHubSecretStore = {
+ availability: 'encrypted',
+ readForHost: async () => 'stored-token',
+ save: async () => undefined,
+ clear: async () => undefined
+ }
+ const { controller } = registerGitHubIntegration({
+ platform: fakePlatform(),
+ userDataDir,
+ project: async (id) => id === project.id ? { project, localApprovalId: 'local-1' } : null,
+ detectRepository: async () => 'owner/repo',
+ secret,
+ run: async () => ({ ok: false, stdout: '', stderr: 'not logged in' })
+ })
+ const initial = await controller.status('project-1')
+ await controller.approve({
+ projectId: 'project-1', repository: 'owner/repo', expectedRevision: initial.control.revision
+ })
+
+ const context = await controller.contextForProject('project-1')
+ await context.client.issuesHeartbeat('owner/repo')
+
+ const view = await controller.status('project-1')
+ expect(view.rate).toMatchObject({ resource: 'core', limit: 5_000, remaining: 12, resetAt: reset * 1_000 })
+ expect(view.throttle).toEqual({ until: reset * 1_000, kind: 'low-budget' })
+ })
+})
diff --git a/src/core/github/integration.ts b/src/core/github/integration.ts
index b2ddb697c..4e622b07d 100644
--- a/src/core/github/integration.ts
+++ b/src/core/github/integration.ts
@@ -47,7 +47,14 @@ export function registerGitHubIntegration(dependencies: Dependencies): {
resolver,
secret: dependencies.secret,
validateToken,
- client: (token) => new GitHubIssuesClient({ token }),
+ client: ({ token, userId }) => new GitHubIssuesClient({
+ token,
+ onRateLimit: (sample) => coordinator.noteRateSample(userId, sample)
+ }),
+ rate: (userId) => ({
+ status: coordinator.rateStatus(userId),
+ throttle: coordinator.throttle(userId)
+ }),
// Both halves of a credential boundary move: stop work that captured the old credential, and
// drop the resolver's memo so the next resolve reflects the change immediately instead of
// serving a revoked credential until its TTL happens to lapse.
diff --git a/src/core/github/request-coordinator.test.ts b/src/core/github/request-coordinator.test.ts
index 297c3c140..cc81630ae 100644
--- a/src/core/github/request-coordinator.test.ts
+++ b/src/core/github/request-coordinator.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest'
-import { GitHubRequestCoordinator } from './request-coordinator'
+import { backgroundFloor, GitHubRequestCoordinator, MAX_RATE_WAIT_MS } from './request-coordinator'
describe('GitHubRequestCoordinator', () => {
it('allows at most four reads for one identity across repositories', async () => {
@@ -108,3 +108,96 @@ describe('GitHubRequestCoordinator', () => {
await expect(queuedB).rejects.toMatchObject({ code: 'configuration-changed' })
})
})
+
+describe('GitHubRequestCoordinator rate budget', () => {
+ const sample = (remaining: number, resetAt = 3_600_000, limit = 5_000) =>
+ ({ resource: 'core', limit, remaining, resetAt })
+
+ it('records the budget each response reports, per identity', () => {
+ const coordinator = new GitHubRequestCoordinator({ now: () => 1_000 })
+ coordinator.noteRateSample('user-1', sample(4_968))
+ expect(coordinator.rateStatus('user-1')).toEqual({
+ resource: 'core', limit: 5_000, remaining: 4_968, resetAt: 3_600_000, observedAt: 1_000
+ })
+ expect(coordinator.rateStatus('user-2')).toBeUndefined()
+ })
+
+ it('keeps the lowest reading of a window and adopts a newer window', () => {
+ const coordinator = new GitHubRequestCoordinator({ now: () => 1_000 })
+ coordinator.noteRateSample('user-1', sample(4_000))
+ // A response that left GitHub earlier can arrive later; it must not raise the budget back.
+ coordinator.noteRateSample('user-1', sample(4_500))
+ expect(coordinator.rateStatus('user-1')?.remaining).toBe(4_000)
+ coordinator.noteRateSample('user-1', sample(4_999, 7_200_000))
+ expect(coordinator.rateStatus('user-1')?.remaining).toBe(4_999)
+ })
+
+ it('blocks new requests the moment a response says the budget is spent, before any refusal', () => {
+ const coordinator = new GitHubRequestCoordinator({ now: () => 1_000 })
+ coordinator.noteRateSample('user-1', sample(0, 90_000))
+ expect(coordinator.canStart('user-1', 89_999)).toBe(false)
+ expect(coordinator.canStart('user-1', 90_000)).toBe(true)
+ expect(coordinator.throttle('user-1')).toEqual({ until: 90_000, kind: 'rate-limited' })
+ })
+
+ it('pauses background work below the floor and resumes it when the window resets', () => {
+ let now = 1_000
+ const coordinator = new GitHubRequestCoordinator({ now: () => now })
+ coordinator.noteRateSample('user-1', sample(backgroundFloor(5_000), 90_000))
+ expect(coordinator.throttle('user-1')).toBeUndefined()
+ coordinator.noteRateSample('user-1', sample(backgroundFloor(5_000) - 1, 90_000))
+ expect(coordinator.throttle('user-1')).toEqual({ until: 90_000, kind: 'low-budget' })
+ // Low budget pauses only BACKGROUND work: a request the user asked for may still start.
+ expect(coordinator.canStart('user-1')).toBe(true)
+ now = 90_000
+ expect(coordinator.throttle('user-1')).toBeUndefined()
+ })
+
+ it('reports an error-learned backoff as the throttle too', () => {
+ const coordinator = new GitHubRequestCoordinator({ now: () => 1_000 })
+ coordinator.noteRateLimit('user-1', { kind: 'secondary', retryAt: 61_000 })
+ expect(coordinator.throttle('user-1')).toEqual({ until: 61_000, kind: 'rate-limited' })
+ })
+
+ it('refuses a read at once instead of sleeping past the cap', async () => {
+ const sleeps: number[] = []
+ const coordinator = new GitHubRequestCoordinator({
+ now: () => 1_000,
+ sleep: async (milliseconds) => { sleeps.push(milliseconds) }
+ })
+ coordinator.noteRateSample('user-1', sample(0, 1_000 + 60 * 60_000))
+ let ran = false
+ await expect(coordinator.runRead('user-1', async () => { ran = true }))
+ .rejects.toMatchObject({ code: 'rate-limited', retryAt: 1_000 + 60 * 60_000 })
+ expect(ran).toBe(false)
+ expect(sleeps).toEqual([])
+ })
+
+ it('refuses a mutation at once instead of sleeping past the cap', async () => {
+ const sleeps: number[] = []
+ const coordinator = new GitHubRequestCoordinator({
+ now: () => 1_000,
+ sleep: async (milliseconds) => { sleeps.push(milliseconds) }
+ })
+ coordinator.noteRateLimit('user-1', { kind: 'primary', retryAt: 1_000 + MAX_RATE_WAIT_MS + 1 })
+ await expect(coordinator.runMutation('user-1', async () => 'written'))
+ .rejects.toMatchObject({ code: 'rate-limited' })
+ expect(sleeps).toEqual([])
+ })
+
+ it('bounds the TOTAL wait when the deadline keeps moving during the sleep', async () => {
+ let now = 1_000
+ const sleeps: number[] = []
+ const coordinator = new GitHubRequestCoordinator({
+ now: () => now,
+ sleep: async (milliseconds) => {
+ sleeps.push(milliseconds)
+ now += milliseconds
+ coordinator.noteRateLimit('user-1', { kind: 'secondary', retryAt: now + MAX_RATE_WAIT_MS - 1 })
+ }
+ })
+ coordinator.noteRateLimit('user-1', { kind: 'secondary', retryAt: 1_000 + MAX_RATE_WAIT_MS - 1 })
+ await expect(coordinator.runRead('user-1', async () => 'ok')).rejects.toMatchObject({ code: 'rate-limited' })
+ expect(sleeps.reduce((total, value) => total + value, 0)).toBeLessThanOrEqual(MAX_RATE_WAIT_MS)
+ })
+})
diff --git a/src/core/github/request-coordinator.ts b/src/core/github/request-coordinator.ts
index ee2d03e5b..e10e75f7b 100644
--- a/src/core/github/request-coordinator.ts
+++ b/src/core/github/request-coordinator.ts
@@ -1,9 +1,28 @@
+import type { GitHubRateStatus, GitHubThrottle } from '../../shared/github-issues'
+import type { GitHubRateSample } from './client'
+
export class GitHubCoordinatorError extends Error {
- constructor(readonly code: 'configuration-changed') {
+ constructor(
+ readonly code: 'configuration-changed' | 'rate-limited',
+ readonly retryAt?: number
+ ) {
super(code)
}
}
+/** The longest any queued request waits out a rate limit. A primary limit resets up to an hour
+ * away; sleeping that long held a read slot (four per identity) and left the caller's IPC call
+ * hanging for the hour. Past this, the request is refused at once with the time it may retry. */
+export const MAX_RATE_WAIT_MS = 10_000
+
+/** Below this many requests left in the window, BACKGROUND polls stop until the window resets.
+ * The budget belongs to the whole GitHub account — the user's `gh`, their browser session and
+ * every other tool spend it too — so a board that polls must hand the last tenth back rather
+ * than race everything else to zero. A user-initiated refresh still runs (within its own floors). */
+export function backgroundFloor(limit: number): number {
+ return Math.max(100, Math.ceil(limit * 0.1))
+}
+
type RateLimit = { kind: 'primary' | 'secondary'; retryAt: number }
type ReadJob = {
generation: number
@@ -18,6 +37,8 @@ type IdentityState = {
lastMutationAt: number
generation: number
retryAt: number
+ /** Latest budget per resource (`core`, `search`, …), from response headers. */
+ budget: Map<string, GitHubRateStatus>
}
type CoordinatorOptions = {
@@ -85,6 +106,40 @@ export class GitHubRequestCoordinator {
if (Number.isFinite(limit.retryAt)) state.retryAt = Math.max(state.retryAt, limit.retryAt)
}
+ /** Records the budget a response carried. Responses can land out of order, so within one window
+ * the LOWEST reading wins; a later window replaces an earlier one. A spent `core` budget blocks
+ * new requests right away, instead of waiting for GitHub to refuse one. */
+ noteRateSample(identity: string, sample: GitHubRateSample): void {
+ const state = this.state(identity)
+ const previous = state.budget.get(sample.resource)
+ if (previous && sample.resetAt < previous.resetAt) return
+ if (previous && sample.resetAt === previous.resetAt && sample.remaining >= previous.remaining) return
+ state.budget.set(sample.resource, { ...sample, observedAt: this.now() })
+ if (sample.resource === 'core' && sample.remaining === 0) {
+ state.retryAt = Math.max(state.retryAt, sample.resetAt)
+ }
+ }
+
+ /** The `core` budget last seen for this identity, while its window is still current. */
+ rateStatus(identity: string, at = this.now()): GitHubRateStatus | undefined {
+ const status = this.states.get(identity)?.budget.get('core')
+ return status && status.resetAt > at ? { ...status } : undefined
+ }
+
+ /** Why background work for this identity must wait, and until when — or undefined when it may
+ * run. `rate-limited` also holds user-initiated requests (they wait up to MAX_RATE_WAIT_MS, then
+ * are refused); `low-budget` holds only background polls. */
+ throttle(identity: string, at = this.now()): GitHubThrottle | undefined {
+ const state = this.states.get(identity)
+ if (!state) return undefined
+ if (state.retryAt > at) return { until: state.retryAt, kind: 'rate-limited' }
+ const status = this.rateStatus(identity, at)
+ if (status && status.remaining < backgroundFloor(status.limit)) {
+ return { until: status.resetAt, kind: 'low-budget' }
+ }
+ return undefined
+ }
+
canStart(identity: string, at = this.now()): boolean {
return at >= this.state(identity).retryAt
}
@@ -109,7 +164,8 @@ export class GitHubRequestCoordinator {
mutationTail: Promise.resolve(),
lastMutationAt: Number.NEGATIVE_INFINITY,
generation: 0,
- retryAt: 0
+ retryAt: 0,
+ budget: new Map()
}
this.states.set(identity, state)
}
@@ -138,9 +194,13 @@ export class GitHubRequestCoordinator {
}
private async waitForRate(state: IdentityState): Promise<void> {
+ // The cap bounds the TOTAL wait, not each sleep: a deadline that keeps moving while we sleep
+ // (a secondary limit re-armed by a concurrent request) must not chain waits without end.
+ const deadline = this.now() + MAX_RATE_WAIT_MS
while (true) {
const wait = state.retryAt - this.now()
if (wait <= 0) return
+ if (state.retryAt > deadline) throw new GitHubCoordinatorError('rate-limited', state.retryAt)
await this.sleep(wait)
}
}
diff --git a/src/core/github/service.test.ts b/src/core/github/service.test.ts
index ba8200265..71fe0ec04 100644
--- a/src/core/github/service.test.ts
+++ b/src/core/github/service.test.ts
@@ -1090,3 +1090,95 @@ describe('GitHubIssueService heartbeat', () => {
expect(stored).not.toBe(client.currentHeartbeatEtag())
})
})
+
+describe('GitHubIssueService rate budget', () => {
+ const low = { resource: 'core', limit: 5_000, remaining: 12, resetAt: 9_000_000 }
+
+ it('pauses the background poll below the budget floor, but a refresh the user asks for still runs', async () => {
+ let clock = 1_000_000
+ const client = new FixtureClient([issue(1)])
+ const coordinator = new GitHubRequestCoordinator({ now: () => clock })
+ const timers: Array<() => Promise<void>> = []
+ const service = new GitHubIssueService({
+ cache: new GitHubIssueCache(userDataDir), coordinator,
+ contextForProject: async () => context(client),
+ now: () => clock,
+ setInterval: (fn) => { timers.push(fn as () => Promise<void>); return timers.length }
+ })
+ await service.subscribe(1, { projectId: 'project-1' })
+ expect(client.heartbeats).toHaveLength(1)
+
+ coordinator.noteRateSample('user-1', low)
+ await timers[0]()
+ expect(client.heartbeats).toHaveLength(1)
+
+ clock += REFRESH_MIN_INTERVAL_MS
+ await service.refresh({ projectId: 'project-1' })
+ expect(client.heartbeats).toHaveLength(2)
+ })
+
+ it('tells the board until when sync is held, instead of going quiet', async () => {
+ const clock = 1_000_000
+ const client = new FixtureClient([issue(1)])
+ const coordinator = new GitHubRequestCoordinator({ now: () => clock })
+ const service = new GitHubIssueService({
+ cache: new GitHubIssueCache(userDataDir), coordinator,
+ contextForProject: async () => context(client), now: () => clock
+ })
+ await service.refresh({ projectId: 'project-1' })
+ expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).throttle)
+ .toBeUndefined()
+
+ coordinator.noteRateSample('user-1', low)
+ expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).throttle)
+ .toEqual({ until: 9_000_000, kind: 'low-budget' })
+ })
+
+ it('prompts subscribers to re-read once when the poll pauses, not on every skipped minute', async () => {
+ const clock = 1_000_000
+ const client = new FixtureClient([issue(1)])
+ const coordinator = new GitHubRequestCoordinator({ now: () => clock })
+ const timers: Array<() => Promise<void>> = []
+ const deltas: number[][] = []
+ const service = new GitHubIssueService({
+ cache: new GitHubIssueCache(userDataDir), coordinator,
+ contextForProject: async () => context(client), now: () => clock,
+ setInterval: (fn) => { timers.push(fn as () => Promise<void>); return timers.length },
+ onDelta: (_uiId, _projectId, numbers) => deltas.push(numbers)
+ })
+ await service.subscribe(1, { projectId: 'project-1' })
+ const before = deltas.length
+ coordinator.noteRateSample('user-1', low)
+
+ await timers[0]()
+ await timers[0]()
+
+ expect(deltas.slice(before)).toEqual([[]])
+ })
+
+ it('prompts subscribers once when a poll is refused by a rate limit', async () => {
+ const clock = 1_000_000
+ const client = new FixtureClient([issue(1)])
+ const coordinator = new GitHubRequestCoordinator({ now: () => clock })
+ const timers: Array<() => Promise<void>> = []
+ const deltas: number[][] = []
+ const service = new GitHubIssueService({
+ cache: new GitHubIssueCache(userDataDir), coordinator,
+ contextForProject: async () => context(client), now: () => clock,
+ setInterval: (fn) => { timers.push(fn as () => Promise<void>); return timers.length },
+ onDelta: (_uiId, _projectId, numbers) => deltas.push(numbers)
+ })
+ await service.subscribe(1, { projectId: 'project-1' })
+ const before = deltas.length
+ client.issuesHeartbeat = async () => {
+ throw Object.assign(new Error('rate-limited'), { code: 'rate-limited', retryAt: 2_000_000 })
+ }
+
+ await timers[0]()
+ await timers[0]()
+
+ expect(deltas.slice(before)).toEqual([[]])
+ expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).throttle)
+ .toEqual({ until: 2_000_000, kind: 'rate-limited' })
+ })
+})
diff --git a/src/core/github/service.ts b/src/core/github/service.ts
index 29ebb8e7a..b13172c77 100644
--- a/src/core/github/service.ts
+++ b/src/core/github/service.ts
@@ -7,6 +7,7 @@ import type {
GitHubIssueQuery,
GitHubMutationResult,
GitHubRepositoryLabel,
+ GitHubThrottle,
IssueHeartbeatResult,
IssuePageResult,
LabelPageResult,
@@ -97,6 +98,9 @@ type RepositoryState = {
timer?: TimerId
refresh?: Promise<void>
cacheGeneration: number
+ /** The throttle deadline subscribers were last prompted about, so a held poll re-prompts them
+ * once per deadline instead of once a minute. */
+ announcedThrottleUntil?: number
}
type RepositoryControl = {
@@ -121,6 +125,14 @@ function epoch(context: GitHubIssueServiceContext): string {
])
}
+/** The deadline a rate-limit refusal carries, from the client or the coordinator alike. */
+function rateLimitedUntil(error: unknown): number | undefined {
+ if (!error || typeof error !== 'object') return undefined
+ const value = error as { code?: unknown; retryAt?: unknown }
+ return value.code === 'rate-limited' && typeof value.retryAt === 'number' &&
+ Number.isFinite(value.retryAt) ? value.retryAt : undefined
+}
+
function foldLabel(value: string): string {
return value.normalize('NFKC').toLocaleLowerCase('en-US')
}
@@ -269,7 +281,8 @@ export class GitHubIssueService {
try {
// Reuse the clock read above as the refresh's own start stamp: one read per refresh keeps the
// incremental watermark anchored to when the work actually began.
- return await this.refreshWithinFloor(request, startedAt)
+ // A foreground refresh is never held by the budget, so there is no throttle to hand back.
+ await this.refreshWithinFloor(request, startedAt)
} catch (error) {
// A refresh that FAILED bought nothing, so it must not hold the floor — otherwise the first
// network blip disables the board's own Retry button for the next 30 seconds.
@@ -281,12 +294,21 @@ export class GitHubIssueService {
}
}
+ /** Resolves to the throttle when a BACKGROUND refresh was held by the rate budget (nothing was
+ * sent), otherwise to nothing. */
private async refreshWithinFloor(
request: { projectId: string; full?: boolean },
- startedAt = this.now()
- ): Promise<void> {
+ startedAt = this.now(),
+ background = false
+ ): Promise<GitHubThrottle | void> {
const operationId = ++this.operationSequence
const captured = await this.options.contextForProject(request.projectId)
+ if (background) {
+ // Checked after the context resolves because the budget belongs to an IDENTITY, and only the
+ // context knows which one. Nothing below this line has spent a request yet.
+ const throttle = this.options.coordinator.throttle(captured.userId)
+ if (throttle) return throttle
+ }
const control = this.repositoryControl(captured.repository)
if (control.deletion || operationId <= control.clearCutoff) return
const repositoryGeneration = control.generation
@@ -312,7 +334,8 @@ export class GitHubIssueService {
throw new Error('invalid-query')
}
const context = await this.cacheContext(request.projectId)
- const { state } = await this.cachedState(context)
+ const { state, userId } = await this.cachedState(context)
+ const throttle = userId ? this.options.coordinator.throttle(userId) : undefined
// One snapshot holds both kinds (they arrive on the same endpoint), so the kind filter is
// what keeps the issue lane's items and counts exactly what they were before pull requests
// were harvested. An absent kind means issues.
@@ -359,7 +382,8 @@ export class GitHubIssueService {
...(state.snapshot ? {
lastSuccessfulRefreshAt: state.snapshot.lastSuccessfulRefreshAt,
lastFullReconciliationAt: state.snapshot.lastFullReconciliationAt
- } : {})
+ } : {}),
+ ...(throttle ? { throttle } : {})
}
}
@@ -694,6 +718,8 @@ export class GitHubIssueService {
private async cachedState(context: GitHubIssueProjectContext): Promise<{
key: string
state: RepositoryState
+ /** The identity the project's cache is bound to; null before its first authenticated refresh. */
+ userId: string | null
}> {
await this.waitForRepositoryDeletion(context.repository)
const repositoryGeneration = this.repositoryControl(context.repository).generation
@@ -714,7 +740,7 @@ export class GitHubIssueService {
if (repositoryGeneration !== this.repositoryControl(context.repository).generation) {
return this.cachedState(context)
}
- return { key, state }
+ return { key, state, userId: null }
}
const key = `${userId}\0${context.repository}`
let state = this.repositories.get(key)
@@ -736,7 +762,7 @@ export class GitHubIssueService {
if (repositoryGeneration !== this.repositoryControl(context.repository).generation) {
return this.cachedState(context)
}
- return { key, state }
+ return { key, state, userId }
}
private async refreshRepository(
@@ -871,14 +897,26 @@ export class GitHubIssueService {
// POLL_MS. Routing it through the floor would also break this loop's fallback — a
// throttled call returns without throwing, which reads here as "this project worked" and
// would stop us ever trying the next subscriber's context.
- await this.refreshWithinFloor({ projectId })
+ // It IS a background refresh, though, so the rate budget may hold it.
+ const throttle = await this.refreshWithinFloor({ projectId }, undefined, true)
+ if (throttle) this.announceThrottle(state, throttle.until)
return
- } catch {
+ } catch (error) {
+ const until = rateLimitedUntil(error)
+ if (until !== undefined) this.announceThrottle(state, until)
// Another approved project may still provide a valid context for the shared repository.
}
}
}
+ /** A held poll changes nothing the board can see except WHY it is quiet. Prompt its subscribers
+ * to re-read (the page carries the throttle) — once per deadline, not once per skipped minute. */
+ private announceThrottle(state: RepositoryState, until: number): void {
+ if (state.announcedThrottleUntil === until) return
+ state.announcedThrottleUntil = until
+ this.emitDelta(state, [], true)
+ }
+
private migrateProjectState(projectId: string, key: string, target: RepositoryState): void {
const previousKey = this.projectKeys.get(projectId)
if (!previousKey || previousKey === key) return
diff --git a/src/renderer/components/kanban/KanbanView.tsx b/src/renderer/components/kanban/KanbanView.tsx
index f550a72ef..fcb047e8d 100644
--- a/src/renderer/components/kanban/KanbanView.tsx
+++ b/src/renderer/components/kanban/KanbanView.tsx
@@ -34,6 +34,7 @@ import {
githubMoveIntent,
type GitHubMoveConfirmation
} from '../../lib/githubIssueMove'
+import { githubThrottleSentence } from '../../lib/githubSyncStatus'
/** One session node shown as a board card — derived LIVE from the canvas nodes; the board
* itself stores only column assignments. */
@@ -171,6 +172,8 @@ export const KanbanView = memo(function KanbanView({
const projectColor = useProjects((s) => s.projects.find((p) => p.id === s.activeProjectId)?.color)
const github = useGitHubIssues((state) => state.projects[projectId])
const githubReadOnly = Object.values(github?.pages ?? {}).some((page) => page.readOnly)
+ // Every page of one project carries the same identity's throttle; any one of them answers.
+ const githubThrottle = Object.values(github?.pages ?? {}).find((page) => page.throttle)?.throttle
// Pull requests are evicted first when a repository outgrows the cache bounds, so the lane can
// legitimately be a subset. Say so — a silently short list reads as "this repo has few PRs".
const pullsTruncated = Object.values(github?.pullPages ?? {}).some((page) => page.partial)
@@ -578,6 +581,9 @@ export const KanbanView = memo(function KanbanView({
GitHub issues are read only until configuration and refresh are complete.
</span>
)}
+ {board.github && githubThrottle && (
+ <span className="kanban-github-status">{githubThrottleSentence(githubThrottle)}</span>
+ )}
{board.github && pullsTruncated && (
<span className="kanban-github-status">
Showing the most recently updated pull requests only.
diff --git a/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsx b/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsx
index cc5bf45ab..eb657195c 100644
--- a/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsx
+++ b/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsx
@@ -117,6 +117,17 @@ describe('GitHubIssuesSection', () => {
unregisterDirty()
})
+ it('says until when sync is held, and how much of the GitHub budget is left', async () => {
+ stub({
+ ...viewWith({}, true),
+ rate: { resource: 'core', limit: 5_000, remaining: 12, resetAt: Date.UTC(2026, 8, 28, 21, 0), observedAt: 1 },
+ throttle: { until: Date.UTC(2026, 8, 28, 21, 0), kind: 'low-budget' }
+ })
+ await mount()
+ expect(host.textContent).toContain('Background sync paused until')
+ expect(host.textContent).toContain('12 of 5,000 GitHub requests left')
+ })
+
it('clears the write-only token field after Save and never renders the stored token', async () => {
await mount()
const input = host.querySelector<HTMLInputElement>('#github-personal-access-token')!
diff --git a/src/renderer/components/settings/sections/GitHubIssuesSection.tsx b/src/renderer/components/settings/sections/GitHubIssuesSection.tsx
index f9b62dbd3..f59d499a1 100644
--- a/src/renderer/components/settings/sections/GitHubIssuesSection.tsx
+++ b/src/renderer/components/settings/sections/GitHubIssuesSection.tsx
@@ -16,6 +16,7 @@ import { Button } from '@renderer/ui/Button'
import { Input } from '@renderer/ui/Input'
import { Select } from '@renderer/ui/Select'
import { Switch } from '@renderer/ui/Switch'
+import { githubRateSentence, githubThrottleSentence } from '../../../lib/githubSyncStatus'
const ROWS = {
enable: {
@@ -548,6 +549,14 @@ export function GitHubIssuesSection({ isActive }: { isActive: boolean }): React.
Choose a mapped completion column before GitHub issue changes are enabled.
</p>
)}
+ {view?.throttle && (
+ <p className="text-[13px] text-warn" role="status">
+ {githubThrottleSentence(view.throttle)}
+ </p>
+ )}
+ {view?.rate && (
+ <p className="text-[13px] text-muted">{githubRateSentence(view.rate)}</p>
+ )}
{notice && noticeRow === 'data' &&
<p role="status" className="text-[13px] text-muted">{notice}</p>}
</div>
diff --git a/src/renderer/lib/githubSyncStatus.test.ts b/src/renderer/lib/githubSyncStatus.test.ts
new file mode 100644
index 000000000..36ba8e08e
--- /dev/null
+++ b/src/renderer/lib/githubSyncStatus.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { githubRateSentence, githubThrottleSentence } from './githubSyncStatus'
+
+const clock = (ms: number): string => `T+${ms}`
+
+describe('githubThrottleSentence', () => {
+ it('says nothing when sync is not held', () => {
+ expect(githubThrottleSentence(undefined, clock)).toBeNull()
+ })
+
+ it('names the time a rate limit lifts', () => {
+ expect(githubThrottleSentence({ until: 90, kind: 'rate-limited' }, clock))
+ .toBe('GitHub rate limit reached. Sync resumes at T+90.')
+ })
+
+ it('says a low budget pauses only background sync, and until when', () => {
+ expect(githubThrottleSentence({ until: 90, kind: 'low-budget' }, clock))
+ .toBe('Background sync paused until T+90 to leave the rest of this hour’s GitHub requests to you.')
+ })
+})
+
+describe('githubRateSentence', () => {
+ it('reports the remaining budget and when it resets', () => {
+ expect(githubRateSentence({
+ resource: 'core', limit: 5_000, remaining: 4_968, resetAt: 90, observedAt: 1
+ }, clock)).toBe('4,968 of 5,000 GitHub requests left until T+90.')
+ })
+})
diff --git a/src/renderer/lib/githubSyncStatus.ts b/src/renderer/lib/githubSyncStatus.ts
new file mode 100644
index 000000000..3ffa233d1
--- /dev/null
+++ b/src/renderer/lib/githubSyncStatus.ts
@@ -0,0 +1,27 @@
+// What the board header and Settings → GitHub Issues say about the state of GitHub sync — decided
+// in one pure place so the two surfaces cannot describe the same condition in two ways. Each
+// sentence names only what was measured: the throttle and budget come from GitHub's own
+// `x-ratelimit-*` headers (or its refusal), never from a guess about why a request failed.
+import type { GitHubRateStatus, GitHubThrottle } from '@shared/github-issues'
+
+/** Local wall-clock time, hours and minutes. */
+export function githubClock(ms: number): string {
+ return new Date(ms).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
+}
+
+export function githubThrottleSentence(
+ throttle: GitHubThrottle | undefined,
+ clock: (ms: number) => string = githubClock
+): string | null {
+ if (!throttle) return null
+ return throttle.kind === 'rate-limited'
+ ? `GitHub rate limit reached. Sync resumes at ${clock(throttle.until)}.`
+ : `Background sync paused until ${clock(throttle.until)} to leave the rest of this hour’s GitHub requests to you.`
+}
+
+export function githubRateSentence(
+ rate: GitHubRateStatus,
+ clock: (ms: number) => string = githubClock
+): string {
+ return `${rate.remaining.toLocaleString('en-US')} of ${rate.limit.toLocaleString('en-US')} GitHub requests left until ${clock(rate.resetAt)}.`
+}
diff --git a/src/shared/github-issues.ts b/src/shared/github-issues.ts
index 6625fd864..3077fbd6b 100644
--- a/src/shared/github-issues.ts
+++ b/src/shared/github-issues.ts
@@ -58,6 +58,24 @@ export interface GitHubAuthStatus {
login?: string
}
+/** The GitHub request budget last reported for the active identity (`x-ratelimit-*`), `core`
+ * resource. `resetAt` / `observedAt` are epoch milliseconds. */
+export interface GitHubRateStatus {
+ resource: string
+ limit: number
+ remaining: number
+ resetAt: number
+ observedAt: number
+}
+
+/** Sync is held until `until` (epoch ms). `rate-limited`: GitHub refused, or the budget is spent —
+ * every request waits. `low-budget`: nodeterm is leaving the rest of the window to the user —
+ * only background polls wait; a refresh the user asks for still runs. */
+export interface GitHubThrottle {
+ until: number
+ kind: 'rate-limited' | 'low-budget'
+}
+
export interface GitHubIssueLabel {
id: number
name: string
@@ -187,6 +205,8 @@ export interface GitHubIssuePage {
readOnly: boolean
lastSuccessfulRefreshAt?: number
lastFullReconciliationAt?: number
+ /** Present while sync for this project's GitHub identity is held by the rate budget. */
+ throttle?: GitHubThrottle
}
export type GitHubMutationResult =
@@ -210,6 +230,10 @@ export interface GitHubControlView {
authProvider: GitHubAuthProvider
}
auth: GitHubAuthStatus
+ /** The active identity's request budget, when a response has reported one this window. */
+ rate?: GitHubRateStatus
+ /** Present while sync for the active identity is held by the rate budget. */
+ throttle?: GitHubThrottle
project?: {
projectId: string
repository?: string