From ae5a1b332332f2339f09fa65a341f43f6f8b6936 Mon Sep 17 00:00:00 2001
From: cubebox <58514883+juzijia@users.noreply.github.com>
Date: Fri, 9 Oct 2026 20:05:27 +0800
Subject: [PATCH 1/2] feat(antigravity): expose membership plan in account UI

---
 .../provider-workspace/ProviderAuthPanel.tsx  |   5 +-
 .../components/provider-workspace/types.ts    |   1 +
 gui/src/hooks/useProviderAccountPools.ts      |   1 +
 .../styles/provider-workspace-settings.css    |   1 +
 .../provider-quota-refresh-controls.test.tsx  |  40 ++++++
 src/oauth/google-antigravity.ts               |  63 ++++++++--
 src/oauth/index.ts                            |  27 +++--
 src/oauth/store.ts                            |  16 ++-
 src/oauth/types.ts                            |   6 +
 .../google/google-antigravity-oauth.test.ts   | 114 +++++++++++++++++-
 tests/oauth/oauth-reauth-bind.test.ts         |  32 +++++
 11 files changed, 279 insertions(+), 27 deletions(-)

diff --git a/gui/src/components/provider-workspace/ProviderAuthPanel.tsx b/gui/src/components/provider-workspace/ProviderAuthPanel.tsx
index da5419c975c..f6a50d77f7a 100644
--- a/gui/src/components/provider-workspace/ProviderAuthPanel.tsx
+++ b/gui/src/components/provider-workspace/ProviderAuthPanel.tsx
@@ -553,6 +553,7 @@ export default function ProviderAuthPanel({
               <ul className="pwi-auth-list">
                 {accounts.map(account => {
                   const label = oauthAccountDisplayLabel(accounts, account, t);
+                  const planLabel = account.plan;
                   const switching = switchingAccountId === account.id;
                   const pausing = pausingAccountId === account.id;
                   const healthStatus = account.health?.status;
@@ -567,11 +568,11 @@ export default function ProviderAuthPanel({
                     <button type="button" className="pwi-auth-row-main"
                       onClick={() => { if (!account.active && !account.paused && !showReauth && !inCooldown && !switchingAccountId && !pausingAccountId) void authHandlers.onSwitchAccount(item.name, account); }}
                       aria-current={account.active ? "true" : undefined}
-                      aria-label={`${label}${account.active ? ` — ${t("pws.accountCurrent")}` : ""}`}
+                      aria-label={`${label}${planLabel ? ` — ${planLabel}` : ""}${account.active ? ` — ${t("pws.accountCurrent")}` : ""}`}
                       disabled={Boolean(account.paused || showReauth || inCooldown || switchingAccountId || pausingAccountId)}>
                       <span className={`pwi-auth-dot ${showReauth ? "pwi-auth-dot--warn" : account.active && !account.paused ? "pwi-auth-dot--ok" : "pwi-auth-dot--off"}`} aria-hidden="true" />
                       <span className="pwi-auth-row-copy">
-                        <span className="pwi-auth-row-label">{label}</span>
+                        <span className="pwi-auth-row-heading"><span className="pwi-auth-row-label">{label}</span>{planLabel && <span className="badge badge-green">{planLabel}</span>}</span>
                         <span className="pwi-auth-row-secondary">{[account.email, `${t("prov.accountId")}: ${maskedId}`].filter(Boolean).join(" · ")}</span>
                         {healthSummary && (
                           <span className="pwi-auth-row-secondary faint">{healthSummary}</span>
diff --git a/gui/src/components/provider-workspace/types.ts b/gui/src/components/provider-workspace/types.ts
index 974ea93f219..f83b81aa38f 100644
--- a/gui/src/components/provider-workspace/types.ts
+++ b/gui/src/components/provider-workspace/types.ts
@@ -65,6 +65,7 @@ export type OAuthAccountRow = AccountQuotaReading & {
   autoSwitchThresholdOverride?: number | null;
   autoSwitchThreshold?: number;
   effectiveAutoSwitchThreshold?: number;
+  plan?: string | null;
   health?: { status: OAuthAccountHealthStatus; reason?: string; until?: string };
   healthLabel?: string;
   healthSummary?: string;
diff --git a/gui/src/hooks/useProviderAccountPools.ts b/gui/src/hooks/useProviderAccountPools.ts
index b934bd94f60..49782cb7605 100644
--- a/gui/src/hooks/useProviderAccountPools.ts
+++ b/gui/src/hooks/useProviderAccountPools.ts
@@ -27,6 +27,7 @@ export interface OAuthAccount extends AccountQuotaReading {
   autoSwitchThreshold?: number;
   effectiveAutoSwitchThreshold?: number;
   expiresAt?: number;
+  plan?: string | null;
   health?: { status: "healthy" | "cooldown" | "reauth_required" | "warning"; reason?: string; until?: string };
   healthLabel?: string;
   healthSummary?: string;
diff --git a/gui/src/styles/provider-workspace-settings.css b/gui/src/styles/provider-workspace-settings.css
index f3c7d4b1a90..e52186bc0d4 100644
--- a/gui/src/styles/provider-workspace-settings.css
+++ b/gui/src/styles/provider-workspace-settings.css
@@ -77,6 +77,7 @@
 .pwi-auth-row-main:disabled { cursor: default; opacity: 0.72; }
 .pwi-auth-row-main:focus-visible,
 .pwi-auth-row-remove:focus-visible { outline: 2px solid var(--accent-ring); outline-offset: 2px; }
+.pwi-auth-row-heading { display: flex; align-items: center; gap: 6px; max-width: 100%; min-width: 0; flex-wrap: wrap; }
 .pwi-auth-row-label  { font-size: var(--text-control); color: var(--text); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .pwi-auth-row-remove {
   background: none; border: none; cursor: pointer; padding: 2px;
diff --git a/gui/tests/provider-quota-refresh-controls.test.tsx b/gui/tests/provider-quota-refresh-controls.test.tsx
index 0bab2820572..63312c38411 100644
--- a/gui/tests/provider-quota-refresh-controls.test.tsx
+++ b/gui/tests/provider-quota-refresh-controls.test.tsx
@@ -264,3 +264,43 @@ test("changing active account discards the previous refresh feedback", async ()
   expect(host.textContent).not.toContain("Quota check completed");
   expect(findButton("Refresh quotas")?.disabled).toBe(false);
 });
+
+test("Antigravity plan badge preserves Free and provider names and leaves pause controls intact", async () => {
+  win.localStorage.setItem("ocx-lang", "zh");
+  const item = { ...oauthItem, name: "google-antigravity" };
+  const handlers = authHandlers({ onPauseAccount: () => {} });
+  const row = { id: "ag-1", active: true, paused: false };
+  const view = (plan: string | null, paused = false, pausingAccountId: string | null = null) =>
+    <ProviderAuthPanel item={item} apiBase="" accounts={[{ ...row, plan, paused }]}
+      pausingAccountId={pausingAccountId} authHandlers={handlers} />;
+  const main = () => host.querySelector(".pwi-auth-row-main") as HTMLButtonElement;
+  const badge = () => main().querySelector(".pwi-auth-row-copy .badge");
+
+  await render(view("Free"));
+  expect(badge()?.textContent).toBe("Free");
+  expect(main().getAttribute("aria-label")).toContain("Free");
+  expect(main().getAttribute("aria-label")).toContain("当前");
+
+  await render(view("Google AI Pro"));
+  expect(badge()?.textContent).toBe("Google AI Pro");
+  expect(main().getAttribute("aria-label")).toContain("Google AI Pro");
+
+  await render(view("Google AI Ultra", true));
+  expect(badge()?.textContent).toBe("Google AI Ultra");
+  expect(main().disabled).toBe(true);
+  expect(findButton("恢复")).not.toBeNull();
+
+  await render(view("Google AI Pro", false, row.id));
+  expect(badge()?.textContent).toBe("Google AI Pro");
+  expect(main().disabled).toBe(true);
+  const pause = findButton("暂停");
+  expect(pause?.disabled).toBe(true);
+  expect(pause?.getAttribute("aria-busy")).toBe("true");
+
+  await render(view(null));
+  expect(badge()).toBeNull();
+  expect(main().closest(".pwi-auth-acct")?.textContent).not.toMatch(/null/i);
+  expect(main().getAttribute("aria-label")).not.toMatch(/null/i);
+  expect(main().getAttribute("aria-label")).not.toContain("Google AI");
+  expect(main().getAttribute("aria-label")).not.toContain("Free");
+});
diff --git a/src/oauth/google-antigravity.ts b/src/oauth/google-antigravity.ts
index be81b55de58..f0cd3a1bd73 100644
--- a/src/oauth/google-antigravity.ts
+++ b/src/oauth/google-antigravity.ts
@@ -94,15 +94,43 @@ function extractProjectId(data: Record<string, unknown> | undefined): string | u
   return undefined;
 }
 
-async function loadCodeAssistProject(accessToken: string, signal?: AbortSignal): Promise<string | undefined> {
+/**
+ * Subscription tier reported by a loadCodeAssist `paidTier`: `free-tier` → "Free", an explicit
+ * `Google AI <name>` is carried verbatim, everything else (missing, malformed, unrecognised) is a
+ * truthful null — never a guess from `currentTier`, which is the bare product name even for free.
+ */
+function extractPaidTierPlan(data: Record<string, unknown>): string | null {
+  const paidTier = data.paidTier;
+  if (!paidTier || typeof paidTier !== "object") return null;
+  const tier = paidTier as { id?: unknown; name?: unknown };
+  if (tier.id === "free-tier") return "Free";
+  if (typeof tier.name !== "string" || /[\x00-\x1f\x7f-\x9f]/.test(tier.name)) return null;
+  const name = tier.name.trim();
+  return name.length <= 128 && /^Google AI [^\s\x00-\x1f\x7f-\x9f][^\x00-\x1f\x7f-\x9f]*$/.test(name) ? name : null;
+}
+
+/**
+ * loadCodeAssist discovery for an access token. A plan/project observation is returned only when
+ * the call succeeded and produced a parseable body. A fetch rejection propagates (so project
+ * discovery does not onboard); non-2xx and JSON parse failure yield no observation.
+ */
+async function loadCodeAssistDiscovery(accessToken: string, signal?: AbortSignal): Promise<{ projectId?: string; plan?: string | null }> {
   const response = await fetch(`${PROD_API}/${API_VERSION}:loadCodeAssist`, {
     method: "POST",
     headers: { Authorization: `Bearer ${accessToken}`, Accept: "*/*", "Content-Type": "application/json", "User-Agent": antigravityUserAgent() },
     body: JSON.stringify({ metadata: { ideType: "ANTIGRAVITY" } }),
     signal: requestSignal(signal),
   });
-  if (!response.ok) return undefined;
-  return extractProjectId((await response.json().catch(() => undefined)) as Record<string, unknown> | undefined);
+  if (!response.ok) return {};
+  let data: unknown;
+  try {
+    data = await response.json();
+  } catch {
+    return {};
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data)) return { plan: null };
+  const projectId = extractProjectId(data as Record<string, unknown>);
+  return { ...(projectId ? { projectId } : {}), plan: extractPaidTierPlan(data as Record<string, unknown>) };
 }
 
 async function onboardProject(accessToken: string, signal?: AbortSignal): Promise<string | undefined> {
@@ -136,9 +164,23 @@ async function onboardProject(accessToken: string, signal?: AbortSignal): Promis
   return undefined;
 }
 
+/**
+ * Discover the CCA project and reported subscription tier for an access token
+ * (loadCodeAssist → onboardUser fallback). The tier observation comes only from a successful,
+ * parseable loadCodeAssist response; onboarding itself adds no tier observation.
+ * Onboarding is attempted only when loadCodeAssist yielded no project, and its failure never
+ * discards a tier observation loadCodeAssist already made.
+ */
+export async function discoverAntigravityAccount(accessToken: string, signal?: AbortSignal): Promise<{ projectId?: string; plan?: string | null }> {
+  const discovery = await loadCodeAssistDiscovery(accessToken, signal);
+  if (discovery.projectId) return discovery;
+  const onboarded = await onboardProject(accessToken, signal).catch(() => undefined);
+  return { ...discovery, ...(onboarded ? { projectId: onboarded } : {}) };
+}
+
 /** Discover the CCA project for an access token (loadCodeAssist → onboardUser fallback). */
 export async function discoverAntigravityProject(accessToken: string, signal?: AbortSignal): Promise<string | undefined> {
-  return (await loadCodeAssistProject(accessToken, signal)) ?? (await onboardProject(accessToken, signal));
+  return (await discoverAntigravityAccount(accessToken, signal)).projectId;
 }
 
 function credentialsFromPayload(payload: GoogleTokenPayload, refreshFallback = ""): OAuthCredentials {
@@ -207,13 +249,13 @@ class AntigravityOAuthFlow extends OAuthCallbackFlow {
     }, this.ctrl.signal);
     const creds = credentialsFromPayload(payload);
     this.ctrl.onProgress?.("Discovering Cloud Code Assist project");
-    const projectId = await discoverAntigravityProject(creds.access, this.ctrl.signal);
-    if (!projectId) {
+    const discovery = await discoverAntigravityAccount(creds.access, this.ctrl.signal);
+    if (!discovery.projectId) {
       // Fail the login rather than persisting a credential that every request would reject for a
       // missing CCA project — otherwise status shows "logged in" while all calls fail closed.
       throw new Error("Antigravity login could not discover a Cloud Code Assist project for this account. Ensure the account has Antigravity/Cloud Code Assist access and try again.");
     }
-    return { ...creds, projectId };
+    return { ...creds, ...discovery };
   }
 }
 
@@ -230,9 +272,10 @@ export async function refreshAntigravityToken(refreshToken: string, signal?: Abo
     refresh_token: refreshToken,
   }, signal);
   const creds = credentialsFromPayload(payload, refreshToken);
-  // Re-discover the project on refresh so a newly-onboarded account fills in projectId.
-  const projectId = await discoverAntigravityProject(creds.access, signal).catch(() => undefined);
-  return projectId ? { ...creds, projectId } : creds;
+  // Re-discover on refresh so a newly-onboarded account fills in projectId and a reported tier is
+  // refreshed. A fetch rejection must not fail token refresh or clear a previous plan.
+  const discovery = await discoverAntigravityAccount(creds.access, signal).catch(() => ({}));
+  return { ...creds, ...discovery };
 }
 
 /**
diff --git a/src/oauth/index.ts b/src/oauth/index.ts
index e893a09af4b..88832298103 100644
--- a/src/oauth/index.ts
+++ b/src/oauth/index.ts
@@ -755,6 +755,7 @@ function merged(fresh: OAuthCredentials, previous: OAuthCredentials): OAuthCrede
     source: fresh.source === "local-cli" ? "local-cli"
       : previous.source === "local-cli" ? "oauth" : fresh.source ?? previous.source ?? "oauth",
     ...(fresh.projectId === undefined && previous.projectId ? { projectId: previous.projectId } : {}),
+    ...(fresh.plan === undefined && previous.plan !== undefined ? { plan: previous.plan } : {}),
     ...(fresh.apiBaseUrl === undefined && previous.apiBaseUrl ? { apiBaseUrl: previous.apiBaseUrl } : {}),
     ...(fresh.email === undefined && previous.email ? { email: previous.email } : {}),
     ...(fresh.accountId === undefined && previous.accountId ? { accountId: previous.accountId } : {}),
@@ -1728,18 +1729,19 @@ export interface OAuthAccountSummary {
   needsReauthReason?: "verify_account";
   expiresAt?: number;
   /**
-   * Subscription tier, mirroring the field the OpenAI/Codex provider reports, so a consumer
-   * weighting a multi-account pool by seat size needs no per-provider branching (#3777).
+   * Display-only subscription tier, mirroring the field the OpenAI/Codex provider reports.
    *
    * Always present and explicitly `null` when the tier is unknown. The distinction matters:
    * an ABSENT key means the proxy is too old to report a tier at all, while `null` means this
-   * version looked and upstream did not say. Omitting it would make those indistinguishable and
+   * version has no recognized tier to display. Omitting it would make those indistinguishable and
    * invite a consumer to assume a tier.
    *
-   * Every OAuth provider reports `null` today. Anthropic's `/api/oauth/usage` returns quota
-   * buckets only — `five_hour`, `seven_day`, the model-scoped weekly windows and `limits[]` —
-   * and carries no subscription/tier field, and its token response carries none either. See
-   * `fetchAnthropicUsageQuota` in `src/providers/quota.ts`.
+   * Google Antigravity can report a plan from a loadCodeAssist `paidTier` (see
+   * `extractPaidTierPlan` in `src/oauth/google-antigravity.ts`); every other provider reports
+   * `null`. Anthropic's `/api/oauth/usage` returns quota buckets only — `five_hour`, `seven_day`,
+   * the model-scoped weekly windows and `limits[]` — and carries no subscription/tier field, and
+   * its token response carries none either. See `fetchAnthropicUsageQuota` in
+   * `src/providers/quota.ts`.
    */
   plan: string | null;
 }
@@ -1764,11 +1766,12 @@ export function getLoginStatus(provider: string, maskEmails = true): { loggedIn:
     ...(accountNeedsReauthForStatus(provider, a) ? { needsReauth: true } : {}),
     ...(a.needsReauth && a.needsReauthReason === "verify_account" ? { needsReauthReason: a.needsReauthReason } : {}),
     expiresAt: a.credential.expires,
-    // Explicitly null rather than omitted — see OAuthAccountSummary.plan. No OAuth provider
-    // exposes a subscription tier today, so there is nothing truthful to put here; deriving one
-    // from quota percentages is not possible, because they are normalized per account and a
-    // half-consumed small seat is indistinguishable from a half-consumed large one.
-    plan: null,
+    // Explicitly null when the credential carries no observed tier — see OAuthAccountSummary.plan.
+    // Only Google Antigravity reports a paidTier today; other providers have nothing truthful to
+    // put here, and deriving one from quota percentages is not possible, because they are
+    // normalized per account and a half-consumed small seat is indistinguishable from a
+    // half-consumed large one.
+    plan: a.credential.plan ?? null,
   }));
 
   // A stored credential counts as "logged in" when it exists and is not marked for
diff --git a/src/oauth/store.ts b/src/oauth/store.ts
index ac750fe0541..2d53a948707 100644
--- a/src/oauth/store.ts
+++ b/src/oauth/store.ts
@@ -539,6 +539,12 @@ function normalizeCredential(cred: unknown): OAuthCredentials | null {
   if (identity) normalized.anthropicIdentity = identity;
   if (isCredentialSource(candidate.source)) normalized.source = candidate.source;
   if (typeof candidate.projectId === "string" && candidate.projectId.length > 0) normalized.projectId = candidate.projectId;
+  if (candidate.plan !== undefined) {
+    if (typeof candidate.plan === "string" && !/[\x00-\x1f\x7f-\x9f]/.test(candidate.plan)) {
+      const plan = candidate.plan.trim();
+      normalized.plan = plan.length > 0 && plan.length <= 128 ? plan : null;
+    } else normalized.plan = null;
+  }
   if (typeof candidate.apiBaseUrl === "string" && candidate.apiBaseUrl.length > 0) {
     // Persist only allowlisted origins; drop anything else so auth.json cannot
     // become an SSRF springboard across reloads. Copilot and Devin are the two
@@ -876,6 +882,12 @@ function registrationPersistGuard(provider: string, assertBeforePersist?: () =>
   };
 }
 
+function retainUnobservedPlan(fresh: OAuthCredentials, previous: OAuthCredentials): OAuthCredentials {
+  return fresh.plan === undefined && previous.plan !== undefined
+    ? { ...fresh, plan: previous.plan }
+    : fresh;
+}
+
 export async function saveCredentialWithReceipt(
   provider: string,
   cred: OAuthCredentials,
@@ -920,7 +932,7 @@ export async function saveCredentialWithReceipt(
     } else if (identity) {
       const existing = set.accounts.find(a => (a.credential.accountId ?? a.credential.email) === identity);
       if (existing) {
-        existing.credential = safe;
+        existing.credential = retainUnobservedPlan(safe, existing.credential);
         delete existing.needsReauth;
         delete existing.needsReauthReason;
         delete existing.refreshAttentionGeneration;
@@ -1213,7 +1225,7 @@ export async function saveAccountCredential(
     const set = store[provider];
     const account = set?.accounts.find(a => a.id === accountId);
     if (!set || !account) return;
-    account.credential = safe;
+    account.credential = retainUnobservedPlan(safe, account.credential);
     if (opts.rotateLoginId) account.loginId = randomUUID();
     delete account.needsReauth;
     delete account.needsReauthReason;
diff --git a/src/oauth/types.ts b/src/oauth/types.ts
index 9f9f06852d4..7371c06914d 100644
--- a/src/oauth/types.ts
+++ b/src/oauth/types.ts
@@ -66,6 +66,12 @@ export type OAuthCredentials = {
   anthropicIdentity?: { v: 1; accountUuid: string; bearerSha256: string };
   /** Google Antigravity (Cloud Code Assist) discovered project id; injected into the CCA envelope. */
   projectId?: string;
+  /**
+   * Google Antigravity subscription tier from loadCodeAssist `paidTier`; display-only, never used
+   * for routing or selection. Absent = no observation this round (retain previous); `null` = an
+   * observed "no recognized plan"; a string = the tier to show.
+   */
+  plan?: string | null;
   /**
    * GitHub Copilot allowlisted API origin from token `endpoints.api` (HTTPS `*.githubcopilot.com` only).
    * Never reuse for Antigravity projectId; validated on write and again at request time.
diff --git a/tests/adapters/google/google-antigravity-oauth.test.ts b/tests/adapters/google/google-antigravity-oauth.test.ts
index 68cf6f49e6a..9d19dcaf6bc 100644
--- a/tests/adapters/google/google-antigravity-oauth.test.ts
+++ b/tests/adapters/google/google-antigravity-oauth.test.ts
@@ -3,7 +3,8 @@ import { discoverAntigravityProject, refreshAntigravityToken } from "../../../sr
 import { mkdirSync} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { getCredential, saveCredential } from "../../../src/oauth/store";
+import { getAccountCredential, getAccountSet, getCredential, saveCredential } from "../../../src/oauth/store";
+import { getValidAccessTokenForAccount, getLoginStatus } from "../../../src/oauth";
 import { ANTIGRAVITY_IDE_VERSION } from "../../../src/adapters/client-fingerprint";
 import { removeTreeWithRetry } from "../../helpers/remove-tree";
 
@@ -37,6 +38,21 @@ describe("antigravity project discovery", () => {
     expect(await discoverAntigravityProject("tok")).toBe("proj-nested");
   });
 
+  test.each(["network", "non-2xx", "invalid JSON"] as const)("loadCodeAssist %s follows base onboarding behavior", async mode => {
+    const { calls } = routeFetch(url => {
+      if (url.includes(":loadCodeAssist")) {
+        if (mode === "network") throw new Error("offline");
+        if (mode === "non-2xx") return new Response("unavailable", { status: 503 });
+        return new Response("not json");
+      }
+      if (url.includes(":onboardUser")) return Response.json({ done: true, response: { cloudaicompanionProject: "proj-onboarded" } });
+      throw new Error(`Unexpected request: ${url}`);
+    });
+    if (mode === "network") await expect(discoverAntigravityProject("tok")).rejects.toThrow("offline");
+    else await expect(discoverAntigravityProject("tok")).resolves.toBe("proj-onboarded");
+    expect(calls.filter(url => url.includes(":onboardUser"))).toHaveLength(mode === "network" ? 0 : 1);
+  });
+
   test("falls back to onboardUser poll loop (not-done then done)", async () => {
     let onboardCalls = 0;
     routeFetch((url, init) => {
@@ -133,6 +149,27 @@ describe("antigravity refresh", () => {
     expect(cred.expires - issuedAt).toBe(55 * 60 * 1000);
   });
 
+  test.each([
+    [{ id: "free-tier", name: "Free" }, "Free"],
+    [{ id: "paid-pro", name: "Google AI Pro" }, "Google AI Pro"],
+    [{ id: "paid-pro", name: " Google AI Pro " }, "Google AI Pro"],
+    [{ id: "fixture-ultra", name: "Google AI Ultra" }, "Google AI Ultra"],
+    [{ id: "paid", name: `Google AI ${"x".repeat(118)}` }, `Google AI ${"x".repeat(118)}`],
+    [{ id: "paid", name: `Google AI ${"x".repeat(119)}` }, null],
+    [{ id: "paid", name: "Google AI Pro\n" }, null],
+    [{ id: "paid", name: "Google AI Pro\u0085" }, null],
+    [{ id: "paid", name: 42 }, null],
+    [{ id: "unknown-product", name: "Other Product" }, null],
+    [undefined, null],
+  ] as const)("observes loadCodeAssist paidTier %p as %p", async (paidTier, expected) => {
+    routeFetch(url => {
+      if (url.includes("oauth2.googleapis.com/token")) return Response.json({ access_token: "fresh", expires_in: 3600 });
+      if (url.includes(":loadCodeAssist")) return Response.json({ cloudaicompanionProject: "proj", paidTier });
+      throw new Error(`Unexpected request: ${url}`);
+    });
+    expect((await refreshAntigravityToken("rt")).plan).toBe(expected);
+  });
+
   test("refresh failure carries status only, not the response body", async () => {
     routeFetch((url) => {
       if (url.includes("oauth2.googleapis.com/token")) return new Response("invalid_grant secret-detail", { status: 400 });
@@ -157,6 +194,81 @@ describe("antigravity credential persistence (projectId survives the store)", ()
     if (tmp) removeTreeWithRetry(tmp);
   });
 
+  test.each([
+    ["request failure", "throw", "Google AI Pro"],
+    ["non-2xx", "status", "Google AI Pro"],
+    ["unparseable body", "invalid", "Google AI Pro"],
+    ["unknown product", "unknown", null],
+    ["oversized name", "oversized", null],
+    ["missing tier", "missing", null],
+    ["observed null then onboarding throws", "null-onboard", null],
+    ["observed Pro then onboarding throws", "pro-onboard", "Google AI Pro"],
+  ] as const)("refresh preserves or replaces the observed plan: %s", async (_label, mode, expected) => {
+    tmp = join(tmpdir(), `ag-plan-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+    mkdirSync(tmp, { recursive: true });
+    process.env.HOME = tmp;
+    process.env.OPENCODEX_HOME = join(tmp, "ocx");
+    await saveCredential("google-antigravity", {
+      access: "old", refresh: "rt", expires: Date.now() - 1000,
+      projectId: "proj-old", plan: mode === "pro-onboard" ? "Free" : "Google AI Pro",
+    });
+    const id = getAccountSet("google-antigravity")!.activeAccountId;
+    const { calls } = routeFetch(url => {
+      if (url.includes("oauth2.googleapis.com/token")) return Response.json({ access_token: "fresh", expires_in: 3600 });
+      if (url.includes(":loadCodeAssist")) {
+        if (mode === "throw") throw new Error("offline");
+        if (mode === "status") return new Response("failure", { status: 503 });
+        if (mode === "invalid") return new Response("not json");
+        const paidTier = mode === "unknown" || mode === "null-onboard"
+          ? { id: "other", name: "Other Product" }
+          : mode === "oversized" ? { id: "paid", name: `Google AI ${"x".repeat(119)}` }
+          : mode === "pro-onboard" ? { id: "pro", name: "Google AI Pro" } : undefined;
+        return Response.json({ ...(["unknown", "oversized", "missing"].includes(mode) ? { cloudaicompanionProject: "proj-new" } : {}), paidTier });
+      }
+      if (url.includes(":onboardUser")) {
+        if (mode.endsWith("-onboard")) throw new Error("onboarding unavailable");
+        return new Response("forbidden", { status: 403 });
+      }
+      throw new Error(`Unexpected request: ${url}`);
+    });
+    expect(await getValidAccessTokenForAccount("google-antigravity", id)).toBe("fresh");
+    if (mode === "throw") expect(calls.some(url => url.includes(":onboardUser"))).toBe(false);
+    if (mode.endsWith("-onboard")) expect(calls.filter(url => url.includes(":onboardUser"))).toHaveLength(1);
+    expect(getAccountCredential("google-antigravity", id)?.plan).toBe(expected);
+    expect(getLoginStatus("google-antigravity").accounts?.[0]?.plan).toBe(expected);
+  });
+
+  test("plan normalization persists null, trims bounded names, rejects controls and accepts legacy records", async () => {
+    tmp = join(tmpdir(), `ag-store-plan-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+    mkdirSync(tmp, { recursive: true });
+    process.env.HOME = tmp;
+    process.env.OPENCODEX_HOME = join(tmp, "ocx");
+    const base = { access: "a", refresh: "r", expires: Date.now() + 3_600_000, email: "ag@example.test" };
+    await saveCredential("google-antigravity", base);
+    expect(getCredential("google-antigravity")?.plan).toBeUndefined();
+    expect(Object.hasOwn(getCredential("google-antigravity")!, "plan")).toBe(false);
+    for (const [input, expected] of [
+      [null, null],
+      ["  Google AI Pro  ", "Google AI Pro"],
+      [`Google AI ${"x".repeat(118)}`, `Google AI ${"x".repeat(118)}`],
+      ["bad\nplan", null],
+      ["\tGoogle AI Pro", null],
+      ["Google AI Pro\n", null],
+      ["Google AI Pro\x7f", null],
+      ["Google AI Pro\u0085", null],
+      ["x".repeat(129), null],
+      ["   ", null],
+      [42, null],
+    ] as const) {
+      await saveCredential("google-antigravity", { ...base, plan: input as string | null });
+      expect(getCredential("google-antigravity")?.plan).toBe(expected);
+      expect(Object.hasOwn(getCredential("google-antigravity")!, "plan")).toBe(true);
+    }
+    await saveCredential("google-antigravity", base);
+    expect(getCredential("google-antigravity")?.plan).toBeNull();
+    expect(Object.hasOwn(getCredential("google-antigravity")!, "plan")).toBe(true);
+  });
+
   test("saveCredential + getCredential round-trips projectId (regression: was stripped by normalizeCredential)", async () => {
     tmp = join(tmpdir(), `ag-store-${Date.now()}-${Math.random().toString(16).slice(2)}`);
     mkdirSync(tmp, { recursive: true });
diff --git a/tests/oauth/oauth-reauth-bind.test.ts b/tests/oauth/oauth-reauth-bind.test.ts
index 0dca8a8891a..539142322f2 100644
--- a/tests/oauth/oauth-reauth-bind.test.ts
+++ b/tests/oauth/oauth-reauth-bind.test.ts
@@ -124,6 +124,38 @@ describe("OAuth account-scoped reauth", () => {
     expect(getAccountSet("xai")?.accounts[0]?.loginId).not.toBe(loginId);
   });
 
+  test.each([
+    ["reauth without observation", "reauth", "Google AI Pro", undefined, "Google AI Pro"],
+    ["reauth without observation after null", "reauth", null, undefined, null],
+    ["reauth with explicit null", "reauth", "Google AI Pro", null, null],
+    ["reauth with fresh Pro", "reauth", "Free", "Google AI Pro", "Google AI Pro"],
+    ["same-identity upsert without observation", "upsert", "Google AI Pro", undefined, "Google AI Pro"],
+    ["same-identity upsert with explicit null", "upsert", "Google AI Pro", null, null],
+    ["same-identity upsert with fresh Pro", "upsert", null, "Google AI Pro", "Google AI Pro"],
+  ] as const)("Antigravity %s preserves only unobserved plan", async (_case, mode, previous, incoming, expected) => {
+    await saveCredential("google-antigravity", {
+      access: "old-access", refresh: "old-refresh", expires: Date.now() + 60_000,
+      email: "ag@example.test", accountId: "ag-account", projectId: "old-project", plan: previous,
+    });
+    const slotId = getAccountSet("google-antigravity")!.activeAccountId;
+    const provider = OAUTH_PROVIDERS["google-antigravity"]!;
+    const original = provider.login;
+    provider.login = async () => ({
+      access: "new-access", refresh: "new-refresh", expires: Date.now() + 60_000,
+      email: "ag@example.test", accountId: "ag-account", projectId: "new-project",
+      ...(incoming !== undefined ? { plan: incoming } : {}),
+    });
+    try {
+      await runLogin("google-antigravity", {} as OAuthController, mode === "reauth" ? { reauthAccountId: slotId } : undefined);
+    } finally {
+      provider.login = original;
+    }
+    expect(getAccountSet("google-antigravity")?.accounts).toHaveLength(1);
+    expect(getAccountCredential("google-antigravity", slotId)).toMatchObject({
+      access: "new-access", refresh: "new-refresh", projectId: "new-project", plan: expected,
+    });
+  });
+
   test("kiro-cli reauth refuses a native-origin slot before any CLI work", async () => {
     const cred: OAuthCredentials = { access: "native-access", refresh: "native-refresh", expires: Date.now() + 60_000 };
     await appendKiroAccountFromDeviceLogin(cred);

From 9b6e14d359cebb1c3fdd016bcc11384c9b2b45bc Mon Sep 17 00:00:00 2001
From: cubebox <58514883+juzijia@users.noreply.github.com>
Date: Fri, 9 Oct 2026 21:35:20 +0800
Subject: [PATCH 2/2] docs(antigravity): document membership plan contract

---
 structure/gui-and-management-api.md | 2 +-
 structure/providers-and-adapters.md | 2 +-
 structure/runtime.md                | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/structure/gui-and-management-api.md b/structure/gui-and-management-api.md
index 46690e75ad2..e0ddacb6de4 100644
--- a/structure/gui-and-management-api.md
+++ b/structure/gui-and-management-api.md
@@ -277,7 +277,7 @@ per-request first-party callback reads that live object; a failed write leaves i
 | Updates | `GET /api/update/check`, `POST /api/update/run`, and `GET /api/update/status` own dashboard self-update state. A launched worker PID is persisted in `update-job.json`; dead PIDs recover immediately, while legacy active records without a PID recover only after ten minutes. Live PIDs remain exclusive regardless of record age. `GET /api/update/check` and `POST /api/update/run` await one per-channel asynchronous registry lookup and write successful results through to the package cache; run passes that result to the job starter. `GET /api/update/badge` only reads the cache and reports unknown after 40 hours, on missing cache, or on channel mismatch. The badge links to the update surface rather than gating other actions. `GET /api/update/badge?surface=desktop&session=<id>` projects only that process-local Tauri session; missing or expired state is unknown and never falls back to the package cache. `POST /api/update/desktop-snapshot` is a 1 KiB bounded display-state mutation with no install permission. It accepts the existing admin-token principal or a dedicated single-use, ten-second snapshot capability bound to nonce, method, path, PID, port and the SHA-256 digest of the exact body bytes; that capability cannot authorize another route. |
 | Providers | Create/update/delete ordinary provider configs and enrich registry metadata. A `POST /api/providers` overwrite of an existing name keeps the eight operator compatibility settings (`PROVIDER_COMPAT_CARRY_FIELDS` in `src/server/management/provider-overwrite-carry.ts`) and the stored key pool only while the destination (adapter, normalized base URL, auth mode when named) is unchanged. It keeps omitted `hideRawReasoning` on every overwrite of the same name, including destination moves, because it is a display policy; a submitted boolean wins. It never merges the rest of the old row. `PATCH` is a field mask and keeps every field it does not name; `hideRawReasoning` accepts a boolean or `null` to clear it. The reserved `openai` card exposes Pool(default)/Direct account mode; `openai-apikey` remains the separate API route. |
 | Models | Fetch routed model lists, disabled model visibility, and catalog-facing ids. New non-OAuth registration holds exposure until authoritative discovery; 20 or more distinct switch rows start OFF without disabling the provider. Pending rows cannot accept visibility changes. Ordinary model reads also apply the [new-arrival catalog contract](catalog.md#shared-catalog) before returning models. With a matching persisted configuration, discovery records the baseline, NEW badges, and automatic disables together; HTTP listing does not wait for a separate Codex sync. Inventory already drifted from disk uses a detached policy projection: arrivals remain disabled in management rows without changing live config or disk. |
-| OAuth | Login/status/logout for OAuth-backed providers, plus multiauth account management: `GET /api/oauth/accounts`, `PUT /api/oauth/accounts/active`, `PUT /api/oauth/accounts/alias`, `PUT /api/oauth/accounts/pause`, and `DELETE /api/oauth/accounts` list masked accounts per provider, switch the active one, edit its display-only alias, pause/resume a generic OAuth account, and remove one. Paused generic OAuth accounts are excluded from request selection, 429 failover, and proactive token refresh; pausing an active account selects the next usable account when available, and resuming an account restores an active selection if the current one remains paused. With no unpaused account, requests return 403 rather than a login error. Kiro account-list rows include the current automatic-selection projection and closed exclusion reason; an active singleton may still send. The login flow itself is `GET /api/oauth/providers`, `POST /api/oauth/login`, `POST /api/oauth/login/code`, `POST /api/oauth/login/cancel`, `POST /api/oauth/logout`, and `GET /api/oauth/status`; pool controls are `GET/PUT/PATCH /api/oauth/accounts/pool` and `POST /api/oauth/accounts/clear-cooldown`. Login accepts `addAccount: true` to force a fresh browser identity. Meta Muse login start and manual-code continuation require the server-resolved `gui-session` principal before credential acquisition or code submission (including reauth); see the [provider contract](providers-and-adapters.md). Device flows return a structured `deviceCode`; the GUI highlights and copies it before the user opens the verification page. |
+| OAuth | Login/status/logout for OAuth-backed providers, plus multiauth account management: `GET /api/oauth/accounts`, `PUT /api/oauth/accounts/active`, `PUT /api/oauth/accounts/alias`, `PUT /api/oauth/accounts/pause`, and `DELETE /api/oauth/accounts` list masked accounts per provider, switch the active one, edit its display-only alias, pause/resume a generic OAuth account, and remove one. Paused generic OAuth accounts are excluded from request selection, 429 failover, and proactive token refresh; pausing an active account selects the next usable account when available, and resuming an account restores an active selection if the current one remains paused. With no unpaused account, requests return 403 rather than a login error. Kiro account-list rows include the current automatic-selection projection and closed exclusion reason; an active singleton may still send. The login flow itself is `GET /api/oauth/providers`, `POST /api/oauth/login`, `POST /api/oauth/login/code`, `POST /api/oauth/login/cancel`, `POST /api/oauth/logout`, and `GET /api/oauth/status`; pool controls are `GET/PUT/PATCH /api/oauth/accounts/pool` and `POST /api/oauth/accounts/clear-cooldown`. Login accepts `addAccount: true` to force a fresh browser identity. Meta Muse login start and manual-code continuation require the server-resolved `gui-session` principal before credential acquisition or code submission (including reauth); see the [provider contract](providers-and-adapters.md). Device flows return a structured `deviceCode`; the GUI highlights and copies it before the user opens the verification page. `getLoginStatus` in `src/oauth/index.ts` always includes `plan` in each account summary as a string or explicit `null` (`credential.plan ?? null`), projecting the [stored observation contract](runtime.md#entrypoints). `gui/src/components/provider-workspace/ProviderAuthPanel.tsx` renders a present plan as a green badge and includes it in the account button's `aria-label`; missing or `null` plans render neither a badge nor a plan suffix. `Free` is literal in every locale, including Chinese, and provider names are not translated. The badge does not change pause, resume or account-switch guards. |
 | Key providers | `GET /api/key-providers` exposes API-key provider presets for setup and dashboard flows, and `GET/POST/DELETE /api/keys` owns the proxy's own admission keys. Machine links live in `src/server/management/link-routes.ts`: dashboard sessions reach `GET /api/link/candidates`, `POST /api/link/probe`, `POST /api/link/confirm-host` and `POST /api/link/apply`, meaning a paired session or, on a standalone runtime, the current loopback-issued session on trusted loopback ingress; `POST /api/link/join` instead requires an operator-paired session because it durably redirects local client traffic, and also refuses a runtime that is not standalone (`409 standalone_required`) or not listening on its configured port (`409 join_port_mismatch`) before any SSH, then restarts this runtime as a client; `GET /api/link/status` reports `joinAvailable` and typed `joinDenied` causes only to GUI-session callers, distinguishing pairing, runtime-role and port refusals without changing the admin/CLI DTO, so the dashboard enables the Child role only when the join gates pass; `GET /api/link/status` and `DELETE /api/link/{id}` also accept the admin token on a trusted loopback ingress; `POST /api/link/issue` accepts only that admin token. Tailscale-identity sessions are refused on every link route. See [Remote Link](remote-link.md). Multi-key pool per key-auth provider: `GET /api/providers/keys`, `POST /api/providers/keys`, `PUT /api/providers/keys/active`, `PUT /api/providers/keys/alias`, `DELETE /api/providers/keys` masked list, add (upsert + activate), switch, rename, and remove keys. `provider.apiKey` always mirrors the active pool entry so routing stays single-key. |
 | OpenAI account mode | Report one OpenAI Codex card with Pool/Direct controls and one API-key card. Mode PATCH persists live without restart or catalog identity changes; Pool owns account/quota controls and Direct uses caller/main login only. Main-account DTOs report real credential presence and terminal `needsReauth` state instead of treating missing/invalid native auth as an unknown quota. Selection order has its own route: `PUT /api/codex-auth/accounts/priority` takes `{ id, priority }`, where `priority` is an integer -100..100 or `null` to restore the default, accepts `__main__`, 404s an unknown id, and echoes the stored value. Re-ordering never clears thread affinity, so the response carries no `appliesImmediately`, but it does release any pin — see [`openai-tiers.md`](providers/openai-tiers.md) for why. `PUT /api/codex-auth/active` with a null id releases one too, but that drops the operator's account selection along with it, so this route is the only operator-facing way to clear a pin while leaving the selected account in place. `GET /api/codex-auth/active` reports `pinned`, true only while the manually selected account is still the effective active one, plus `pinnedAccountId`, which names the pinned account whether or not it is the active one. Surfaces should render `pinnedAccountId`: under round-robin and fill-first the pin caps the tier ceiling at its own tier while the strategy cursor moves freely inside that tier, so `pinned` goes false on a sibling's turn even though the pin is still suppressing every higher tier — which is why the dashboard badges `pinnedAccountId` and the GUI controller tracks only the id. `pinned` answers the narrower question of whether routing is *currently* on the operator's choice; no surface in this repo asks it, and a new one almost certainly wants the id instead. |
 | Subagents | Read/write the featured `subagentModels` list capped at five ids. `GET/PUT /api/injection-model` manages the shared delegation model/effort selection, the independent OpenCodex guidance switch, and the default-off `syncCodexSubagentDefaults` opt-in for native Codex subagent defaults. When OpenCodex owns the active Codex routing, native `[agents]` defaults apply to newly created Codex tasks after sync/restart; external user-managed provider configs remain untouched. The defaults do not cause delegation and preserve existing user-owned defaults rather than overwriting them. PUT is partial-update: absent keys are unchanged, `null` clears, and non-object bodies are rejected with 400 before field validation. `syncCodexSubagentDefaults: true` requires a nonblank `model` and a supported Codex reasoning effort when effort is set; clearing `model` (null/empty) always clears effort and disables native-default sync even when the stored effort was invalid. |
diff --git a/structure/providers-and-adapters.md b/structure/providers-and-adapters.md
index 337caff090a..d12813a05fe 100644
--- a/structure/providers-and-adapters.md
+++ b/structure/providers-and-adapters.md
@@ -194,7 +194,7 @@ rewrite rules and the routed-id settlement.
 | `src/providers/model-rename-fields.ts`, `src/providers/model-rename-migration.ts` | Classifies every provider config field for a declared model rename. Exact-model records, lists and nested request-pacing keys follow the replacement; an already saved replacement entry wins. Provider-wide settings, including response-tier authority and project-context consent, and credential fields are not model identities. |
 | `src/providers/resolved-model-policy.ts`, `src/providers/resolved-model-policy-merge.ts` | Static provider/model policy resolution for the final upstream wire model, plus its pure clone/merge/URL/family helpers. The resolver detaches and freezes registry defaults, operator overrides, exact explicit input-modality declarations, provider-scoped hard wire pins (including Command Code's `claude-` prefix), aliases, and explicit false/empty values with field-level provenance. Provider derivation, routing, catalog hints, gather admission, and adapter selection consume its detached frozen result. Callers supply transport match, the exact capability row, and a credential-free effective auth decision; credential bytes, usability evidence, account/quota/health state, and observed limits remain outside the result. |
 
-| `src/oauth/` | OAuth providers, token storage, refresh, and auth-token resolution. Meta Muse device authorization, polling, and key-mint JSON responses share the 64 KiB bounded-body ceiling and the request's deadline; oversized declared or streamed bodies are rejected before JSON parsing. The login callback listener binds a per-provider FIXED loopback port, so consecutive logins reuse the same number; every response it sends ends its connection (`Connection: close`, including non-callback paths such as a stray `/favicon.ico` 404). Stopping the listener does not close an established socket, so without that a pooled client would deliver the next login's callback to the retired flow, which rejects the unknown state as a CSRF mismatch while the live flow waits. Command Code manual callback JSON remains opaque to the shared `code#state` parser and is state-validated by its provider parser. A raw Command Code paste with an explicit `#state` suffix must match the flow state on the direct prompt as well. Kiro add-account identity prefers same-session `whoami` over a leftover SQLite state profile, and never persists the Builder ID service profile ARN as `accountId`. ChatGPT token exchange and refresh in `src/oauth/chatgpt.ts` compose caller cancellation with a fresh 30-second per-fetch deadline covering headers and body. Error bodies are capped at 16 KiB bytes and success JSON at 64 KiB; each settled call detaches its caller listener and clears its timer. The registration in `src/oauth/index.ts` preserves that signal and uses the shared Codex classifier through `ChatGptTokenError`: terminal grant refusals require an explicit allowlisted terminal OAuth code and mark only the matching generation `needsReauth`; free-text descriptions never establish terminality; transient failures remain retryable. HTTP-derived errors expose only status and allowlisted code. Cancellation and deadline errors use fixed AbortError/TimeoutError messages; transport and parsing failures also use fixed messages, without raw reasons or causes, and never mark reauthentication. The registry preserves its own stale-flight error. `tests/oauth/chatgpt-token-expiry.test.ts`, `tests/oauth/chatgpt-token-boundaries.test.ts` and `tests/oauth/oauth-refresh-generic-lock.test.ts` cover these boundaries with synthetic responses. |
+| `src/oauth/` | OAuth providers, token storage, refresh, and auth-token resolution. Antigravity `src/oauth/google-antigravity.ts` reads `loadCodeAssist.paidTier` from existing project discovery, without an extra request for the plan. `free-tier` maps to `Free`; a valid `Google AI ...` name is retained after trimming, without translation (at most 128 UTF-16 code units and no C0/C1 control characters). A successful, parseable response with missing, invalid or unrecognized `paidTier` yields `null`; request rejection, non-2xx status or JSON parse failure yields no new observation. Failed onboarding does not discard an observation already obtained. Persistence follows the [runtime observation semantics](runtime.md#entrypoints). Meta Muse device authorization, polling, and key-mint JSON responses share the 64 KiB bounded-body ceiling and the request's deadline; oversized declared or streamed bodies are rejected before JSON parsing. The login callback listener binds a per-provider FIXED loopback port, so consecutive logins reuse the same number; every response it sends ends its connection (`Connection: close`, including non-callback paths such as a stray `/favicon.ico` 404). Stopping the listener does not close an established socket, so without that a pooled client would deliver the next login's callback to the retired flow, which rejects the unknown state as a CSRF mismatch while the live flow waits. Command Code manual callback JSON remains opaque to the shared `code#state` parser and is state-validated by its provider parser. A raw Command Code paste with an explicit `#state` suffix must match the flow state on the direct prompt as well. Kiro add-account identity prefers same-session `whoami` over a leftover SQLite state profile, and never persists the Builder ID service profile ARN as `accountId`. ChatGPT token exchange and refresh in `src/oauth/chatgpt.ts` compose caller cancellation with a fresh 30-second per-fetch deadline covering headers and body. Error bodies are capped at 16 KiB bytes and success JSON at 64 KiB; each settled call detaches its caller listener and clears its timer. The registration in `src/oauth/index.ts` preserves that signal and uses the shared Codex classifier through `ChatGptTokenError`: terminal grant refusals require an explicit allowlisted terminal OAuth code and mark only the matching generation `needsReauth`; free-text descriptions never establish terminality; transient failures remain retryable. HTTP-derived errors expose only status and allowlisted code. Cancellation and deadline errors use fixed AbortError/TimeoutError messages; transport and parsing failures also use fixed messages, without raw reasons or causes, and never mark reauthentication. The registry preserves its own stale-flight error. `tests/oauth/chatgpt-token-expiry.test.ts`, `tests/oauth/chatgpt-token-boundaries.test.ts` and `tests/oauth/oauth-refresh-generic-lock.test.ts` cover these boundaries with synthetic responses. |
 | `src/combos/failover.ts` | Recognizes the exact bounded ChatGPT plan/model HTTP400 refusal in a bare message or a single `detail`/`error.message` envelope. Competing envelopes stop before code-based hops; finite evidence survives display truncation and SSE error reconstruction without retaining raw bodies. This permits another declared target before output commitment, never credential revocation or provider-wide quota evidence. |
 | `src/combos/request.ts` | Clones each selected combo target request and applies the existing target capability ladder: adaptive unknown targets and explicit empty ladders receive no unsupported reasoning/thinking controls, while known ladders retain per-target resolution. |
 | `src/adapters/openai-responses.ts`, `src/adapters/openai-responses/` | Native OpenAI/ChatGPT Responses passthrough. The canonical ChatGPT adapter forces its upstream-only `stream: true` requirement without changing caller `store`; downstream JSON negotiation remains owned by the [Responses HTTP/SSE contract](transports/responses.md#responses-httpsse). |
diff --git a/structure/runtime.md b/structure/runtime.md
index c4fcedef9c2..d967f07869d 100644
--- a/structure/runtime.md
+++ b/structure/runtime.md
@@ -157,7 +157,7 @@ there. Feature code is grouped by responsibility:
 | Group | Directories |
 | --- | --- |
 | Data plane | `src/adapters/`, `src/responses/`, `src/chat/`, `src/claude/`, `src/grok/`, `src/images/`, `src/vision/`, `src/web-search/` |
-| Codex integration | `src/codex/`, `src/combos/`, `src/providers/`, `src/oauth/` |
+| Codex integration | `src/codex/`, `src/combos/`, `src/providers/`, `src/oauth/` — Antigravity `plan` observations follow [provider parsing](providers-and-adapters.md). `merged` in `src/oauth/index.ts` and `retainUnobservedPlan` in `src/oauth/store.ts` preserve the previous value only when incoming `plan` is `undefined`, including refresh, account-scoped reauthentication and same-identity upsert. Explicit `null` clears the stored plan; a string replaces it. Store normalization rejects U+0000–U+001F and U+007F–U+009F before trimming, then accepts 1–128 UTF-16 code units; invalid present values normalize to `null`. The field is display-only and never affects authentication, quota, routing, account selection, health or failover. |
 | Surfaces | `src/server/`, `src/cli/`, `src/tray/`, `src/github/` |
 | Evidence and contracts | `src/compatibility/`, `src/lab/` |
 | Support | `src/lib/`, `src/storage/` (Worker policy fixtures synchronize after loading the initial policy; `src/storage/policy.ts` bounds the test barrier at 10 seconds), `src/usage/`, `src/update/` ([package refresh](ops/service-and-sidecars.md#package-cache-refresh); `desktop-badge.ts` holds bounded process-local display state, never install authority), `src/generated/` |