@jameslovespancakes/pi-plus 1.0.21 → 1.0.23

package/README.md

@@ -37,9 +37,10 @@ the app's Stop button stops the agent. Your selected model still runs through pi
 ──────────────────────────────────────
 ```
 
-**`/claude-remote`** toggles On/Off. On connects now and auto-starts in future
-interactive sessions; Off disconnects and disables auto-start. The footer dot
-is green when connected and red otherwise.
+**`/claude-remote`** toggles On/Off for this session only. Startup, new sessions,
+resumes, forks, and reloads always start Off; old auto-start preferences are
+ignored. Off disconnects immediately. The footer dot is green when connected
+and red otherwise.
 
 Off by default. Requires your primary Anthropic OAuth login via `/login`.
 Experimental: text input and completed-message mirroring, not token streaming.
@@ -88,6 +89,16 @@ usage in the footer. Supports Anthropic, OpenAI Codex, Gemini, Kimi Code, and xA
 **`/routing quota-aware`** uses reported capacity; **`/routing sequential`**
 follows account order. **`/usage`** refreshes the bars.
 
+Claude usage comes from response headers first, with a shared cached status
+fetch when needed. Cooldowns survive restarts and are respected by `/usage`;
+usage checks never generate model responses or consume inference tokens.
+
+Gemini login and reauthorization confirm account access before reporting success.
+If Google requires verification, its verification page opens through pi's auth UI;
+complete it, then choose **check again**. Credentials are saved only after the
+server confirms access. Background quota checks never open a browser; they point
+you to `/login gemini` or `/accounts reauth gemini <name>` when verification is needed.
+
 Quota visibility depends on the provider. Where no usage endpoint exists,
 pi-plus shows the last observed rate-limit reading rather than inventing one.
 
@@ -114,11 +125,23 @@ boundary, including workflow subagents—not just through prompt instructions.
 ──────────────────────────────────────
  Providers
 › ● Anthropic              Allowed
-  ● OpenRouter             Needs Approval
+  ● OpenRouter             Off
 ──────────────────────────────────────
 ```
 
 **`/provider`** opens the picker. Enter or Space toggles access in place.
+OpenRouter cycles **Off → On → On (ZDR) → Off**. Grants are session-local;
+explicit policy denials stay locked. Other providers keep their existing toggles.
+
+**On (ZDR)** restricts OpenRouter inference to Zero Data Retention endpoints,
+including workflow agents and compaction. No eligible endpoint means an error,
+never a non-ZDR retry; fallback among ZDR endpoints is allowed. Native Chat
+Completions and Anthropic Messages routes are supported; unsupported APIs or
+custom endpoints fail closed. Ordinary On does not remove account-level privacy
+rules. ZDR does not cover separately enabled search plugins or local session logs.
+
+Commands: `/provider approve openrouter`, `/provider zdr openrouter`, and
+`/provider remove openrouter`.
 
 ## Workflows
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jameslovespancakes/pi-plus",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "type": "module",
   "description": "pi and more",
   "license": "MIT",

package/src/core/anthropic/quota.ts

