@young1lin/dsh-gpt-sub 0.1.0

package/src/jwt.ts

@@ -0,0 +1,26 @@
+/**
+ * Minimal JWT claim reader. Only the `exp` claim is needed, and signature
+ * verification is deliberately absent: these tokens are read from the user's
+ * own credential file, never accepted from a remote party.
+ *
+ * @module dsh-gpt-sub/jwt
+ */
+
+/**
+ * Read a JWT's expiry.
+ *
+ * @param token - a candidate JWT; opaque strings are tolerated.
+ * @returns expiry in epoch milliseconds, or undefined when absent or undecodable.
+ */
+export function jwtExpiryMs(token: string): number | undefined {
+  const payload = token.split('.')[1]
+  if (payload === undefined) return undefined
+  try {
+    const claims: unknown = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'))
+    if (typeof claims !== 'object' || claims === null) return undefined
+    const exp = (claims as { exp?: unknown }).exp
+    return typeof exp === 'number' ? exp * 1000 : undefined
+  } catch {
+    return undefined
+  }
+}

package/src/proxy-config.ts

@@ -0,0 +1,217 @@
+/**
+ * Runtime proxy configuration: request-body reading, URL validation, and the
+ * persisted override the settings panel writes.
+ *
+ * The override file exists because cordis config layers are the loader's
+ * property -- a panel edit cannot rewrite them. The file holds the panel's
+ * last saved choice; when present, it wins over the config's proxyUrl so a
+ * page edit survives restarts.
+ *
+ * @module dsh-gpt-sub/proxy-config
+ */
+
+import type { IncomingMessage } from 'node:http'
+import { readFile, rename, rm, writeFile } from 'node:fs/promises'
+
+/** Bodies larger than this are refused rather than buffered. */
+const BODY_LIMIT_BYTES = 65_536
+
+/** Read one header, tolerating the array form node uses for repeated headers. */
+function header(request: IncomingMessage, name: string): string | undefined {
+  const value = request.headers?.[name]
+  if (Array.isArray(value)) return value[0]
+  return value
+}
+
+/**
+ * Validate a caller-supplied proxy URL.
+ *
+ * @param value - the candidate value from a request body.
+ * @returns the trimmed URL, or the empty string for a direct connection.
+ * @throws Error when the value is not a string or not an http(s) URL.
+ */
+export function validateProxyUrl(value: unknown): string {
+  if (typeof value !== 'string') throw new Error('proxyUrl must be a string')
+  const trimmed = value.trim()
+  if (trimmed === '') return ''
+  let parsed: URL
+  try {
+    parsed = new URL(trimmed)
+  } catch {
+    throw new Error(`proxyUrl is not a valid URL: ${trimmed}`)
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`proxyUrl must be http or https, got ${parsed.protocol}`)
+  }
+  return trimmed
+}
+
+/**
+ * Mask any userinfo credentials in a proxy URL, for logging.
+ *
+ * The URL itself is worth logging; the password inside it is not. A URL
+ * without credentials is returned exactly as given.
+ *
+ * @param url - the proxy URL as configured.
+ * @returns the URL with its userinfo, if any, replaced by `***`.
+ */
+export function redactProxyUrl(url: string): string {
+  if (url === '') return ''
+  const scheme = /^https?:\/\//.exec(url)
+  if (scheme === null) return url
+  const rest = url.slice(scheme[0].length)
+  const credentialsEnd = rest.indexOf('@')
+  if (credentialsEnd === -1) return url
+  // Replace the userinfo by string surgery rather than URL re-serialisation,
+  // so everything after the `@` stays byte-identical to what was configured.
+  return `${scheme[0]}***@${rest.slice(credentialsEnd + 1)}`
+}
+
+/**
+ * Whether a request's Origin header names an origin other than the host the
+ * request was addressed to.
+ *
+ * The mutating routes must refuse such requests: a page on another origin can
+ * otherwise make the harness reroute its credentials through a proxy of the
+ * page's choosing. An absent Origin passes -- browsers always set one on a
+ * POST, so absence means a non-browser client such as curl.
+ *
+ * @param request - the incoming request.
+ * @returns true when Origin is present and names another host.
+ */
+export function crossOrigin(request: IncomingMessage): boolean {
+  const origin = header(request, 'origin')
+  if (origin === undefined || origin === '') return false
+  const host = header(request, 'host')
+  if (host === undefined || host === '') return true
+  try {
+    // Comparing through URL normalises default ports away on both sides.
+    return new URL(origin).host !== new URL(`http://${host}`).host
+  } catch {
+    // An unparsable Origin (including the literal "null") vouches for nothing.
+    return true
+  }
+}
+
+/**
+ * Read one JSON object request body.
+ *
+ * A body that declares a content-type must declare JSON: browsers refuse to
+ * send `application/json` cross-origin without a preflight, so the check
+ * turns every form a forged cross-site POST can take into a refusal. An
+ * absent content-type passes for non-browser clients that send none.
+ *
+ * @param request - the incoming request whose body to consume.
+ * @param limitBytes - the maximum body size accepted.
+ * @returns the parsed object.
+ * @throws Error when the body is oversized, unparseable, not an object, or
+ *   not JSON-content-typed.
+ */
+export async function readJsonObject(
+  request: IncomingMessage,
+  limitBytes = BODY_LIMIT_BYTES,
+): Promise<Record<string, unknown>> {
+  const contentType = header(request, 'content-type')
+  if (contentType !== undefined) {
+    const mediaType = contentType.split(';')[0]?.trim().toLowerCase() ?? ''
+    if (mediaType !== 'application/json') {
+      throw new Error(`request body content-type must be application/json, got "${mediaType}"`)
+    }
+  }
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of request) {
+    const piece = typeof chunk === 'string' ? Buffer.from(chunk) : (chunk as Buffer)
+    size += piece.length
+    if (size > limitBytes) throw new Error('request body too large')
+    chunks.push(piece)
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+  } catch {
+    throw new Error('request body is not valid JSON')
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error('request body must be a JSON object')
+  }
+  return parsed as Record<string, unknown>
+}
+
+/** The state file's on-disk shape; each field stands alone. */
+export interface StateOverride {
+  /** The saved proxy URL; empty string means direct. */
+  proxyUrl?: string
+  /** The saved credential-file path, exactly as typed on the page. */
+  authFile?: string
+}
+
+/**
+ * Load the persisted panel overrides.
+ *
+ * An absent file simply means "no override". A corrupt file is ignored too:
+ * the panel that wrote it may have died mid-write, and failing the whole
+ * plugin over a status file would trade working settings for a stale byte.
+ *
+ * Each known field validates on its own, so one invalid value drops without
+ * discarding the other choice the panel made.
+ *
+ * @param path - the state file's path.
+ * @returns the saved choices, or undefined when there is no readable file.
+ */
+export async function loadStateOverride(path: string): Promise<StateOverride | undefined> {
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch {
+    return undefined
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return undefined
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return undefined
+  const document = parsed as Record<string, unknown>
+
+  const state: StateOverride = {}
+  const proxyUrl = document['proxyUrl']
+  if (typeof proxyUrl === 'string') {
+    try {
+      state.proxyUrl = validateProxyUrl(proxyUrl)
+    } catch {
+      // A stale invalid proxy falls back to the config rather than
+      // invalidating the whole file.
+    }
+  }
+  const authFile = document['authFile']
+  if (typeof authFile === 'string' && authFile.trim() !== '') {
+    state.authFile = authFile.trim()
+  }
+  return state
+}
+
+/**
+ * Persist the panel's choices atomically, so a crash never leaves a half write.
+ *
+ * The object is written exactly as given; callers read-modify-write so saving
+ * one choice never erases the other.
+ *
+ * @param path - the state file's path.
+ * @param state - the choices to persist; absent fields mean "use the config".
+ * @returns nothing; failures propagate to the caller.
+ */
+export async function saveStateOverride(path: string, state: StateOverride): Promise<void> {
+  const temporary = `${path}.tmp-${String(process.pid)}`
+  // The file can hold a proxy URL with embedded credentials and a private
+  // filesystem layout, so create it private to the user, the same way
+  // token-store writes auth.json.
+  await writeFile(temporary, JSON.stringify(state, null, 2), { encoding: 'utf8', mode: 0o600 })
+  try {
+    await rename(temporary, path)
+  } catch (error) {
+    await rm(temporary, { force: true })
+    throw error
+  }
+}

package/src/proxy-probe.ts

@@ -0,0 +1,81 @@
+/**
+ * Connectivity probe for a candidate proxy: one real usage read through a
+ * throwaway ProxyAgent, timed, answering ok/latency or the failure text.
+ *
+ * This is the host half of the panel's "test connection" button. It exercises
+ * the exact path production traffic takes -- same host, same endpoint, same
+ * dispatcher kind -- so a green result means model calls will connect, not
+ * merely that the proxy's TCP port answers.
+ *
+ * @module dsh-gpt-sub/proxy-probe
+ */
+
+import { ProxyAgent, fetch as undiciFetch } from 'undici'
+import { fetchUsage } from './usage.ts'
+
+/** Default ceiling on one probe; a proxy that cannot answer this is broken. */
+const DEFAULT_TIMEOUT_MS = 15_000
+
+/** What the probe answers. */
+export interface ProxyProbeResult {
+  /** True when the usage endpoint answered through the candidate. */
+  ok: boolean
+  /** Round-trip milliseconds; present on success. */
+  latencyMs?: number
+  /** Subscription plan reported upstream; present on success when known. */
+  plan?: string
+  /** Failure text; present when ok is false. */
+  message?: string
+}
+
+/** Construction options; the injectable seams exist for tests. */
+export interface ProxyProbeOptions {
+  /** Candidate proxy URL; empty string probes a direct connection. */
+  readonly proxyUrl: string
+  /** A live access token for the usage call. */
+  readonly accessToken: string
+  /** Per-probe timeout; defaults to {@link DEFAULT_TIMEOUT_MS}. */
+  readonly timeoutMs?: number
+  /** Injectable fetch, defaulting to undici's. */
+  readonly fetchImpl?: typeof undiciFetch
+  /** Injectable clock, defaulting to Date.now. */
+  readonly now?: () => number
+}
+
+/**
+ * Probe one candidate proxy with a single usage read.
+ *
+ * The probe's ProxyAgent is private: it is created here and closed here, so a
+ * probe can never leak dispatcher state into the live routing.
+ *
+ * @param options - the candidate and the credentials to read with.
+ * @returns the probe outcome, never a rejection.
+ */
+export async function probeProxy(options: ProxyProbeOptions): Promise<ProxyProbeResult> {
+  const { proxyUrl, accessToken } = options
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const now = options.now ?? (() => Date.now())
+  const agent = proxyUrl === '' ? undefined : new ProxyAgent(proxyUrl)
+  const started = now()
+  try {
+    const usage = await fetchUsage(
+      accessToken,
+      agent,
+      options.fetchImpl,
+      AbortSignal.timeout(timeoutMs),
+    )
+    const latencyMs = now() - started
+    return {
+      ok: true,
+      latencyMs,
+      ...(usage.plan_type === undefined ? {} : { plan: usage.plan_type }),
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      message: error instanceof Error ? error.message : String(error),
+    }
+  } finally {
+    if (agent !== undefined) await agent.close().catch(() => undefined)
+  }
+}

package/src/proxy-routing.ts

@@ -0,0 +1,205 @@
+/**
+ * Host-scoped proxy routing for the process-wide undici dispatcher.
+ *
+ * pi-ai issues its own requests through the global `fetch`, so this plugin
+ * cannot hand it a dispatcher the way it hands one to `TokenStore`. The only
+ * seam is undici's global dispatcher -- but replacing that wholesale would
+ * push every provider in the harness through the proxy, including endpoints
+ * that must not go near it.
+ *
+ * So route by hostname: the Codex hosts go through the proxy, everything else
+ * continues to whatever dispatcher was installed before. Reaching
+ * `chatgpt.com` from an unproxied address here answers 403 with a Cloudflare
+ * block page, which surfaces as an unreadable HTML body rather than an API
+ * error, so this is the difference between working and not.
+ *
+ * @module dsh-gpt-sub/proxy-routing
+ */
+
+import { Dispatcher, ProxyAgent, getGlobalDispatcher, interceptors, setGlobalDispatcher } from 'undici'
+
+/**
+ * Transport failures worth retrying: the link to this proxy drops connections
+ * at random, and each drop surfaces to DSH as a bare `fetch failed`.
+ *
+ * Measured direct to chatgpt.com through the same proxy, the failure is
+ * non-monotonic in payload size, so it is a random connection failure rather
+ * than a threshold -- which is exactly the shape a retry fixes.
+ */
+const RETRYABLE_ERROR_CODES = [
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'ENOTFOUND',
+  'ENETDOWN',
+  'ENETUNREACH',
+  'EHOSTDOWN',
+  'EHOSTUNREACH',
+  'EPIPE',
+  'ETIMEDOUT',
+  'UND_ERR_SOCKET',
+  'UND_ERR_CONNECT_TIMEOUT',
+]
+
+/**
+ * Hosts that must egress through the proxy: the Codex API and the OAuth token
+ * endpoint the refresh calls. Subdomains match too.
+ */
+export const PROXIED_HOSTS: readonly string[] = ['chatgpt.com', 'auth.openai.com', 'api.openai.com']
+
+/**
+ * Whether a hostname belongs to one of `hosts`, matching the host itself and
+ * any subdomain of it.
+ *
+ * @param hostname - the hostname to test.
+ * @param hosts - the suffixes to match against.
+ * @returns true when the hostname should be proxied.
+ */
+export function shouldProxy(hostname: string, hosts: readonly string[] = PROXIED_HOSTS): boolean {
+  const lower = hostname.toLowerCase()
+  return hosts.some((host) => lower === host || lower.endsWith(`.${host}`))
+}
+
+/**
+ * A dispatcher that sends matching hosts to one delegate and everything else
+ * to another.
+ *
+ * Only the proxy delegate is owned: `close`/`destroy` never touch the
+ * fallback, because that dispatcher belongs to the host and outlives this
+ * plugin.
+ */
+export class HostRoutingDispatcher extends Dispatcher {
+  readonly #proxy: Dispatcher
+  readonly #fallback: Dispatcher
+  readonly #hosts: readonly string[]
+
+  constructor(proxy: Dispatcher, fallback: Dispatcher, hosts: readonly string[] = PROXIED_HOSTS) {
+    super()
+    this.#proxy = proxy
+    this.#fallback = fallback
+    this.#hosts = hosts
+  }
+
+  /**
+   * Route one request by its origin's hostname.
+   *
+   * An origin that cannot be parsed is sent to the fallback: defaulting to the
+   * proxy would silently divert unrelated traffic.
+   *
+   * @param options - undici dispatch options.
+   * @param handler - undici dispatch handler.
+   * @returns whatever the chosen delegate returns.
+   */
+  override dispatch(options: Dispatcher.DispatchOptions, handler: Dispatcher.DispatchHandler): boolean {
+    let hostname = ''
+    try {
+      const origin = options.origin
+      hostname = new URL(typeof origin === 'string' ? origin : String(origin?.href ?? '')).hostname
+    } catch {
+      hostname = ''
+    }
+    const delegate = hostname !== '' && shouldProxy(hostname, this.#hosts) ? this.#proxy : this.#fallback
+    return delegate.dispatch(options, handler)
+  }
+
+  /** Close only the proxy delegate; the fallback belongs to the host. */
+  override async close(): Promise<void> {
+    await this.#proxy.close()
+  }
+
+  /** Destroy only the proxy delegate; the fallback belongs to the host. */
+  override async destroy(): Promise<void> {
+    await this.#proxy.destroy()
+  }
+}
+
+/**
+ * Retry options that absorb a dropped connection without taking on any
+ * HTTP-level retry policy.
+ *
+ * `statusCodes: []` is deliberate: an upstream 429 or 500 carries a body DSH
+ * knows how to read and surface, and retrying here would swallow it. This
+ * dispatcher's job is narrow -- make the flaky link look reliable -- and every
+ * HTTP semantic stays with the harness.
+ *
+ * `POST` is listed even though undici omits it by default, because undici
+ * omits it for non-idempotency: a POST that may have been received must not be
+ * replayed. That does not apply to what is retried here. A connection error
+ * arrives before any response, and undici refuses to replay a request whose
+ * body was already consumed; a partially streamed response is caught by
+ * undici's own range check rather than silently concatenated. Model calls are
+ * POSTs, so without this the retry would never fire at all.
+ *
+ * @param maxRetries - how many extra attempts a single request may make.
+ * @returns options for undici's retry interceptor.
+ */
+export function connectionRetryOptions(maxRetries: number): {
+  maxRetries: number
+  methods: string[]
+  statusCodes: number[]
+  errorCodes: string[]
+  minTimeout: number
+  maxTimeout: number
+  timeoutFactor: number
+} {
+  return {
+    maxRetries,
+    methods: ['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE', 'TRACE', 'POST'],
+    statusCodes: [],
+    errorCodes: [...RETRYABLE_ERROR_CODES],
+    // 0.5s, 1s, 2s -- fast enough that a recovered connection still feels like
+    // one request, slow enough to let a flapping tunnel settle.
+    minTimeout: 500,
+    maxTimeout: 8_000,
+    timeoutFactor: 2,
+  }
+}
+
+/** What {@link installProxyRouting} returns, so the caller can undo it. */
+export interface ProxyRouting {
+  /** The proxy agent, for handing to components that take an explicit dispatcher. */
+  readonly dispatcher: Dispatcher
+  /** Restore the previous global dispatcher and close the proxy agent. */
+  readonly uninstall: () => Promise<void>
+}
+
+/** Options for {@link installProxyRouting}. */
+export interface ProxyRoutingOptions {
+  /** Hostnames to proxy; defaults to {@link PROXIED_HOSTS}. */
+  readonly hosts?: readonly string[]
+  /** Extra attempts per request after a connection failure. 0 disables retry. */
+  readonly maxRetries?: number
+}
+
+/**
+ * Install host-scoped proxy routing as the global dispatcher.
+ *
+ * @param proxyUrl - the proxy to route the Codex hosts through.
+ * @param options - hosts to proxy and how hard to retry a dropped connection.
+ * @returns the proxy dispatcher and the function that restores the previous global.
+ */
+export function installProxyRouting(proxyUrl: string, options: ProxyRoutingOptions = {}): ProxyRouting {
+  const hosts = options.hosts ?? PROXIED_HOSTS
+  const maxRetries = options.maxRetries ?? 3
+  const proxy = new ProxyAgent(proxyUrl)
+  // `compose` returns a proxy over the same agent with only `dispatch`
+  // replaced, so `close()` on the result still closes the agent underneath --
+  // and only requests routed here are retried. Nothing else in the harness
+  // changes behaviour.
+  const dispatcher =
+    maxRetries > 0 ? proxy.compose(interceptors.retry(connectionRetryOptions(maxRetries))) : proxy
+  const previous = getGlobalDispatcher()
+  setGlobalDispatcher(new HostRoutingDispatcher(dispatcher, previous, hosts))
+
+  return {
+    dispatcher,
+    uninstall: async () => {
+      // Restore first, so nothing dispatches into a closing agent.
+      setGlobalDispatcher(previous)
+      try {
+        await proxy.close()
+      } catch {
+        // Disposal must not hinge on the agent shutting down cleanly.
+      }
+    },
+  }
+}

package/src/quota-route.ts

@@ -0,0 +1,163 @@
+/**
+ * The host half of the quota panel: one cached JSON endpoint the browser polls.
+ *
+ * Every quota semantic lives here rather than in the client bundle -- which
+ * windows count, how often upstream may be asked, what a failure looks like --
+ * so the browser half stays a renderer.
+ *
+ * @module dsh-gpt-sub/quota-route
+ */
+
+import type { Dispatcher } from 'undici'
+import { fetchUsage, reportWindows, reportedWindows, resetsRemaining, type ReportedWindow, type UsageWindow } from './usage.ts'
+
+/** One rate-limit window as the endpoint serves it to the panel. */
+export interface QuotaWindowState {
+  /** Percent of the window consumed. */
+  usedPercent: number
+  /** Length of the window, in hours. */
+  windowHours: number
+  /** Epoch seconds at which the window resets. */
+  resetAt?: number
+}
+
+/** What the endpoint serves. */
+export interface QuotaState {
+  /** 'ready' once a reading has been taken, 'error' when none ever succeeded. */
+  phase: 'ready' | 'error'
+  /** Subscription plan, when upstream reported one. */
+  plan?: string
+  /**
+   * The short rolling window -- 5 hours on every plan that reports one. A
+   * plan without it (pro currently) simply omits the field, and the panel
+   * says so instead of drawing an empty bar.
+   */
+  fiveHour?: QuotaWindowState
+  /** The weekly window, alone or beside the 5-hour one. */
+  weekly?: QuotaWindowState
+  /**
+   * On-demand usage resets the account can still spend, when the plan
+   * reports them -- each clears a capped window without waiting out its
+   * timer.
+   */
+  resetsRemaining?: number
+  /** Every reported window, primary first; one panel row each. */
+  windows?: ReportedWindow[]
+  /** Epoch milliseconds this reading was taken. */
+  fetchedAt?: number
+  /** True when the reading is older than the refresh interval and a retry failed. */
+  stale?: boolean
+  /** Human-readable failure note; present on error, or beside a stale reading. */
+  message?: string
+}
+
+/** Windows shorter than a day are the 5-hour-style rolling limit. */
+const DAY_SECONDS = 24 * 3600
+
+/**
+ * Fold one upstream window into the shape the panel renders.
+ *
+ * @param window - a window as the usage endpoint reported it.
+ * @returns the same figures in the panel's vocabulary.
+ */
+const toWindowState = (window: UsageWindow): QuotaWindowState => ({
+  usedPercent: window.used_percent,
+  windowHours: Math.round(window.limit_window_seconds / 3600),
+  ...(window.reset_at === undefined ? {} : { resetAt: window.reset_at }),
+})
+
+/** Construction options. */
+export interface QuotaSourceOptions {
+  /** Returns a live access token. */
+  readonly accessToken: () => Promise<string>
+  /** Dispatcher for the upstream call. */
+  readonly dispatcher?: Dispatcher
+  /** Minimum gap between upstream reads; a poll inside it is served from cache. */
+  readonly minIntervalMs?: number
+  /** Injectable clock, defaulting to Date.now. */
+  readonly now?: () => number
+}
+
+/**
+ * A throttled quota reader.
+ *
+ * The browser polls far more often than the account's usage changes, so an
+ * unthrottled endpoint would turn one open settings page into a steady stream
+ * of upstream requests.
+ */
+export class QuotaSource {
+  readonly #accessToken: () => Promise<string>
+  #dispatcher: Dispatcher | undefined
+  readonly #minIntervalMs: number
+  readonly #now: () => number
+  #state: QuotaState = { phase: 'error', message: 'not read yet' }
+  #lastAttempt = 0
+  /** The in-flight read, shared by every caller that arrives during it. */
+  #inFlight: Promise<QuotaState> | undefined
+
+  constructor(options: QuotaSourceOptions) {
+    this.#accessToken = options.accessToken
+    this.#dispatcher = options.dispatcher
+    this.#minIntervalMs = options.minIntervalMs ?? 60_000
+    this.#now = options.now ?? (() => Date.now())
+  }
+
+  /**
+   * Point later upstream reads at a different dispatcher, as a proxy switch does.
+   *
+   * @param dispatcher - the dispatcher future reads use; undefined for the global.
+   */
+  setDispatcher(dispatcher: Dispatcher | undefined): void {
+    this.#dispatcher = dispatcher
+  }
+
+  /**
+   * Return the current reading, refreshing when the throttle allows.
+   *
+   * @param force - ignore the throttle, as the panel's refresh button does.
+   * @returns the reading to serve.
+   */
+  async read(force = false): Promise<QuotaState> {
+    const elapsed = this.#now() - this.#lastAttempt
+    if (!force && this.#state.phase === 'ready' && elapsed < this.#minIntervalMs) return this.#state
+    this.#inFlight ??= this.#refresh().finally(() => {
+      this.#inFlight = undefined
+    })
+    return this.#inFlight
+  }
+
+  /**
+   * Take one upstream reading and fold it into the cached state.
+   *
+   * A failure never discards a previous good reading: the panel shows the last
+   * known figure marked stale, which is more useful than an empty panel.
+   *
+   * @returns the new state.
+   */
+  async #refresh(): Promise<QuotaState> {
+    this.#lastAttempt = this.#now()
+    try {
+      const usage = await fetchUsage(await this.#accessToken(), this.#dispatcher)
+      const reported = reportedWindows(usage)
+      const fiveHour = reported.find((window) => window.limit_window_seconds < DAY_SECONDS)
+      const weekly = reported.find((window) => window.limit_window_seconds >= DAY_SECONDS)
+      const resets = resetsRemaining(usage)
+      const windows = reportWindows(usage)
+      this.#state = {
+        phase: 'ready',
+        ...(usage.plan_type === undefined ? {} : { plan: usage.plan_type }),
+        ...(fiveHour === undefined ? {} : { fiveHour: toWindowState(fiveHour) }),
+        ...(weekly === undefined ? {} : { weekly: toWindowState(weekly) }),
+        ...(resets === undefined ? {} : { resetsRemaining: resets }),
+        ...(windows.length === 0 ? {} : { windows }),
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      this.#state =
+        this.#state.phase === 'ready'
+          ? { ...this.#state, stale: true, message }
+          : { phase: 'error', message }
+    }
+    return this.#state
+  }
+}