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.

fix(github): a rate limit, an outage or a network blip is not 'signed out'

review463597f82fa4
diff --git a/src/core/github/client.test.ts b/src/core/github/client.test.ts
index 1e472ee3e..ed8224d94 100644
--- a/src/core/github/client.test.ts
+++ b/src/core/github/client.test.ts
@@ -32,7 +32,9 @@ describe('GitHubIssuesClient', () => {
token: 'secret',
fetch: async () => response({ id: 123, login: 'octocat' })
})
- expect(await client.getAuthenticatedUser()).toEqual({ userId: '123', login: 'octocat' })
+ expect(await client.checkAuthenticatedUser()).toEqual({
+ notModified: false, identity: { userId: '123', login: 'octocat' }
+ })
})
it('uses the fixed API host and required version headers', async () => {
@@ -290,4 +292,38 @@ describe('GitHubIssuesClient', () => {
})
})
})
+ describe('checkAuthenticatedUser', () => {
+ it('answers 304 for an unchanged identity when given its validator', async () => {
+ let sent: string | null = null
+ const client = new GitHubIssuesClient({
+ token: 'secret',
+ fetch: async (_url, init) => {
+ sent = new Headers(init?.headers).get('if-none-match')
+ return new Response(null, { status: 304 })
+ }
+ })
+ expect(await client.checkAuthenticatedUser('W/"me"')).toEqual({ notModified: true })
+ expect(sent).toBe('W/"me"')
+ })
+
+ it('returns the identity with its validator on a 200', async () => {
+ const client = new GitHubIssuesClient({
+ token: 'secret',
+ fetch: async () => response({ id: 7, login: 'octocat' }, { headers: { etag: 'W/"me"' } })
+ })
+ expect(await client.checkAuthenticatedUser()).toEqual({
+ notModified: false, identity: { userId: '7', login: 'octocat' }, etag: 'W/"me"'
+ })
+ })
+
+ it('still surfaces a 401 as a refusal', async () => {
+ const client = new GitHubIssuesClient({
+ token: 'secret',
+ fetch: async () => new Response('{}', { status: 401 })
+ })
+ await expect(client.checkAuthenticatedUser('W/"me"')).rejects.toMatchObject({
+ code: 'request-failed', status: 401
+ })
+ })
+ })
})
diff --git a/src/core/github/client.ts b/src/core/github/client.ts
index c5a6d4d3e..5170b6a70 100644
--- a/src/core/github/client.ts
+++ b/src/core/github/client.ts
@@ -224,8 +224,24 @@ export class GitHubIssuesClient {
this.timeoutMs = options.timeoutMs ?? 15_000
}
- async getAuthenticatedUser(): Promise<{ userId: string; login: string }> {
- const value = object(await this.json(await this.request('/user', { method: 'GET' })))
+ /** `GET /user`, conditional on `etag`. A 304 means the identity behind this token is unchanged —
+ * and it is free; a token GitHub no longer accepts is still refused (401) whatever the condition. */
+ async checkAuthenticatedUser(etag?: string): Promise<
+ | { notModified: true }
+ | { notModified: false; identity: { userId: string; login: string }; etag?: string }
+ > {
+ if (etag !== undefined && !string(etag, 512)) throw new GitHubClientError('invalid-request')
+ const response = await this.request('/user', {
+ method: 'GET', ...(etag ? { headers: { 'if-none-match': etag } } : {})
+ })
+ if (response.status === 304) return { notModified: true }
+ const identity = await this.userFrom(response)
+ const fresh = response.headers.get('etag')
+ return { notModified: false, identity, ...(fresh && string(fresh, 512) ? { etag: fresh } : {}) }
+ }
+
+ private async userFrom(response: Response): Promise<{ userId: string; login: string }> {
+ const value = object(await this.json(response))
if (!value || !positiveInteger(Number(value.id), Number.MAX_SAFE_INTEGER) ||
!string(value.login, 128) || !value.login) {
throw new GitHubClientError('malformed-response')
diff --git a/src/core/github/credentials.test.ts b/src/core/github/credentials.test.ts
index 386c46bd4..2fa5759bf 100644
--- a/src/core/github/credentials.test.ts
+++ b/src/core/github/credentials.test.ts
@@ -2,11 +2,14 @@ import { describe, expect, it, vi } from 'vitest'
import * as ghPathModule from '../gh-path'
import {
CREDENTIAL_CACHE_MS,
+ createTokenValidator,
GitHubCredentialResolver,
runGitHubCliCommand,
type CommandRunner,
- type GitHubSecretStore
+ type GitHubSecretStore,
+ type TokenValidation
} from './credentials'
+import { GitHubClientError } from './client'
import type { GitHubAuthProvider } from '../../shared/github-issues'
function fixture(options: {
@@ -19,12 +22,8 @@ function fixture(options: {
const run: CommandRunner = async (_command, args) => {
calls.push(args.join(' '))
if (options.gh === 'missing') return { ok: false, stdout: '', stderr: 'not found' }
- if (args[1] === 'status') {
- return options.gh === 'valid'
- ? { ok: true, stdout: '', stderr: '' }
- : { ok: false, stdout: '', stderr: 'not logged in' }
- }
- return { ok: true, stdout: 'gh-token\n', stderr: '' }
+ // An 'invalid' gh still HANDS OUT its stored token; GitHub is what refuses it (a 401 below).
+ return { ok: true, stdout: options.gh === 'valid' ? 'gh-token\n' : 'revoked-gh-token\n', stderr: '' }
}
const secret: GitHubSecretStore = {
availability: options.storage ?? 'encrypted',
@@ -35,9 +34,11 @@ function fixture(options: {
const resolver = new GitHubCredentialResolver({
run,
secret,
- validate: async (token) => {
+ validate: async (token): Promise<TokenValidation> => {
const userId = options.validTokens?.[token]
- return userId ? { userId, login: `login-${userId}` } : null
+ return userId
+ ? { status: 'ok', identity: { userId, login: `login-${userId}` } }
+ : { status: 'unauthorized' }
}
})
return { resolver, calls }
@@ -47,9 +48,8 @@ describe('GitHubCredentialResolver caching', () => {
function counted(now: () => number) {
let ghCalls = 0
let validations = 0
- const run: CommandRunner = async (_command, args) => {
+ const run: CommandRunner = async () => {
ghCalls += 1
- if (args[1] === 'status') return { ok: true, stdout: '', stderr: '' }
return { ok: true, stdout: 'gh-token\n', stderr: '' }
}
const secret: GitHubSecretStore = {
@@ -61,9 +61,9 @@ describe('GitHubCredentialResolver caching', () => {
const resolver = new GitHubCredentialResolver({
run,
secret,
- validate: async () => {
+ validate: async (): Promise<TokenValidation> => {
validations += 1
- return { userId: 'gh-user', login: 'octocat' }
+ return { status: 'ok', identity: { userId: 'gh-user', login: 'octocat' } }
},
now
})
@@ -78,7 +78,7 @@ describe('GitHubCredentialResolver caching', () => {
await resolver.resolve('gh')
const first = counts()
- expect(first.ghCalls).toBe(2)
+ expect(first.ghCalls).toBe(1)
expect(first.validations).toBe(1)
clock += 1_000
@@ -134,11 +134,11 @@ describe('GitHubCredentialResolver', () => {
clear: async () => undefined
}
const resolver = new GitHubCredentialResolver({
- run: async (_command, args) => args[1] === 'status'
- ? { ok: true, stdout: '', stderr: '' }
- : { ok: true, stdout: 'gh-token', stderr: '' },
+ run: async () => ({ ok: true, stdout: 'gh-token', stderr: '' }),
secret,
- validate: async () => ({ userId: '1', login: 'octocat' })
+ validate: async (): Promise<TokenValidation> => ({
+ status: 'ok', identity: { userId: '1', login: 'octocat' }
+ })
})
expect((await resolver.resolve('auto'))?.provider).toBe('gh')
expect(secretReads).toBe(0)
@@ -165,10 +165,154 @@ describe('GitHubCredentialResolver', () => {
expect(JSON.stringify(status)).not.toContain('super-secret-token')
})
- it('validates GitHub CLI auth before asking it for a token', async () => {
- const { resolver, calls } = fixture({ gh: 'invalid', storedToken: null })
+ it('never runs `gh auth status`, which reports a network failure as an invalid token', async () => {
+ // Measured on gh 2.45 with api.github.com unreachable: `gh auth status` printed "The token in
+ // hosts.yml is invalid" (and exited 0). `gh auth token` only reads the local store; whether the
+ // token works is decided by our own classified /user check.
+ const { resolver, calls } = fixture({ gh: 'valid', validTokens: { 'gh-token': 'gh-user' } })
await resolver.resolve('gh')
- expect(calls).toEqual(['auth status --hostname github.com'])
+ await resolver.status('gh')
+ expect(calls.every((call) => call === 'auth token --hostname github.com')).toBe(true)
+ })
+})
+
+describe('GitHubCredentialResolver: only GitHub saying no is "signed out"', () => {
+ function flaky(initial: TokenValidation['status'] = 'ok') {
+ let clock = 1_000
+ let answer: TokenValidation = initial === 'ok'
+ ? { status: 'ok', identity: { userId: 'gh-user', login: 'octocat' } }
+ : { status: 'unknown', reason: 'unreachable' }
+ let ghToken = 'gh-token'
+ const resolver = new GitHubCredentialResolver({
+ run: async () => ({ ok: true, stdout: `${ghToken}\n`, stderr: '' }),
+ secret: {
+ availability: 'encrypted',
+ readForHost: async () => 'pat',
+ save: async () => undefined,
+ clear: async () => undefined
+ },
+ validate: async (token) => token === 'pat'
+ ? { status: 'ok', identity: { userId: 'pat-user', login: 'pat-login' } }
+ : answer,
+ now: () => clock
+ })
+ return {
+ resolver,
+ advance: () => { clock += CREDENTIAL_CACHE_MS },
+ answer: (next: TokenValidation) => { answer = next },
+ ghToken: (next: string) => { ghToken = next }
+ }
+ }
+
+ it.each([
+ ['a rate limit', { status: 'unknown', reason: 'rate-limited', retryAt: 9_000 }],
+ ['a network failure', { status: 'unknown', reason: 'unreachable' }]
+ ] as const)('keeps the last good credential through %s', async (_name, failure) => {
+ const { resolver, advance, answer } = flaky()
+ expect((await resolver.resolve('gh'))?.login).toBe('octocat')
+ advance()
+ answer(failure)
+ expect(await resolver.resolve('gh')).toMatchObject({ provider: 'gh', userId: 'gh-user' })
+ const status = await resolver.status('gh')
+ expect(status).toMatchObject({
+ activeProvider: 'gh', ghAuthenticated: true, login: 'octocat',
+ unreachable: { reason: failure.reason }
+ })
+ })
+
+ it('refuses rather than answering "signed out" when it has never had a good answer', async () => {
+ const { resolver } = flaky('unknown')
+ await expect(resolver.resolve('gh')).rejects.toMatchObject({ code: 'github-unreachable' })
+ const status = await resolver.status('gh')
+ expect(status.unreachable).toEqual({ reason: 'unreachable' })
+ expect(status.activeProvider).toBeNull()
+ })
+
+ it('does not vouch for a DIFFERENT token with an old good answer', async () => {
+ const { resolver, advance, answer, ghToken } = flaky()
+ await resolver.resolve('gh')
+ advance()
+ ghToken('someone-elses-token')
+ answer({ status: 'unknown', reason: 'unreachable' })
+ await expect(resolver.resolve('gh')).rejects.toMatchObject({ code: 'github-unreachable' })
+ })
+
+ it('says signed out only when GitHub refuses the credential', async () => {
+ const { resolver, advance, answer } = flaky()
+ await resolver.resolve('gh')
+ advance()
+ answer({ status: 'unauthorized' })
+ expect(await resolver.resolve('gh')).toBeNull()
+ const status = await resolver.status('gh')
+ expect(status).toMatchObject({ activeProvider: null, ghAuthenticated: false })
+ expect(status.unreachable).toBeUndefined()
+ })
+
+ it('does not switch Auto to the saved token just because GitHub could not check the CLI', async () => {
+ const { resolver } = flaky('unknown')
+ await expect(resolver.resolve('auto')).rejects.toMatchObject({ code: 'github-unreachable' })
+ })
+
+ it('carries the retry time of a rate-limited check', async () => {
+ const { resolver, answer } = flaky('unknown')
+ answer({ status: 'unknown', reason: 'rate-limited', retryAt: 9_000 })
+ await expect(resolver.resolve('gh')).rejects.toMatchObject({ code: 'rate-limited', retryAt: 9_000 })
+ })
+})
+
+describe('createTokenValidator', () => {
+ type Fetch = Parameters<typeof createTokenValidator>[0]
+
+ it('makes the repeat check conditional, so an unchanged identity costs no request', async () => {
+ const sent: Array<[string, string | undefined]> = []
+ const fetchUser: Fetch = async (token, etag) => {
+ sent.push([token, etag])
+ return etag === 'W/"me"'
+ ? { notModified: true }
+ : { notModified: false, identity: { userId: '1', login: 'octocat' }, etag: 'W/"me"' }
+ }
+ const validate = createTokenValidator(fetchUser)
+ expect(await validate('t1')).toEqual({ status: 'ok', identity: { userId: '1', login: 'octocat' } })
+ expect(await validate('t1')).toEqual({ status: 'ok', identity: { userId: '1', login: 'octocat' } })
+ expect(sent).toEqual([['t1', undefined], ['t1', 'W/"me"']])
+ })
+
+ it('never presents one token\'s validator for another', async () => {
+ const sent: Array<[string, string | undefined]> = []
+ const validate = createTokenValidator(async (token, etag) => {
+ sent.push([token, etag])
+ return { notModified: false, identity: { userId: token, login: token }, etag: `W/"${token}"` }
+ })
+ await validate('t1')
+ await validate('t2')
+ expect(sent).toEqual([['t1', undefined], ['t2', undefined]])
+ })
+
+ it.each([
+ ['a 401', new GitHubClientError('request-failed', 401), { status: 'unauthorized' }],
+ ['a rate limit', new GitHubClientError('rate-limited', 403, 9_000),
+ { status: 'unknown', reason: 'rate-limited', retryAt: 9_000 }],
+ ['a network failure', new GitHubClientError('request-failed'), { status: 'unknown', reason: 'unreachable' }],
+ ['a 503', new GitHubClientError('request-failed', 503), { status: 'unknown', reason: 'unreachable' }]
+ ])('answers %s with the classified outcome', async (_name, error, expected) => {
+ const validate = createTokenValidator(async () => { throw error })
+ expect(await validate('t1')).toEqual(expected)
+ })
+
+ it('forgets a validator once GitHub refuses its token', async () => {
+ let refuse = false
+ const sent: Array<string | undefined> = []
+ const validate = createTokenValidator(async (_token, etag) => {
+ sent.push(etag)
+ if (refuse) throw new GitHubClientError('request-failed', 401)
+ return { notModified: false, identity: { userId: '1', login: 'a' }, etag: 'W/"e"' }
+ })
+ await validate('t1')
+ refuse = true
+ await validate('t1')
+ refuse = false
+ await validate('t1')
+ expect(sent).toEqual([undefined, 'W/"e"', undefined])
})
})
diff --git a/src/core/github/credentials.ts b/src/core/github/credentials.ts
index 1b604921b..6aeaa5692 100644
--- a/src/core/github/credentials.ts
+++ b/src/core/github/credentials.ts
@@ -3,11 +3,13 @@ import type {
GitHubAuthStatus,
GitHubSecretAvailability
} from '../../shared/github-issues'
+import { createHash } from 'node:crypto'
import { execFile } from 'node:child_process'
import { promisify } from 'node:util'
import type { SecretStore } from '../secret-store'
import { gitEnv } from '../git-env'
import { ghPath } from '../gh-path'
+import { classifyGitHubFailure, GitHubReachabilityError } from './failure'
export type CommandResult = { ok: boolean; stdout: string; stderr: string }
export type CommandRunner = (command: string, args: string[]) => Promise<CommandResult>
@@ -51,42 +53,127 @@ export interface ResolvedGitHubCredential extends ValidatedGitHubIdentity {
token: string
}
+/**
+ * What checking one token against GitHub established. Three answers, never two: `unauthorized` is
+ * GitHub refusing the token; `unknown` is failing to get an answer at all (network, outage, rate
+ * limit). Folding `unknown` into "not authenticated" is how a throttle used to read as "you are
+ * signed out" — see ./failure.ts.
+ */
+export type TokenValidation =
+ | { status: 'ok'; identity: ValidatedGitHubIdentity }
+ | { status: 'unauthorized' }
+ | { status: 'unknown'; reason: 'rate-limited' | 'unreachable'; retryAt?: number }
+
+/** One `/user` read. `etag` asks GitHub to answer 304 when the identity is unchanged. */
+export type AuthenticatedUserFetch = (token: string, etag?: string) => Promise<
+ | { notModified: true }
+ | { notModified: false; identity: ValidatedGitHubIdentity; etag?: string }
+>
+
+const VALIDATOR_MEMO_LIMIT = 8
+
+/**
+ * Validates tokens with a CONDITIONAL `GET /user`. Every background poll re-resolves the credential
+ * (the resolver's memo is shorter than the poll interval), so an unconditional check spent one
+ * request per poll even when the heartbeat itself was a free 304. Measured 2026-09-28: ten
+ * conditional `/user` reads answered 304 and moved `x-ratelimit-used` by zero, and a bogus token
+ * presenting a valid `If-None-Match` still got 401 — the condition never masks a revoked token.
+ *
+ * The memo is keyed by a digest of the token (never the token itself), holds one validator per
+ * token, and drops a token's entry the moment GitHub refuses it.
+ */
+export function createTokenValidator(fetchUser: AuthenticatedUserFetch): (token: string) => Promise<TokenValidation> {
+ const memo = new Map<string, { etag: string; identity: ValidatedGitHubIdentity }>()
+ return async (token) => {
+ const key = createHash('sha256').update(token).digest('hex')
+ const known = memo.get(key)
+ try {
+ const result = await fetchUser(token, known?.etag)
+ if (result.notModified) {
+ if (known) return { status: 'ok', identity: known.identity }
+ return { status: 'unknown', reason: 'unreachable' }
+ }
+ memo.delete(key)
+ if (result.etag) {
+ memo.set(key, { etag: result.etag, identity: result.identity })
+ while (memo.size > VALIDATOR_MEMO_LIMIT) memo.delete(memo.keys().next().value!)
+ }
+ return { status: 'ok', identity: result.identity }
+ } catch (error) {
+ const failure = classifyGitHubFailure(error)
+ if (failure.kind === 'unauthorized') {
+ memo.delete(key)
+ return { status: 'unauthorized' }
+ }
+ if (failure.kind === 'rate-limited') {
+ return failure.retryAt === undefined
+ ? { status: 'unknown', reason: 'rate-limited' }
+ : { status: 'unknown', reason: 'rate-limited', retryAt: failure.retryAt }
+ }
+ return { status: 'unknown', reason: 'unreachable' }
+ }
+ }
+}
+
type ResolverDependencies = {
run: CommandRunner
secret: GitHubSecretStore
- validate(token: string): Promise<ValidatedGitHubIdentity | null>
+ validate(token: string): Promise<TokenValidation>
now?: () => number
}
/** How long one resolved credential is reused. The service re-checks its epoch before every read
* and around every write, and each check calls resolve() — which, uncached, spawns `gh auth
- * status` + `gh auth token` AND spends a GET /user request. Those /user calls never pass through
- * the request coordinator, so they are neither rate-limited nor backed off: a single full sync of
- * a large repository could fire hundreds of them, trip GitHub's secondary limiter, and surface as
- * "not authenticated" to a user who is signed in perfectly well. Short enough that an external
- * `gh auth logout` is noticed promptly; every in-app credential change calls invalidate() instead
- * of waiting for it. */
+ * token` AND spends a GET /user request. Those /user calls never pass through the request
+ * coordinator, so they are neither rate-limited nor backed off: a single full sync of a large
+ * repository could fire hundreds of them, trip GitHub's secondary limiter, and — before the
+ * tri-state below — surface as "not authenticated" to a user who is signed in perfectly well.
+ * Short enough that an external `gh auth logout` is noticed promptly; every in-app credential
+ * change calls invalidate() instead of waiting for it. */
export const CREDENTIAL_CACHE_MS = 30_000
-type CacheEntry = { at: number; value: ResolvedGitHubCredential | null }
+type Source = 'gh' | 'token'
+
+/** One credential source, checked. `lastGood` is the last `ok` answer for THIS token, kept so that
+ * failing to reach GitHub does not un-sign-in a user GitHub has already vouched for. */
+type SourceOutcome =
+ | { status: 'absent' }
+ | { status: 'ok'; credential: ResolvedGitHubCredential }
+ | { status: 'unauthorized' }
+ | {
+ status: 'unknown'
+ reason: 'rate-limited' | 'unreachable'
+ retryAt?: number
+ lastGood?: ResolvedGitHubCredential
+ }
+
+type CacheEntry = { at: number; outcome: SourceOutcome }
export class GitHubCredentialResolver {
private readonly cache = new Map<GitHubAuthProvider, CacheEntry>()
+ private readonly lastGood = new Map<Source, ResolvedGitHubCredential>()
private readonly now: () => number
constructor(private readonly dependencies: ResolverDependencies) {
this.now = dependencies.now ?? Date.now
}
+ /**
+ * The credential to act with; null ONLY when there is none or GitHub refused it. When GitHub
+ * could not be asked, the last credential it vouched for (same token) is returned; with no such
+ * answer this throws a GitHubReachabilityError — never a null that would read as signed out.
+ */
async resolve(provider: GitHubAuthProvider): Promise<ResolvedGitHubCredential | null> {
const cached = this.cache.get(provider)
const at = this.now()
- if (cached && at - cached.at < CREDENTIAL_CACHE_MS) return cached.value
- const value = await this.resolveUncached(provider)
- // A null answer is cached too: "gh is logged out" is exactly the state that would otherwise
- // re-spawn two processes on every epoch check of every failing refresh.
- this.cache.set(provider, { at, value })
- return value
+ const outcome = cached && at - cached.at < CREDENTIAL_CACHE_MS
+ ? cached.outcome
+ : await this.select(provider)
+ // Every outcome is cached, a negative one too: "gh is logged out" and "GitHub is unreachable"
+ // are exactly the states that would otherwise re-spawn `gh` on every epoch check of every
+ // failing refresh.
+ if (!cached || cached.outcome !== outcome) this.cache.set(provider, { at, outcome })
+ return credentialFrom(outcome)
}
/** Drop the memo the moment the credential boundary moves (token saved/cleared, provider
@@ -95,47 +182,83 @@ export class GitHubCredentialResolver {
this.cache.clear()
}
- private async resolveUncached(provider: GitHubAuthProvider): Promise<ResolvedGitHubCredential | null> {
- if (provider === 'gh') return this.fromGitHubCli()
- if (provider === 'token') return this.fromStoredToken()
- return (await this.fromGitHubCli()) ?? this.fromStoredToken()
- }
-
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
- const active = provider === 'gh'
- ? gh
- : provider === 'token'
- ? tokenIdentity && stored ? { ...tokenIdentity, provider: 'token' as const, token: stored } : null
- : gh ?? (tokenIdentity && stored
- ? { ...tokenIdentity, provider: 'token' as const, token: stored }
- : null)
+ const token = await this.check('token', stored)
+ const selected = provider === 'gh' ? gh : provider === 'token' ? token : autoChoice(gh, token)
+ const active = selected.status === 'ok'
+ ? selected.credential
+ : selected.status === 'unknown' ? selected.lastGood : undefined
return {
selectedProvider: provider,
activeProvider: active?.provider ?? null,
- ghAuthenticated: gh !== null,
+ ghAuthenticated: gh.status === 'ok' || (gh.status === 'unknown' && !!gh.lastGood),
tokenPresent: stored !== null,
storage: this.dependencies.secret.availability,
- ...(active ? { login: active.login, userId: active.userId } : {})
+ ...(active ? { login: active.login, userId: active.userId } : {}),
+ ...(selected.status === 'unknown'
+ ? { unreachable: {
+ reason: selected.reason,
+ ...(selected.retryAt !== undefined ? { retryAt: selected.retryAt } : {})
+ } }
+ : {})
}
}
- private async fromGitHubCli(): Promise<ResolvedGitHubCredential | null> {
- const status = await this.dependencies.run('gh', ['auth', 'status', '--hostname', 'github.com'])
- if (!status.ok) return null
+ private async select(provider: GitHubAuthProvider): Promise<SourceOutcome> {
+ if (provider === 'gh') return this.fromGitHubCli()
+ if (provider === 'token') return this.check('token', await this.dependencies.secret.readForHost())
+ const gh = await this.fromGitHubCli()
+ // Auto prefers the CLI. The saved token is read only when the CLI has no credential or GitHub
+ // refused it — not when GitHub merely could not be asked, which would silently switch the
+ // identity every request is made as for the length of an outage.
+ if (gh.status === 'ok' || gh.status === 'unknown') return gh
+ return this.check('token', await this.dependencies.secret.readForHost())
+ }
+
+ /** `gh auth token` only reads gh's local store. `gh auth status` is deliberately NOT used: it
+ * checks the token over the network and — measured on gh 2.45 with GitHub unreachable — reports
+ * "The token in hosts.yml is invalid" for what was a dropped connection. */
+ private async fromGitHubCli(): Promise<SourceOutcome> {
const result = await this.dependencies.run('gh', ['auth', 'token', '--hostname', 'github.com'])
const token = result.ok ? result.stdout.trim() : ''
- if (!token) return null
- const identity = await this.dependencies.validate(token)
- return identity ? { ...identity, provider: 'gh', token } : null
+ return this.check('gh', token || null)
}
- private async fromStoredToken(): Promise<ResolvedGitHubCredential | null> {
- const token = await this.dependencies.secret.readForHost()
- if (!token) return null
- const identity = await this.dependencies.validate(token)
- return identity ? { ...identity, provider: 'token', token } : null
+ private async check(source: Source, token: string | null): Promise<SourceOutcome> {
+ if (!token) return { status: 'absent' }
+ const validation = await this.dependencies.validate(token)
+ if (validation.status === 'ok') {
+ const credential: ResolvedGitHubCredential = { ...validation.identity, provider: source, token }
+ this.lastGood.set(source, credential)
+ return { status: 'ok', credential }
+ }
+ if (validation.status === 'unauthorized') {
+ this.lastGood.delete(source)
+ return { status: 'unauthorized' }
+ }
+ const previous = this.lastGood.get(source)
+ return {
+ status: 'unknown',
+ reason: validation.reason,
+ ...(validation.retryAt !== undefined ? { retryAt: validation.retryAt } : {}),
+ // Only for the SAME token: a newly logged-in account is not vouched for by the old one.
+ ...(previous && previous.token === token ? { lastGood: previous } : {})
+ }
}
}
+
+function autoChoice(gh: SourceOutcome, token: SourceOutcome): SourceOutcome {
+ return gh.status === 'ok' || gh.status === 'unknown' ? gh : token
+}
+
+function credentialFrom(outcome: SourceOutcome): ResolvedGitHubCredential | null {
+ if (outcome.status === 'ok') return outcome.credential
+ if (outcome.status !== 'unknown') return null
+ if (outcome.lastGood) return outcome.lastGood
+ throw new GitHubReachabilityError(
+ outcome.reason === 'rate-limited' ? 'rate-limited' : 'github-unreachable',
+ outcome.retryAt
+ )
+}
diff --git a/src/core/github/failure.test.ts b/src/core/github/failure.test.ts
new file mode 100644
index 000000000..52f3236b9
--- /dev/null
+++ b/src/core/github/failure.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { GitHubClientError } from './client'
+import { GitHubReachabilityError, classifyGitHubFailure } from './failure'
+import { GitHubCoordinatorError } from './request-coordinator'
+
+describe('classifyGitHubFailure', () => {
+ it.each([
+ ['a 401', new GitHubClientError('request-failed', 401), { kind: 'unauthorized' }],
+ ['a non-rate-limit 403', new GitHubClientError('insufficient-permission', 403), { kind: 'unauthorized' }],
+ ['a primary rate limit', new GitHubClientError('rate-limited', 403, 9_000), { kind: 'rate-limited', retryAt: 9_000 }],
+ ['a secondary rate limit', new GitHubClientError('rate-limited', 429, 7_000), { kind: 'rate-limited', retryAt: 7_000 }],
+ ['a capped coordinator wait', new GitHubCoordinatorError('rate-limited', 5_000), { kind: 'rate-limited', retryAt: 5_000 }],
+ ['a network failure or timeout', new GitHubClientError('request-failed'), { kind: 'unreachable' }],
+ ['a 502', new GitHubClientError('request-failed', 502), { kind: 'unreachable' }],
+ ['a 404 from a flaky proxy', new GitHubClientError('request-failed', 404), { kind: 'unreachable' }],
+ ['a truncated body', new GitHubClientError('malformed-response'), { kind: 'unreachable' }],
+ ['an oversized body', new GitHubClientError('response-too-large'), { kind: 'unreachable' }],
+ ['an unreachable credential check', new GitHubReachabilityError('github-unreachable'), { kind: 'unreachable' }],
+ ['a rate-limited credential check', new GitHubReachabilityError('rate-limited', 4_000), { kind: 'rate-limited', retryAt: 4_000 }],
+ ['a configuration change', new GitHubCoordinatorError('configuration-changed'), { kind: 'other' }],
+ ['an unrelated error', new Error('boom'), { kind: 'other' }],
+ ['a non-error', 'boom', { kind: 'other' }]
+ ])('classifies %s', (_name, error, expected) => {
+ expect(classifyGitHubFailure(error)).toEqual(expected)
+ })
+
+ it('reads the error shape, so an error that crossed a structured clone still classifies', () => {
+ expect(classifyGitHubFailure({ code: 'rate-limited', retryAt: 3 })).toEqual({ kind: 'rate-limited', retryAt: 3 })
+ expect(classifyGitHubFailure({ code: 'request-failed', status: 401 })).toEqual({ kind: 'unauthorized' })
+ })
+})
diff --git a/src/core/github/failure.ts b/src/core/github/failure.ts
new file mode 100644
index 000000000..3a88c602b
--- /dev/null
+++ b/src/core/github/failure.ts
@@ -0,0 +1,51 @@
+/**
+ * The ONE place this module decides what a failed GitHub call means.
+ *
+ * The distinction that matters to a user is "you are signed out" against "GitHub could not be
+ * asked". Only the first is fixed by signing in, and saying it for the second sends the user to
+ * re-authenticate an account that is fine — while the real cause (a rate limit, an outage, a
+ * dropped network) goes unnamed. So `unauthorized` is reserved for an answer GitHub actually gave
+ * about the credential: a 401, or a 403 that is not a rate limit. Everything that merely failed to
+ * produce an answer is `unreachable` or `rate-limited`, and must never be reported as signed out.
+ *
+ * It reads the error's SHAPE (`code`, `status`, `retryAt`) rather than its class, so an error that
+ * lost its prototype on the way (a structured clone, a re-thrown copy) still classifies the same.
+ */
+
+export type GitHubFailure =
+ | { kind: 'unauthorized' }
+ | { kind: 'rate-limited'; retryAt?: number }
+ | { kind: 'unreachable' }
+ /** Not a statement about GitHub at all: configuration, approval, a programming error. */
+ | { kind: 'other' }
+
+/** A credential check that could not reach an answer. Thrown instead of reporting "signed out". */
+export class GitHubReachabilityError extends Error {
+ constructor(
+ readonly code: 'github-unreachable' | 'rate-limited',
+ readonly retryAt?: number
+ ) {
+ super(code)
+ }
+}
+
+export function classifyGitHubFailure(error: unknown): GitHubFailure {
+ if (!error || typeof error !== 'object') return { kind: 'other' }
+ const value = error as { code?: unknown; status?: unknown; retryAt?: unknown }
+ switch (value.code) {
+ case 'rate-limited':
+ return typeof value.retryAt === 'number' && Number.isFinite(value.retryAt)
+ ? { kind: 'rate-limited', retryAt: value.retryAt }
+ : { kind: 'rate-limited' }
+ case 'insufficient-permission':
+ return { kind: 'unauthorized' }
+ case 'request-failed':
+ return value.status === 401 ? { kind: 'unauthorized' } : { kind: 'unreachable' }
+ case 'malformed-response':
+ case 'response-too-large':
+ case 'github-unreachable':
+ return { kind: 'unreachable' }
+ default:
+ return { kind: 'other' }
+ }
+}
diff --git a/src/core/github/host.test.ts b/src/core/github/host.test.ts
index b82d8c7c4..1a8200abc 100644
--- a/src/core/github/host.test.ts
+++ b/src/core/github/host.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it, vi } from 'vitest'
import type { Project } from '../../shared/types'
import type { GitHubControlState } from '../../shared/github-issues'
import { GitHubHostController, GitHubHostError } from './host'
+import type { TokenValidation } from './credentials'
const project: Project = {
id: 'project-1',
@@ -104,9 +105,11 @@ function fixture() {
controls,
resolver,
secret,
- validateToken: vi.fn(async (value: string) => value === 'valid-token'
- ? { userId: '1', login: 'octocat' }
- : null),
+ validateToken: vi.fn(async (value: string): Promise<TokenValidation> => value === 'valid-token'
+ ? { status: 'ok', identity: { userId: '1', login: 'octocat' } }
+ : value === 'unchecked-token'
+ ? { status: 'unknown', reason: 'unreachable' }
+ : { status: 'unauthorized' }),
client: vi.fn(() => client),
rate: (userId: string) => userId === '1'
? {
@@ -170,4 +173,10 @@ describe('GitHubHostController', () => {
expect(secret.save).toHaveBeenCalledWith('valid-token')
expect(JSON.stringify(view)).not.toContain('valid-token')
})
+
+ it('does not call a token invalid when GitHub could not be asked, and saves nothing', async () => {
+ const { controller, secret } = fixture()
+ await expect(controller.saveToken('unchecked-token')).rejects.toMatchObject({ code: 'github-unreachable' })
+ expect(secret.save).not.toHaveBeenCalled()
+ })
})
diff --git a/src/core/github/host.ts b/src/core/github/host.ts
index 2b0d9be7d..1957b9fbe 100644
--- a/src/core/github/host.ts
+++ b/src/core/github/host.ts
@@ -8,7 +8,8 @@ import type {
GitHubThrottle
} from '../../shared/github-issues'
import { normaliseProjectKanbanGitHub, parseGitHubRepository } from './config'
-import type { GitHubSecretStore, ResolvedGitHubCredential } from './credentials'
+import type { GitHubSecretStore, ResolvedGitHubCredential, TokenValidation } from './credentials'
+import { GitHubReachabilityError } from './failure'
import type {
GitHubIssueProjectContext,
GitHubIssueServiceContext,
@@ -64,7 +65,7 @@ type HostDependencies = {
controls: ControlStoreLike
resolver: CredentialResolverLike
secret: GitHubSecretStore
- validateToken(token: string): Promise<{ userId: string; login: string } | null>
+ validateToken(token: string): Promise<TokenValidation>
/** 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
@@ -166,8 +167,17 @@ export class GitHubHostController {
}
async saveToken(token: string): Promise<GitHubControlView> {
- const identity = await this.dependencies.validateToken(token)
- if (!identity) throw new GitHubHostError('invalid-token')
+ const validation = await this.dependencies.validateToken(token)
+ // Only GitHub refusing the token makes it invalid. When GitHub could not be asked, nothing is
+ // saved either — an unchecked token is not stored — but the user is told why, not that the
+ // token they pasted is wrong.
+ if (validation.status === 'unauthorized') throw new GitHubHostError('invalid-token')
+ if (validation.status === 'unknown') {
+ throw new GitHubReachabilityError(
+ validation.reason === 'rate-limited' ? 'rate-limited' : 'github-unreachable',
+ validation.retryAt
+ )
+ }
await this.dependencies.secret.save(token)
this.credentialGeneration += 1
this.dependencies.onCredentialBoundaryChange?.()
diff --git a/src/core/github/integration.ts b/src/core/github/integration.ts
index 4e622b07d..87eaa0aa9 100644
--- a/src/core/github/integration.ts
+++ b/src/core/github/integration.ts
@@ -1,7 +1,7 @@
import type { Project } from '../../shared/types'
import type { CorePlatform } from '../platform'
import type { GitHubSecretStore, CommandRunner } from './credentials'
-import { GitHubCredentialResolver } from './credentials'
+import { createTokenValidator, GitHubCredentialResolver } from './credentials'
import { GitHubControlStore } from './control-store'
import { GitHubIssuesClient } from './client'
import { GitHubIssueCache } from './cache'
@@ -26,13 +26,10 @@ export function registerGitHubIntegration(dependencies: Dependencies): {
controller: GitHubHostController
service: GitHubIssueService
} {
- const validateToken = async (token: string) => {
- try {
- return await new GitHubIssuesClient({ token }).getAuthenticatedUser()
- } catch {
- return null
- }
- }
+ // Tri-state and conditional (see createTokenValidator): a failed check is no longer a null that
+ // every caller reads as "signed out", and an unchanged identity re-validates with a free 304.
+ const validateToken = createTokenValidator((token, etag) =>
+ new GitHubIssuesClient({ token }).checkAuthenticatedUser(etag))
const controls = new GitHubControlStore(dependencies.userDataDir)
const coordinator = new GitHubRequestCoordinator()
const resolver = new GitHubCredentialResolver({
diff --git a/src/core/github/report-issue-service.test.ts b/src/core/github/report-issue-service.test.ts
index 405c168e9..2f56c865b 100644
--- a/src/core/github/report-issue-service.test.ts
+++ b/src/core/github/report-issue-service.test.ts
@@ -1,5 +1,6 @@
import { beforeEach, describe, expect, it, vi } from 'vitest'
import { GitHubClientError } from './client'
+import { GitHubReachabilityError } from './failure'
import {
reportIssue,
resetReportRunCounters,
@@ -102,6 +103,19 @@ describe('the repository comes from the project, or there is none', () => {
expect((result as { message: string }).message).toContain('do not file it anywhere else')
})
+ it('never tells an agent to have the user sign in when GitHub merely could not check the sign-in', async () => {
+ for (const error of [new GitHubReachabilityError('rate-limited', 9), new GitHubReachabilityError('github-unreachable')]) {
+ const result = await reportIssue(deps({ contextForProject: async () => { throw error } }), {
+ projectId: 'p', input: INPUT
+ })
+ expect((result as { message: string }).message).not.toContain('sign in')
+ }
+ const limited = await reportIssue(deps({
+ contextForProject: async () => { throw new GitHubReachabilityError('rate-limited', 9) }
+ }), { projectId: 'p', input: INPUT })
+ expect((limited as { message: string }).message).toContain('report-rate-limited')
+ })
+
it('names the machine-local approval when that is what is missing', async () => {
const d = deps({ contextForProject: async () => { throw new Error('not-approved') } })
const result = await reportIssue(d, { projectId: 'p', input: INPUT })
diff --git a/src/core/github/report-issue-service.ts b/src/core/github/report-issue-service.ts
index 4c29d8e2d..964f74a97 100644
--- a/src/core/github/report-issue-service.ts
+++ b/src/core/github/report-issue-service.ts
@@ -136,6 +136,9 @@ export function describeContextError(error: unknown): string {
)
case 'project-not-found':
return 'report-no-project: that project is not open here. Do not retry.'
+ // The credential check itself was rate-limited. Not a sign-in problem (see ./failure.ts).
+ case 'rate-limited':
+ return 'report-rate-limited: GitHub is rate-limiting this token. Try again later, once.'
default:
return `report-failed: could not reach GitHub (${code}). Tell the user rather than retrying.`
}
diff --git a/src/core/github/service.ts b/src/core/github/service.ts
index b13172c77..c5618a30b 100644
--- a/src/core/github/service.ts
+++ b/src/core/github/service.ts
@@ -21,6 +21,7 @@ import {
type GitHubCompleteSnapshot,
type GitHubIssueCache
} from './cache'
+import { classifyGitHubFailure } from './failure'
import type { GitHubRequestCoordinator } from './request-coordinator'
const MAX_ISSUES = 10_000
@@ -125,14 +126,6 @@ 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')
}
@@ -902,8 +895,10 @@ export class GitHubIssueService {
if (throttle) this.announceThrottle(state, throttle.until)
return
} catch (error) {
- const until = rateLimitedUntil(error)
- if (until !== undefined) this.announceThrottle(state, until)
+ const failure = classifyGitHubFailure(error)
+ if (failure.kind === 'rate-limited' && failure.retryAt !== undefined) {
+ this.announceThrottle(state, failure.retryAt)
+ }
// Another approved project may still provide a valid context for the shared repository.
}
}
diff --git a/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsx b/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsx
index eb657195c..d181639b3 100644
--- a/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsx
+++ b/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsx
@@ -128,6 +128,43 @@ describe('GitHubIssuesSection', () => {
expect(host.textContent).toContain('12 of 5,000 GitHub requests left')
})
+ it('says GitHub could not be reached — never "not signed in" — when the sign-in could not be checked', async () => {
+ stub(viewWith({
+ activeProvider: null, ghAuthenticated: false, tokenPresent: false, login: undefined,
+ unreachable: { reason: 'unreachable' }
+ }, true))
+ await mount()
+ expect(host.textContent).toContain('GitHub could not be reached to check the sign-in.')
+ expect(host.textContent).not.toContain('not signed in')
+ expect(host.textContent).not.toContain('Authentication is still needed')
+ })
+
+ it('keeps the last confirmed sign-in on screen through a rate limit, and says it is the last one', async () => {
+ stub(viewWith({
+ activeProvider: 'gh', ghAuthenticated: true, login: 'octocat',
+ unreachable: { reason: 'rate-limited' }
+ }, true))
+ await mount()
+ expect(host.textContent).toContain('✓ Signed in via GitHub CLI as @octocat')
+ expect(host.textContent).toContain('GitHub’s rate limit was reached, so the sign-in could not be checked')
+ expect(host.textContent).toContain('the last one GitHub confirmed')
+ })
+
+ it('names a rate limit or an outage instead of a generic failure', async () => {
+ stub(viewWith({}, true))
+ ;(window as unknown as { nodeTerminal: any }).nodeTerminal.githubIssues.refresh =
+ vi.fn(async () => { throw new Error("Error invoking remote method 'github-issues:refresh': Error: rate-limited") })
+ await mount()
+ const refresh = [...host.querySelectorAll('button')].find((b) => b.textContent === 'Refresh now')!
+ await act(async () => { refresh.click() })
+ expect(host.textContent).toContain('GitHub’s rate limit was reached. Try again later.')
+
+ ;(window as unknown as { nodeTerminal: any }).nodeTerminal.githubIssues.refresh =
+ vi.fn(async () => { throw new Error("Error invoking remote method 'github-issues:refresh': Error: github-unreachable") })
+ await act(async () => { refresh.click() })
+ expect(host.textContent).toContain('GitHub could not be reached. Nothing was changed')
+ })
+
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 f59d499a1..ff451541a 100644
--- a/src/renderer/components/settings/sections/GitHubIssuesSection.tsx
+++ b/src/renderer/components/settings/sections/GitHubIssuesSection.tsx
@@ -16,7 +16,11 @@ 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'
+import {
+ githubRateSentence,
+ githubThrottleSentence,
+ githubUnreachableSentence
+} from '../../../lib/githubSyncStatus'
const ROWS = {
enable: {
@@ -61,6 +65,12 @@ function messageFor(error: unknown): string {
? String((error as { code: unknown }).code)
: error instanceof Error ? error.message : ''
if (code.includes('revision-conflict')) return 'Settings changed elsewhere. The latest state has been loaded.'
+ // Checked before anything that could read as an auth problem: a limit or an outage is not the
+ // user's credential, and naming it as one sends them to re-authenticate an account that is fine.
+ if (code.includes('rate-limited')) return 'GitHub’s rate limit was reached. Try again later.'
+ if (code.includes('github-unreachable')) {
+ return 'GitHub could not be reached. Nothing was changed; try again in a moment.'
+ }
if (code.includes('invalid-token')) return 'GitHub could not validate that token.'
if (code.includes('not-authenticated')) return 'Sign in with GitHub CLI or save a valid token first.'
if (code.includes('not-approved')) return 'Approve this repository on this machine first.'
@@ -360,7 +370,9 @@ export function GitHubIssuesSection({ isActive }: { isActive: boolean }): React.
{ready
? `Ready as ${view?.auth.login ?? 'GitHub user'}`
: view?.project?.approved
- ? 'Repository approved. Authentication is still needed.'
+ ? view.auth.unreachable && !authenticated
+ ? 'Repository approved. GitHub could not be reached to check the sign-in.'
+ : 'Repository approved. Authentication is still needed.'
: 'Approval is required before nodeterm reads the repository.'}
</span>
{!view?.project?.approved && repository && (
@@ -393,6 +405,10 @@ export function GitHubIssuesSection({ isActive }: { isActive: boolean }): React.
<p className="text-[13px] text-muted">
GitHub authentication has not been checked yet.
</p>
+ ) : auth.unreachable && !activeProvider ? (
+ // GitHub never answered for this credential. Not signed out — every branch below
+ // would say it was.
+ <p className="text-[13px] text-muted">{githubUnreachableSentence(auth.unreachable)}</p>
) : ghActive ? (
// Happy path: the CLI already authenticates every request — no token, no dropdown.
<p className="text-[13px] text-text">
@@ -430,6 +446,12 @@ export function GitHubIssuesSection({ isActive }: { isActive: boolean }): React.
</Button>
</div>
+ {auth?.unreachable && activeProvider && (
+ <p className="text-[13px] text-muted">
+ {githubUnreachableSentence(auth.unreachable)} The sign-in above is the last one GitHub confirmed.
+ </p>
+ )}
+
{/* A pinned provider decides which credential is even consulted, and the dropdown that
changes it now lives inside Advanced — so the pinning has to be said out loud. */}
{selectedProvider !== 'auto' && (
diff --git a/src/renderer/lib/githubSyncStatus.test.ts b/src/renderer/lib/githubSyncStatus.test.ts
index 36ba8e08e..87c092b2d 100644
--- a/src/renderer/lib/githubSyncStatus.test.ts
+++ b/src/renderer/lib/githubSyncStatus.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest'
-import { githubRateSentence, githubThrottleSentence } from './githubSyncStatus'
+import { githubRateSentence, githubThrottleSentence, githubUnreachableSentence } from './githubSyncStatus'
const clock = (ms: number): string => `T+${ms}`
@@ -26,3 +26,15 @@ describe('githubRateSentence', () => {
}, clock)).toBe('4,968 of 5,000 GitHub requests left until T+90.')
})
})
+
+describe('githubUnreachableSentence', () => {
+ it('names a rate limit and when the check can run again', () => {
+ expect(githubUnreachableSentence({ reason: 'rate-limited', retryAt: 90 }, clock))
+ .toBe('GitHub’s rate limit was reached, so the sign-in could not be checked until T+90.')
+ })
+
+ it('names an unreachable GitHub without claiming a cause it did not see', () => {
+ expect(githubUnreachableSentence({ reason: 'unreachable' }, clock))
+ .toBe('GitHub could not be reached to check the sign-in.')
+ })
+})
diff --git a/src/renderer/lib/githubSyncStatus.ts b/src/renderer/lib/githubSyncStatus.ts
index 3ffa233d1..9fa7804a9 100644
--- a/src/renderer/lib/githubSyncStatus.ts
+++ b/src/renderer/lib/githubSyncStatus.ts
@@ -2,7 +2,7 @@
// 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'
+import type { GitHubAuthStatus, GitHubRateStatus, GitHubThrottle } from '@shared/github-issues'
/** Local wall-clock time, hours and minutes. */
export function githubClock(ms: number): string {
@@ -25,3 +25,16 @@ export function githubRateSentence(
): string {
return `${rate.remaining.toLocaleString('en-US')} of ${rate.limit.toLocaleString('en-US')} GitHub requests left until ${clock(rate.resetAt)}.`
}
+
+/** The sign-in check could not reach an answer. Deliberately never "signed out": only GitHub
+ * refusing the credential means that, and this sentence is for everything that is not that. */
+export function githubUnreachableSentence(
+ unreachable: NonNullable<GitHubAuthStatus['unreachable']>,
+ clock: (ms: number) => string = githubClock
+): string {
+ if (unreachable.reason === 'rate-limited') {
+ return `GitHub’s rate limit was reached, so the sign-in could not be checked${
+ unreachable.retryAt !== undefined ? ` until ${clock(unreachable.retryAt)}` : ''}.`
+ }
+ return 'GitHub could not be reached to check the sign-in.'
+}
diff --git a/src/shared/github-issues.ts b/src/shared/github-issues.ts
index 3077fbd6b..92594f03a 100644
--- a/src/shared/github-issues.ts
+++ b/src/shared/github-issues.ts
@@ -56,6 +56,10 @@ export interface GitHubAuthStatus {
tokenPresent: boolean
storage: GitHubSecretAvailability
login?: string
+ /** Present when the sign-in could not be CHECKED — a network failure, a GitHub outage or a rate
+ * limit. It is not "signed out": the fields above keep the last answer GitHub gave for this
+ * token (or none, if it never gave one). `retryAt` is epoch ms, for a rate limit. */
+ unreachable?: { reason: 'rate-limited' | 'unreachable'; retryAt?: number }
}
/** The GitHub request budget last reported for the active identity (`x-ratelimit-*`), `core`