@@ -1,6 +1,5 @@
-import { createHash, randomUUID } from "node:crypto";
-import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { createHash } from "node:crypto";
+import { acquireFileLease } from "../file-lease.ts";
 import { refreshAbortSignal } from "../accounts/routing.ts";
 import {
   configPath as defaultConfigPath,
@@ -12,10 +11,7 @@ import {
 } from "./store.ts";
 import { refreshToken, type RefreshOptions, type TokenSet } from "./oauth.ts";
 
-/** Uses free response headers first, polling only stale idle accounts. */
-
-const QUOTA_URL = "https://api.anthropic.com/api/oauth/usage";
-const TIMEOUT_MS = 10_000;
+/** Quota parsing and pooled credential refresh. Status I/O lives in usage-cache.ts. */
 /** Refresh early enough to absorb transient OAuth rate limits before expiry. */
 export const ACCESS_REFRESH_WINDOW_MS = 4 * 60 * 60_000;
 /** Background refresh cadence; each process adds a small startup jitter. */
@@ -24,26 +20,8 @@ const REFRESH_LOCK_TTL_MS = 60_000;
 const REFRESH_JOIN_WAIT_MS = 16_000;
 /** Snapshot lifetime and minimum interval between polls. */
 export const QUOTA_FRESH_MS = 10 * 60_000;
-/** After a 429, wait at least this long before touching the endpoint again. */
-export const QUOTA_BACKOFF_MS = 15 * 60_000;
-
-/** Per-account earliest next poll, set when the endpoint rate limits us. */
-const blockedUntil = new Map<string, number>();
-
-/** True when a recent 429 means this account must not be polled yet. */
-export function isPollBlocked(accountId: string, now = Date.now()): boolean {
-  const until = blockedUntil.get(accountId);
-  if (until === undefined) return false;
-  if (now >= until) { blockedUntil.delete(accountId); return false; }
-  return true;
-}
-
-/** Visible for tests; clears the backoff table. */
-export function resetPollBackoff(): void {
-  blockedUntil.clear();
-}
-
 const pct = (value: unknown): number | undefined => {
+  if (value == null || typeof value === "boolean" || (typeof value === "string" && !value.trim())) return undefined;
   const n = typeof value === "number" ? value : Number(value);
   return Number.isFinite(n) ? Math.min(100, Math.max(0, n)) : undefined;
 };
@@ -58,6 +36,7 @@ export function parseQuota(body: any, now = Date.now()): QuotaSnapshot {
       remainingPercent: 100 - used,
       resetsAt: typeof raw?.resets_at === "string" ? raw.resets_at : undefined,
       checkedAt: now,
+      capacity: typeof raw?.limit_dollars === "number" && raw.limit_dollars > 0 ? raw.limit_dollars : undefined,
     };
   };
 
@@ -79,9 +58,15 @@ export function parseQuota(body: any, now = Date.now()): QuotaSnapshot {
     })
     .filter(Boolean);
 
