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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
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.tsindex 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.tsindex ba83d5d68..c5a6d4d3e 100644--- a/src/core/github/client.ts+++ b/src/core/github/client.ts@@ -34,6 +34,30 @@ type ClientOptions = {fetch?: typeof fetchmaxResponseBytes?: numbertimeoutMs?: 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 responseif (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.tsindex 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.tsindex 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.tsindex 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.tsindex 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: CredentialResolverLikesecret: GitHubSecretStorevalidateToken(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.tsindex 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.tsindex 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.tsindex 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.tsindex 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: numbergeneration: numberretryAt: 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_MSwhile (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.tsindex 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.tsindex 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?: TimerIdrefresh?: 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.operationSequenceconst 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) returnconst 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: stringstate: 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) returndiff --git a/src/renderer/components/kanban/KanbanView.tsx b/src/renderer/components/kanban/KanbanView.tsxindex 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.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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: numbername: string@@ -187,6 +205,8 @@ export interface GitHubIssuePage {readOnly: booleanlastSuccessfulRefreshAt?: numberlastFullReconciliationAt?: 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?: GitHubThrottleproject?: {projectId: stringrepository?: string