+  for (const [id, raw] of [["opus", body?.seven_day_opus ?? body?.seven_day_omelette], ["sonnet", body?.seven_day_sonnet]] as const) {
+    const value = window(raw);
+    if (value && !scoped.some((entry: { id: string }) => entry.id === id)) scoped.push({ id, ...value });
+  }
+
   return {
     five_hour: window(body?.five_hour),
     seven_day: window(body?.seven_day),
+    extra: body?.extra_usage?.is_enabled ? window(body.extra_usage) : undefined,
     scoped: scoped.length ? scoped : undefined,
     checkedAt: now,
     source: "poll",
@@ -114,7 +99,7 @@ export function parseQuotaHeaders(
 
   const window = (prefix: string) => {
     const raw = get(`${prefix}-utilization`);
-    if (raw === undefined) return undefined;
+    if (raw === undefined || !raw.trim()) return undefined;
     const fraction = Number(raw);
     if (!Number.isFinite(fraction)) return undefined;
 
@@ -137,60 +122,6 @@ export function parseQuotaHeaders(
   return { five_hour, seven_day, checkedAt: now, source: "headers" };
 }
 
-/** Merges header quota while preserving polled model limits. */
-export function applyQuotaHeaders(
-  accountId: string,
-  headers: Record<string, unknown> | undefined,
-  now = Date.now(),
-): boolean {
-  const fresh = parseQuotaHeaders(headers, now);
-  if (!fresh) return false;
-
-  const storage = loadAccounts();
-  const account = storage?.accounts.find((a) => a.id === accountId);
-  if (!account) return false;
-
-  // Skip unchanged values to avoid credential writes on every response.
-  const previous = account.quota;
-  const unchanged =
-    previous?.five_hour?.usedPercent === fresh.five_hour?.usedPercent
-    && previous?.seven_day?.usedPercent === fresh.seven_day?.usedPercent;
-  if (unchanged) return false;
-
-  saveAccount({ ...account, quota: { ...fresh, scoped: previous?.scoped } });
-  return true;
-}
-
-/** Polls one account and records rate-limit backoff. */
-export async function pollQuota(
-  accessToken: string,
-  accountId?: string,
-): Promise<QuotaSnapshot | undefined> {
-  if (accountId && isPollBlocked(accountId)) return undefined;
-  try {
-    const response = await fetch(QUOTA_URL, {
-      headers: {
-        Authorization: `Bearer ${accessToken}`,
-        "anthropic-beta": "oauth-2025-04-20",
-        Accept: "application/json",
-      },
-      signal: AbortSignal.timeout(TIMEOUT_MS),
-    });
-    if (response.status === 429 && accountId) {
-      // `retry-after` is commonly 0 here, which is not a usable hint, so the
-      // floor is ours rather than the server's.
-      const hint = Number(response.headers.get("retry-after")) * 1000;
-      const wait = Number.isFinite(hint) && hint > 0 ? hint : QUOTA_BACKOFF_MS;
-      blockedUntil.set(accountId, Date.now() + Math.max(wait, QUOTA_BACKOFF_MS));
-      return undefined;
-    }
-    if (!response.ok) return undefined;
-    return parseQuota(await response.json());
-  } catch {
-    return undefined;
-  }
-}
-
 export function accessTokenNeedsRefresh(account: Account, now = Date.now()): boolean {
   return !account.access
     || typeof account.expires !== "number"
@@ -205,14 +136,6 @@ export interface EnsureAccessTokenOptions {
   refresh?: RefreshTokenFn;
 }
 
-export interface RefreshAllQuotaOptions extends EnsureAccessTokenOptions {
-  poll?: typeof pollQuota;
-}
-
-interface RefreshLock {
-  release(): void;
-}
-
 const refreshes = new Map<string, Promise<string | undefined>>();
 
 function refreshLockPath(accountId: string, config: string): string {
@@ -220,45 +143,6 @@ function refreshLockPath(accountId: string, config: string): string {
   return `${statePath(config)}.refresh-${id}.lock`;
 }
 
-/** Cross-process exclusion for Anthropic's rotating refresh tokens. */
-function acquireRefreshLock(accountId: string, config: string, now: number): RefreshLock | undefined {
-  const path = refreshLockPath(accountId, config);
-  const owner = randomUUID();
-  mkdirSync(dirname(path), { recursive: true });
-
-  for (let attempt = 0; attempt < 2; attempt++) {
-    try {
-      const fd = openSync(path, "wx", 0o600);
-      try {
-        writeFileSync(fd, JSON.stringify({ owner, expiresAt: now + REFRESH_LOCK_TTL_MS }), "utf8");
-      } finally {
-        closeSync(fd);
-      }
-      return {
-        release() {
-          try {
-            const current = JSON.parse(readFileSync(path, "utf8"));
-            if (current?.owner === owner) rmSync(path, { force: true });
-          } catch {
-            // A stale or externally removed lock needs no cleanup.
-          }
-        },
-      };
-    } catch (error: any) {
-      if (error?.code !== "EEXIST") throw error;
-      try {
-        const current = JSON.parse(readFileSync(path, "utf8"));
-        if (Number(current?.expiresAt) > now) return undefined;
-        rmSync(path, { force: true });
-      } catch {
-        // A malformed lock is stale; remove it and retry once.
-        try { rmSync(path, { force: true }); } catch { /* best effort */ }
-      }
-    }
-  }
-  return undefined;
-}
-
 function storedAccount(accountId: string, config: string): Account | undefined {
   return loadAccounts(config)?.accounts.find((candidate) => candidate.id === accountId);
 }
@@ -304,7 +188,7 @@ async function refreshAccountNow(
   if (!accessTokenNeedsRefresh(latest, now())) return latest.access;
   if (!latest.refresh) return usableAccess(latest, now());
 
-  const lock = acquireRefreshLock(account.id, config, now());
+  const lock = acquireFileLease(refreshLockPath(account.id, config), REFRESH_LOCK_TTL_MS, now());
   if (!lock) return joinConcurrentRefresh(latest, config, now);
 
   try {
@@ -381,41 +265,3 @@ export async function refreshDueAccessTokens(
   }));
   return results.filter(Boolean).length;
 }
-
-/** Refreshes due access tokens, then polls only stale quota snapshots. */
-export async function refreshAllQuota(
-  force = false,
-  config = defaultConfigPath(),
-  options: RefreshAllQuotaOptions = {},
-): Promise<number> {
-  await refreshDueAccessTokens(config, options);
-  const storage = loadAccounts(config);
-  if (!storage) return 0;
-  const now = options.now?.() ?? Date.now();
-  const poll = options.poll ?? pollQuota;
-
-  const stale = storage.accounts.filter(
-    (a) => a.enabled !== false && a.type === "oauth"
-      && (force || !isFresh(a.quota, now))
-      && !isPollBlocked(a.id, now));
-
-  const results = await Promise.all(stale.map(async (account) => {
-    try {
-      const token = await ensureAccessToken(account, { ...options, config });
-      if (!token) return false;
-      const quota = await poll(token, account.id);
-      if (!quota) return false;
-      // Do not restore the pre-refresh account snapshot here. That used to
-      // overwrite a freshly rotated access/refresh pair with the now-invalid
-      // old pair immediately after a successful quota poll.
-      const current = storedAccount(account.id, config);
-      if (!current || current.access !== token) return false;
-      saveAccount({ ...current, quota }, config);
-      return true;
-    } catch {
-      return false;
-    }
-  }));
-
-  return results.filter(Boolean).length;
-}

package/src/core/anthropic/store.ts

@@ -20,6 +20,7 @@ export const CONFIG_FILE = "anthropic-auth.json";
 export const STATE_FILE = "anthropic-auth-state.json";
 
 export interface QuotaWindow {
+  capacity?: number;
   remainingPercent?: number;
   usedPercent?: number;
   resetsAt?: string;
@@ -30,6 +31,7 @@ export interface QuotaWindow {
 export interface QuotaSnapshot {
   five_hour?: QuotaWindow;
   seven_day?: QuotaWindow;
+  extra?: QuotaWindow;
   scoped?: QuotaWindow[];
   checkedAt?: number;
   source?: "poll" | "headers";

package/src/core/anthropic/usage-cache.ts

@@ -0,0 +1,141 @@
+import { createHash } from "node:crypto";
+import { acquireFileLease } from "../file-lease.ts";
+import { readJson, writeJson } from "../store.ts";
+import { cachedAnthropicAccountIdentity } from "./identity.ts";
+import { isFresh, parseQuota, parseQuotaHeaders, QUOTA_FRESH_MS } from "./quota.ts";
+import { loadAccounts, statePath, type QuotaSnapshot } from "./store.ts";
+
+export const QUOTA_BACKOFF_MS = 15 * 60_000;
+const MAX_BACKOFF_MS = 2 * 60 * 60_000;
+const LEASE_MS = 60_000;
+
+export interface ClaudeUsageAccount {
+  access: string;
+  identity?: string;
+  id?: string;
+  /** Read old snapshots without maintaining a second quota store. */
+  quota?: QuotaSnapshot;
+}
+interface UsageCache {
+  quota?: QuotaSnapshot;
+  nextPollAt?: number;
+  failures?: number;
+  error?: string;
+}
+
+const hash = (value: string) => createHash("sha256").update(value).digest("hex");
+function cachePath(account: ClaudeUsageAccount): string {
+  const key = account.identity ? `identity:${account.identity}` : account.id ? `account:${account.id}` : `token:${account.access}`;
+  return `${statePath()}.usage-${hash(key)}.json`;
+}
+
+function cachePaths(account: ClaudeUsageAccount): string[] {
+  // The token alias preserves cooldown when identity discovery is temporarily unavailable.
+  return [...new Set([cachePath(account), cachePath({ access: account.access })])];
+}
+function lockCache(paths: string[], now: number): (() => void) | undefined {
+  const leases: Array<{ release(): void }> = [];
+  const release = () => leases.forEach((lease) => lease.release());
+  try {
+    for (const path of paths) {
+      const lease = acquireFileLease(`${path}.lock`, LEASE_MS, now);
+      if (!lease) { release(); return undefined; }
+      leases.push(lease);
+    }
+    return release;
+  } catch (error) { release(); throw error; }
+}
+const readCache = (paths: string[]): UsageCache => paths.map((path) => readJson<UsageCache>(path, {}))
+  .sort((a, b) => (b.nextPollAt ?? 0) - (a.nextPollAt ?? 0))[0] ?? {};
+const saveCache = (paths: string[], cache: UsageCache): boolean => paths.every((path) => writeJson(path, cache, false, 0o600));
+
+/** Preserve missing windows and each window's own observation time. */
+function mergeQuota(previous: QuotaSnapshot | undefined, next: QuotaSnapshot): QuotaSnapshot {
+  const merged = { ...previous, ...next };
+  for (const key of ["five_hour", "seven_day"] as const) {
+    const old = previous?.[key], fresh = next[key];
+    const observedAt = fresh?.checkedAt ?? next.checkedAt ?? 0;
+    merged[key] = fresh && observedAt >= (old?.checkedAt ?? 0) ? {
+      ...old, ...fresh,
+      resetsAt: fresh.resetsAt ?? (Date.parse(old?.resetsAt ?? "") > observedAt ? old?.resetsAt : undefined),
+    } : old;
+  }
+  merged.scoped = next.scoped ?? previous?.scoped;
+  merged.extra = next.extra ?? previous?.extra;
+  return merged;
+}
+
+/** Shared disk cache, with token-keyed observations as a fallback before identity discovery. */
+export function cachedClaudeQuota(account: ClaudeUsageAccount): QuotaSnapshot | undefined {
+  const samples = [account.quota, ...cachePaths(account).map((path) => readJson<UsageCache>(path, {}).quota)]
+    .filter((quota): quota is QuotaSnapshot => !!quota)
+    .sort((a, b) => (a.checkedAt ?? 0) - (b.checkedAt ?? 0));
+  return samples.reduce<QuotaSnapshot | undefined>((merged, sample) => mergeQuota(merged, sample), undefined);
+}
+
+/** Free telemetry from the actual request credential; never use a global last-routed account. */
+export function observeClaudeQuota(access: string, headers: Record<string, unknown>, now = Date.now()): void {
+  const fresh = parseQuotaHeaders(headers, now);
+  if (!fresh) return;
+  const account = loadAccounts()?.accounts.find((candidate) => candidate.access === access);
+  const target = { access, id: account?.id, identity: account?.identity ?? cachedAnthropicAccountIdentity(access), quota: account?.quota };
+  const paths = cachePaths(target);
+  const release = lockCache(paths, now);
+  if (!release) return; // An in-flight status fetch will refresh this account instead.
+  try {
+    saveCache(paths, { ...readCache(paths), quota: mergeQuota(cachedClaudeQuota(target), fresh) });
+  } finally { release(); }
+}
+
+function hasFreshWindows(quota: QuotaSnapshot | undefined, now: number): boolean {
+  return [quota?.five_hour, quota?.seven_day].every((window) =>
+    window && isFresh({ checkedAt: window.checkedAt ?? quota?.checkedAt }, now));
+}
+
+/** The only Claude status fetch path. Manual refresh and process restarts cannot bypass its cooldown. */
+export async function readClaudeQuota(account: ClaudeUsageAccount, now = Date.now()): Promise<{ quota?: QuotaSnapshot; error?: string }> {
+  const paths = cachePaths(account);
+  const cached = () => cachedClaudeQuota(account);
+  const initial = cached();
+  if (hasFreshWindows(initial, now)) return { quota: initial };
+  const release = lockCache(paths, now);
+  if (!release) return { quota: cached() };
+  try {
+    const current = readCache(paths);
+    const quota = cached();
+    if (hasFreshWindows(quota, now)) return { quota };
+    if ((current.nextPollAt ?? 0) > now) return { quota, error: current.error };
+
+    // Reserve before I/O: even a crash or failed final write must not trigger a retry storm.
+    if (!saveCache(paths, { ...current, quota, nextPollAt: now + QUOTA_BACKOFF_MS })) {
+      return { quota, error: "Could not persist usage cooldown" };
+    }
+    let error: string;
+    let retryAfter = 0;
+    try {
+      const response = await fetch("https://api.anthropic.com/api/oauth/usage", {
+        headers: { Authorization: `Bearer ${account.access}`, "anthropic-beta": "oauth-2025-04-20", Accept: "application/json" },
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (response.ok) {
+        const fresh = parseQuota(await response.json(), now);
+        if (fresh.five_hour || fresh.seven_day) {
+          saveCache(paths, { quota: fresh, nextPollAt: now + QUOTA_FRESH_MS, failures: 0 });
+          return { quota: fresh };
+        }
+        error = "Usage windows unavailable";
+      } else {
+        error = `HTTP ${response.status}`;
+        const hint = response.headers.get("retry-after");
+        if (hint) retryAfter = /^\s*\d+(\.\d+)?\s*$/.test(hint) ? Number(hint) * 1000 : Date.parse(hint) - now;
+      }
+    } catch {
+      error = "Usage request failed"; // Never echo tokens or raw provider bodies.
+    }
+    const failures = Math.min((current.failures ?? 0) + 1, 8);
+    const backoff = Math.min(MAX_BACKOFF_MS, QUOTA_BACKOFF_MS * 2 ** (failures - 1));
+    const wait = Math.max(backoff, Number.isFinite(retryAfter) ? retryAfter : 0);
+    saveCache(paths, { quota, failures, error, nextPollAt: now + wait });
+    return { quota, error };
+  } finally { release(); }
+}

package/src/core/env.ts

@@ -15,7 +15,6 @@ export type EnvKey =
   | "AGENT_BOARD_NAME"
   | "AGENT_BOARD_MODE"
   | "AGENT_BOARD_SSH"
-  | "PI_CLAUDE_REMOTE"
   | "PI_CLAUDE_REMOTE_ALLOW_INBOUND"
   | "CLAUDE_TRUSTED_DEVICE_TOKEN";
 
@@ -26,7 +25,6 @@ export const ENV_KEYS: { key: EnvKey; label: string; secret: boolean }[] = [
   { key: "AGENT_BOARD_NAME", label: "Agent board display name", secret: false },
   { key: "AGENT_BOARD_MODE", label: "Agent board deployment (local|remote|external)", secret: false },
   { key: "AGENT_BOARD_SSH", label: "Agent board SSH host, when remote", secret: false },
-  { key: "PI_CLAUDE_REMOTE", label: "Claude Remote auto-start (1|0)", secret: false },
   { key: "PI_CLAUDE_REMOTE_ALLOW_INBOUND", label: "Claude Remote input (1|0)", secret: false },
   { key: "CLAUDE_TRUSTED_DEVICE_TOKEN", label: "Claude trusted-device token (optional)", secret: true },
 ];

package/src/core/file-lease.ts

@@ -0,0 +1,32 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** Non-blocking cross-process lease. Never delete a live or partially written lock. */
+export function acquireFileLease(path: string, ttlMs: number, now = Date.now()): { release(): void } | undefined {
+  mkdirSync(dirname(path), { recursive: true });
+  const owner = randomUUID();
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = openSync(path, "wx", 0o600);
+      try { writeFileSync(fd, JSON.stringify({ owner, expiresAt: now + ttlMs }), "utf8"); }
+      finally { closeSync(fd); }
+      return { release() {
+        try {
+          if (JSON.parse(readFileSync(path, "utf8")).owner === owner) rmSync(path, { force: true });
+        } catch { /* already removed */ }
+      } };
+    } catch (error: any) {
+      if (error?.code !== "EEXIST") throw error;
+      try {
+        let expiresAt: number;
+        try { expiresAt = Number(JSON.parse(readFileSync(path, "utf8")).expiresAt); }
+        catch { expiresAt = NaN; }
+        if (!Number.isFinite(expiresAt)) expiresAt = statSync(path).mtimeMs + ttlMs;
+        if (expiresAt > now) return undefined;
+        rmSync(path, { force: true });
+      } catch { return undefined; }
+    }
+  }
+  return undefined;
+}

package/src/core/gemini/client.ts

@@ -57,7 +57,14 @@ function timeoutSignal(signal?: AbortSignal): AbortSignal {
 }
 
 /** POSTs to one endpoint; undefined for any non-2xx or transport failure. */
-async function postJson(endpoint: string, path: string, token: string, body: unknown, signal?: AbortSignal): Promise<unknown> {
+async function postJson(
+  endpoint: string,
+  path: string,
+  token: string,
+  body: unknown,
+  signal?: AbortSignal,
+  onFailure?: (status: number, body: unknown) => void,
+): Promise<unknown> {
   try {
     const response = await fetch(`${endpoint}/v1internal:${path}`, {
       method: "POST",
@@ -65,7 +72,10 @@ async function postJson(endpoint: string, path: string, token: string, body: unk
       body: JSON.stringify(body),
       signal: timeoutSignal(signal),
     });
-    if (!response.ok) return undefined;
+    if (!response.ok) {
+      if (onFailure) onFailure(response.status, await response.json().catch(() => undefined));
+      return undefined;
+    }
     return await response.json();
   } catch (error) {
     // A caller abort is a decision, not an endpoint failure to route around.
@@ -154,6 +164,28 @@ export async function fetchUserEmail(token: string, signal?: AbortSignal): Promi
   }
 }
 
+/** Only Google's observed verification destination may be opened during login. */
+function verificationUrl(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  try {
+    const url = new URL(value);
+    if (url.protocol === "https:" && url.hostname === "accounts.google.com"
+      && !url.port && !url.username && !url.password && url.pathname === "/signin/continue") return url.href;
+  } catch { /* An invalid link must never reach the browser. */ }
+  return undefined;
+}
+
+export class GeminiVerificationRequiredError extends Error {
+  readonly verificationUrl?: string;
+
+  constructor(url?: unknown) {
+    super("Google account verification required. Sign in to Antigravity with this account to continue.");
+    this.name = "GeminiVerificationRequiredError";
+    // The challenge URL is for the interactive auth UI, not serialized errors.
+    Object.defineProperty(this, "verificationUrl", { value: verificationUrl(url), enumerable: false });
+  }
+}
+
 /** One `retrieveUserQuota` bucket: a runtime model's remaining share of its window. */
 export interface QuotaBucket {
   modelId: string;
@@ -173,8 +205,22 @@ export async function fetchUserQuota(
   projectId: string,
   signal?: AbortSignal,
 ): Promise<QuotaBucket[]> {
+  let lastStatus: number | undefined;
+  let verificationRequired: GeminiVerificationRequiredError | undefined;
+  const onFailure = (status: number, body: unknown) => {
+    lastStatus = status;
+    const error = isRecord(body) && isRecord(body.error) ? body.error : undefined;
+    if (status !== 403 || !error) return;
+    const detail = Array.isArray(error.details) ? error.details.find((item) => isRecord(item)
+      && item["@type"] === "type.googleapis.com/google.rpc.ErrorInfo"
+      && item.domain === "cloudcode-pa.googleapis.com" && item.reason === "VALIDATION_REQUIRED") : undefined;
+    if (detail || (typeof error.message === "string" && /verify your account/i.test(error.message))) {
+      const candidate = new GeminiVerificationRequiredError(detail?.metadata?.validation_url);
+      if (!verificationRequired?.verificationUrl) verificationRequired = candidate;
+    }
+  };
   for (const endpoint of GEMINI_ENDPOINTS) {
-    const answer = await postJson(endpoint, "retrieveUserQuota", token, { project: projectId }, signal);
+    const answer = await postJson(endpoint, "retrieveUserQuota", token, { project: projectId }, signal, onFailure);
     if (!isRecord(answer)) continue;
     const buckets = Array.isArray(answer.buckets) ? answer.buckets : [];
     return buckets.flatMap((bucket): QuotaBucket[] => {
@@ -190,7 +236,8 @@ export async function fetchUserQuota(
       }];
     });
   }
-  throw new Error("Gemini did not return quota from any endpoint.");
+  if (verificationRequired) throw verificationRequired;
+  throw new Error(`Gemini did not return quota from any endpoint${lastStatus ? ` (HTTP ${lastStatus})` : ""}.`);
 }
 
 /** One entry of `fetchAvailableModels`, keyed by its runtime model id. */