@narumitw/pi-usage 0.61.2 → 0.62.0

package/docs/providers.md

@@ -25,10 +25,10 @@ The README contains the capability overview and shared security requirements.
 ### OpenAI native ChatGPT OAuth
 
 - Provider ID: `openai`
-- Semantics: verified ChatGPT plan authentication, not measured subscription usage
-- Source: Pi's fresh native OAuth resolution and an exact complete credential match; no usage HTTP endpoint
-- Displayed data: **Connected (native OAuth)**, an explicit numerical-usage/reset-time limitation, and [ChatGPT usage settings](https://chatgpt.com/settings/usage)
-- Statusline: `chatgpt usage: web only`
+- Default semantics/source: verified native authentication through fresh Pi OAuth resolution and an exact complete credential match; no usage HTTP endpoint
+- Default display: **Connected (native OAuth)** and [ChatGPT usage settings](https://chatgpt.com/settings/usage)
+- Default statusline: `chatgpt usage: web only`
+- Opt-in source: experimental same-account Codex companion OAuth; distinct shared plan and app limits
 
 Use `/login openai` in a Pi runtime that supports native Sign in with ChatGPT, then select an official `https://api.openai.com` model.
 Authentication requires Pi's freshly resolved provider source to be `OAuth`, matching effective model and provider authorization, and a complete matching credential with `clientId` and the `chatgpt.tokens.use.direct` scope.
@@ -37,17 +37,39 @@ Stored OAuth alone and Pi's cached OAuth flag do not establish the active runtim
 Runtime/API-key overrides, model-level Authorization replacements or removals, and custom/proxy origins cannot inherit native subscription status.
 OpenAI API-key usage reporting remains unsupported.
 
-The report verifies authentication, not the plan tier, allowance, remaining quota, or reset time.
-Automatic refresh only revalidates auth; it does not poll a usage endpoint.
+The default report verifies authentication, not the plan tier, allowance, remaining quota, or reset time.
+Default automatic refresh only revalidates auth; it does not poll a usage endpoint.
 The settings link is guidance, not an automatically opened browser or a promise that the browser is signed into Pi's account.
 Native tokens are never sent to `/backend-api/wham`, and opaque native metadata is not decoded as a legacy Codex account ID.
-Legacy Fast payload rewriting, pricing correction, reset countdowns, and earned reset redemption do not apply to native `openai`.
+Legacy Fast payload rewriting, pricing correction, and earned reset redemption do not apply to native `openai`.
 Existing `openai-codex` behavior below is unchanged.
 
 The boundary is verified against Pi's [`openai-chatgpt.ts`](https://github.com/earendil-works/pi/blob/d86654abb8862e201933517d6f1fce9f88dd117f/packages/ai/src/auth/oauth/openai-chatgpt.ts) at `d86654abb8862e201933517d6f1fce9f88dd117f` and OpenAI's [models and inference](https://developers.openai.com/siwc/token-sharing-open-source/models-and-inference), [token reference](https://developers.openai.com/siwc/token-sharing-open-source/token-reference), and [UI/UX guidelines](https://developers.openai.com/siwc/ui-ux-guidelines).
 These contracts establish the public inference and authentication boundary, not a numerical usage API.
 Verification uses synthetic credentials with Pi's real auth resolver; live browser login and account-specific quota retrieval have not been verified.
 
+#### Experimental companion quotas
+
+Follow the [opt-in setup](../README.md#experimental-chatgpt-companion-usage): `openaiCompanionUsage` defaults to `false` and requires a same-account/workspace `/login openai-codex`.
+Fresh companion OAuth must match a complete grant with its own account ID; custom origins, API-key overrides, conflicting grants, and effective Authorization overrides fail closed.
+Only the companion bearer and matching `ChatGPT-Account-Id` reach these fixed, redirect-rejecting GET routes:
+
+- `https://chatgpt.com/backend-api/wham/usage/chatpass/apps`
+- `https://chatgpt.com/backend-api/wham/usage`
+
+The app list must be complete and bounded to 128 registrations, with a readable nonempty string `id` on every entry, exactly one `id` equal to the native grant's `clientId`, and 1–32 valid windows on that matched entry.
+Unknown envelope fields or pagination markers fail closed rather than assuming uniqueness on one page.
+Only plan primary/secondary windows are used; Codex model-specific limits are not native app quotas.
+Each window requires a finite 0–100 used percentage and positive whole-second duration; optional remaining percentages must agree within one percentage point, and reset timestamps must be valid nonnegative epoch seconds.
+`allowed_usage_percent` is **App allowance**, a cap on shared plan usage, not remaining quota.
+Plan/app windows and reset boundaries stay separate in reports and the statusline; Codex display preferences do not apply.
+
+Disabled or missing-companion paths remain web-only without requests. Other enabled-mode failures invalidate numerical data and remain observable.
+No native token, refresh token, app name, or account ID is rendered or persisted by this feature.
+An exact registration match is not independent identity proof; users must choose the same account/workspace for both logins.
+The endpoints are undocumented; live availability and numerical agreement remain unverified.
+Contract fixtures derive from [Specode's pinned implementation](https://github.com/specode/pi-subscription-usage/blob/1015f9f419dfef9ac27c9845ec2318394928fa38/src/providers/openai.ts) and [OpenAI's shared-plan/app-limit explanation](https://help.openai.com/en/articles/20001542-using-your-chatgpt-plan-in-other-apps-and-sites), not a public native quota API.
+
 ### OpenAI Codex
 
 - Provider ID: `openai-codex` (legacy; not an alias for native `openai`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@narumitw/pi-usage",
-  "version": "0.61.2",
+  "version": "0.62.0",
   "description": "Pi extension that shows current-account usage and DeepSeek API balance for supported providers.",
   "type": "module",
   "license": "MIT",
@@ -57,9 +57,9 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "1.0.0",
-    "@earendil-works/pi-coding-agent": "1.0.0",
-    "@earendil-works/pi-tui": "1.0.0",
+    "@earendil-works/pi-ai": "1.0.2",
+    "@earendil-works/pi-coding-agent": "1.0.2",
+    "@earendil-works/pi-tui": "1.0.2",
     "@types/node": "26.6.4",
     "esbuild": "0.28.2",
     "typescript": "7.0.2"

package/src/format.ts

@@ -28,7 +28,8 @@ export function formatUsageReport(report: UsageReport, displayState: UsageDispla
   if (report.accountLabel) lines.push(`Account: ${report.accountLabel}`);
   lines.push(`Semantics: ${report.semantics.label}`, "");
 
-  if (report.providerId === "baseten") formatBasetenReport(lines, report);
+  if (report.source === "openai-chatgpt-companion") formatOpenAICompanionReport(lines, report);
+  else if (report.providerId === "baseten") formatBasetenReport(lines, report);
   else if (report.providerId === "openai-codex") formatCodexReport(lines, report);
   else if (report.providerId === "deepseek") formatDeepSeekReport(lines, report);
   else if (report.providerId === "fireworks") formatFireworksReport(lines, report);
@@ -60,6 +61,19 @@ export function formatUsageStatusline(
   codexStatusPercentage: CodexStatusPercentage = "remaining",
 ): string | undefined {
   if (report.providerId === "openai" && report.source === "openai-chatgpt-auth") return "chatgpt usage: web only";
+  if (report.source === "openai-chatgpt-companion") {
+    return `chatgpt ${["chatgpt-plan", "chatgpt-app"]
+      .map((group) => {
+        const windows = report.buckets
+          .filter((bucket) => bucket.groupId === group)
+          .map((bucket) => {
+            const reset = formatResetCountdown(bucket.resetsAt, now);
+            return `${bucket.remaining === undefined ? "unavailable" : `${bucket.remaining.toFixed(0)}%`} ${reset ? `↻ ${reset}` : formatWindowLabel(bucket.windowMinutes, "weekly", true)}`;
+          });
+        return `${group === "chatgpt-plan" ? "plan" : "app"} ${windows.join(" ")}`;
+      })
+      .join(" · ")}`;
+  }
   if (report.providerId === "baseten") return formatBasetenStatusline(report);
   if (report.providerId === "openai-codex") {
     return formatCodexStatusline(report, model, now, showCodexResetCountdown, codexStatusPercentage);
@@ -522,6 +536,19 @@ function formatZaiReport(lines: string[], report: UsageReport): void {
   }
 }
 
+function formatOpenAICompanionReport(lines: string[], report: UsageReport): void {
+  for (const group of ["chatgpt-plan", "chatgpt-app"]) {
+    lines.push(group === "chatgpt-plan" ? "Plan limits:" : "App limits:");
+    for (const bucket of report.buckets.filter((bucket) => bucket.groupId === group)) {
+      lines.push(
+        `${formatWindowLabel(bucket.windowMinutes, "weekly", false).padEnd(VALUE_COLUMN)}${formatPercentBucket(bucket)}`,
+      );
+    }
+  }
+  for (const metric of report.metrics)
+    lines.push(`${`${metric.label}:`.padEnd(VALUE_COLUMN)}${formatMetricValue(metric.value, metric.unit)}`);
+}
+
 function formatGenericReport(lines: string[], report: UsageReport): void {
   for (const bucket of report.buckets) {
     lines.push(
@@ -668,6 +695,7 @@ function formatResetCountdown(resetsAt: number | undefined, now: number): string
 
 function formatMetricValue(value: number | string, unit: UsageBucket["unit"] | undefined): string {
   if (unit === "usd" && typeof value === "number") return formatUsd(value);
+  if (unit === "percent" && typeof value === "number") return `${value}%`;
   return String(value);
 }
 

package/src/openai-companion-auth.ts

@@ -0,0 +1,103 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { fingerprintResolvedAuth } from "./core.js";
+import { fallbackOAuthCredentialCandidates, type OAuthCredentialCandidateReader } from "./oauth-credential-source.js";
+import { openAIAuthAccessToken } from "./providers/openai-chatgpt.js";
+import { adapterForProvider, resolveUsageAuth } from "./query.js";
+import type { ResolvedUsageAuth } from "./types.js";
+
+// A native app registration is routing metadata, not cryptographic same-account proof.
+// Keep this opt-in boundary separate from legacy Codex querying and reset mutation policy.
+export async function resolveOpenAICompanionAuth(
+  ctx: ExtensionContext,
+  native: ResolvedUsageAuth,
+  salt: Uint8Array,
+  credentialReader: (providerId: string) => unknown,
+  candidateReader?: OAuthCredentialCandidateReader,
+): Promise<ResolvedUsageAuth> {
+  const unavailable = () => ({
+    ...native,
+    openaiCompanionEnabled: true,
+    fingerprint: fingerprintResolvedAuth(
+      { apiKey: JSON.stringify([native.fingerprint, native.openaiClientId, true, null]) },
+      salt,
+    ),
+  });
+  if (candidateReader?.waitUntilReady && !(await candidateReader.waitUntilReady(ctx, "openai-codex"))) {
+    throw new Error("Companion Codex OAuth credential readiness failed closed.");
+  }
+  const adapter = adapterForProvider("openai-codex");
+  if (!adapter) throw new Error("Companion Codex usage support is unavailable.");
+  const companion = await resolveUsageAuth(ctx, adapter, salt, credentialReader);
+  if (!companion) return unavailable();
+  if (companion.source !== "OAuth")
+    throw new Error("Companion usage requires /login openai-codex OAuth, not an API key.");
+  // Legacy querying is more permissive. Enforce explicit Authorization removals and duplicates
+  // against preserved fresh provider auth before using its normalized request headers.
+  const access = openAIAuthAccessToken(companion.auth);
+  if (ctx.model?.provider === "openai-codex") {
+    const selected = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+    if (
+      !selected.ok ||
+      (selected.baseUrl && new URL(selected.baseUrl).origin !== "https://chatgpt.com") ||
+      openAIAuthAccessToken(selected) !== access
+    ) {
+      throw new Error("Selected Codex model authorization does not match the companion OAuth credential.");
+    }
+  }
+  if (!access || access !== openAIAuthAccessToken(companion)) {
+    throw new Error("Companion Codex runtime authorization did not match its OAuth credential.");
+  }
+  const accountId = codexAccountId(access);
+  if (!accountId) throw new Error("Companion Codex token did not contain a valid account ID.");
+  const offered = candidateReader
+    ? await candidateReader(ctx, "openai-codex")
+    : fallbackOAuthCredentialCandidates("openai-codex", credentialReader);
+  if (!offered.ok) throw new Error("Companion Codex OAuth credential discovery failed closed.");
+  const matches = new Set<string>();
+  for (const candidate of offered.candidates) {
+    const credential = object(candidate);
+    if (credential?.type !== "oauth" || credential.access !== access) continue;
+    if (
+      credential.accountId !== accountId ||
+      typeof credential.refresh !== "string" ||
+      !credential.refresh ||
+      typeof credential.expires !== "number" ||
+      !Number.isFinite(credential.expires)
+    ) {
+      throw new Error("The matching companion Codex OAuth credential was incomplete or had a different account ID.");
+    }
+    matches.add(credential.refresh);
+  }
+  if (matches.size !== 1) throw new Error("Companion Codex OAuth must uniquely match the fresh runtime credential.");
+  const headers = { Authorization: `Bearer ${access}`, "ChatGPT-Account-Id": accountId };
+  return {
+    ...native,
+    openaiCompanionEnabled: true,
+    openaiCompanion: { headers },
+    fingerprint: fingerprintResolvedAuth(
+      { apiKey: JSON.stringify([native.fingerprint, native.openaiClientId, true, companion.fingerprint, headers]) },
+      salt,
+    ),
+    secrets: [
+      ...new Set([...native.secrets, ...companion.secrets, ...matches, access, accountId, headers.Authorization]),
+    ],
+  };
+}
+
+function codexAccountId(access: string): string | undefined {
+  try {
+    const parts = access.split(".");
+    if (parts.length !== 3 || !parts[1]) return undefined;
+    const payload = object(JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8")));
+    const account = object(payload?.["https://api.openai.com/auth"])?.chatgpt_account_id;
+    return typeof account === "string" && account.length > 0 && account.length <= 512 && /^[\x21-\x7e]+$/u.test(account)
+      ? account
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}

package/src/providers/openai-chatgpt.ts

@@ -24,7 +24,13 @@ export const OPENAI_CHATGPT_ADAPTER: UsageProviderAdapter = {
   id: "openai",
   displayName: "OpenAI",
   semantics: { kind: "consumer-subscription", label: "ChatGPT plan authentication status" },
-  async query(_auth, signal, _timeoutMs, guard) {
+  invalidateCacheOnFailure: true,
+  async query(auth, signal, timeoutMs, guard) {
+    if (auth.openaiCompanion) {
+      const { queryOpenAICompanionUsage } = await import("./openai-companion-usage.js");
+      signal.throwIfAborted();
+      return queryOpenAICompanionUsage(auth, signal, timeoutMs, guard);
+    }
     if (!guard) throw new Error("ChatGPT plan status requires runtime-auth revalidation.");
     signal.throwIfAborted();
     await guard();
@@ -40,6 +46,11 @@ export const OPENAI_CHATGPT_ADAPTER: UsageProviderAdapter = {
       notes: [
         "Numerical usage and reset times are unavailable in pi-usage for native OpenAI OAuth.",
         `Manage usage: ${CHATGPT_USAGE_SETTINGS_URL}`,
+        ...(auth.openaiCompanionEnabled
+          ? [
+              "Experimental companion usage requires /login openai-codex with the same ChatGPT account/workspace; native inference stays on openai.",
+            ]
+          : []),
         "Fast mode and earned reset redemption remain legacy openai-codex features.",
       ],
     };
@@ -56,11 +67,11 @@ export function resolveOpenAIChatGPTAuth(
   // isUsingOAuth() is a cached snapshot; source alone is also insufficient when a model header
   // overrides Authorization. Match both freshly resolved credentials and the exact native grant.
   if (source !== "OAuth") throw new UnsupportedOpenAIUsageAuthError();
-  const access = accessToken(auth);
-  if (!access || access !== accessToken(providerAuth)) {
+  const access = openAIAuthAccessToken(auth);
+  if (!access || access !== openAIAuthAccessToken(providerAuth)) {
     throw new Error("The active OpenAI model authorization does not match its resolved OAuth credential.");
   }
-  const matches = new Map<string, string>();
+  const matches = new Map<string, { refresh: string; clientId: string }>();
   for (const candidate of candidates) {
     if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) continue;
     const credential = candidate as Record<string, unknown>;
@@ -80,24 +91,28 @@ export function resolveOpenAIChatGPTAuth(
         "The matching OpenAI OAuth credential is not a complete native ChatGPT grant; reconnect with /login openai.",
       );
     }
-    matches.set(JSON.stringify([credential.clientId, credential.refresh]), credential.refresh);
+    matches.set(JSON.stringify([credential.clientId, credential.refresh]), {
+      refresh: credential.refresh,
+      clientId: credential.clientId,
+    });
   }
   if (matches.size > 1)
     throw new Error("Conflicting native ChatGPT credentials match the active OpenAI runtime account.");
-  const refresh = matches.values().next().value;
-  if (!refresh)
+  const match = matches.values().next().value;
+  if (!match)
     throw new Error("The active OpenAI runtime account does not match an available native ChatGPT OAuth credential.");
   const authorization = `Bearer ${access}`;
   return {
+    openaiClientId: match.clientId,
     apiKey: access,
     headers: { Authorization: authorization },
     fingerprint: "",
-    secrets: [access, refresh, authorization],
+    secrets: [access, match.refresh, authorization, match.clientId],
     model,
   };
 }
 
-function accessToken(auth: RequestAuth | undefined): string | undefined {
+export function openAIAuthAccessToken(auth: RequestAuth | undefined): string | undefined {
   if (!auth) return undefined;
   const authorization = Object.entries(auth.headers ?? {}).filter(([name]) => name.toLowerCase() === "authorization");
   if (authorization.length > 1) throw new Error("OpenAI runtime authorization headers are ambiguous.");

package/src/providers/openai-companion-usage.ts

@@ -0,0 +1,146 @@
+import { fetchProviderJson } from "../query.js";
+import type { ResolvedUsageAuth, UsageBucket, UsageReport, UsageRequestGuard } from "../types.js";
+import { CHATGPT_USAGE_SETTINGS_URL } from "./openai-chatgpt.js";
+
+const USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const MAX_APPS = 128;
+const MAX_WINDOWS = 32;
+
+// Evidence: pinned Specode openai.ts at 1015f9f419dfef9ac27c9845ec2318394928fa38
+// and OpenAI's Help Center article 20001542. Backend shapes remain undocumented.
+// Accept only a complete list; unknown list envelope fields fail closed, including pagination.
+export function matchingOpenAIAppBuckets(
+  payload: unknown,
+  clientId: string,
+): { buckets: UsageBucket[]; allowance?: number } {
+  const root = object(payload);
+  if (
+    !root ||
+    !Array.isArray(root.items) ||
+    root.items.length > MAX_APPS ||
+    Object.keys(root).some((key) => !["items", "has_more", "next_cursor"].includes(key)) ||
+    (root.has_more !== undefined && root.has_more !== false) ||
+    (root.next_cursor !== undefined && root.next_cursor !== null && root.next_cursor !== "")
+  ) {
+    throw new Error("ChatGPT app usage requires a complete, bounded registration list; pagination is unsupported.");
+  }
+  const apps = root.items.map(object);
+  if (apps.some((app) => !app || typeof app.id !== "string" || !app.id.trim())) {
+    throw new Error(
+      "ChatGPT app usage returned an unreadable registration identity; uniqueness cannot be established.",
+    );
+  }
+  const matches = apps.filter((app) => app?.id === clientId);
+  if (!clientId || matches.length !== 1) {
+    throw new Error(
+      "The native registration was not uniquely found in the companion Codex account; use the same ChatGPT account/workspace for both logins.",
+    );
+  }
+  const app = matches[0];
+  if (!Array.isArray(app?.windows) || app.windows.length === 0 || app.windows.length > MAX_WINDOWS) {
+    throw new Error("ChatGPT app usage returned no bounded, displayable windows.");
+  }
+  const allowance = app.allowed_usage_percent;
+  if (allowance !== undefined && !percent(allowance)) throw new Error("ChatGPT app allowance was invalid.");
+  return {
+    buckets: app.windows.map((window, index) => normalizeWindow(window, `app:${index}`, "chatgpt-app", "App limits")),
+    ...(allowance === undefined ? {} : { allowance: allowance as number }),
+  };
+}
+
+export async function queryOpenAICompanionUsage(
+  auth: ResolvedUsageAuth,
+  signal: AbortSignal,
+  timeoutMs: number,
+  guard?: UsageRequestGuard,
+): Promise<UsageReport> {
+  if (!guard) throw new Error("Companion ChatGPT usage requires request-boundary revalidation.");
+  if (!auth.openaiCompanion || !auth.openaiClientId)
+    throw new Error("Companion ChatGPT usage authentication was incomplete.");
+  const startedAt = Date.now();
+  // Never pass native apiKey/auth/env to transport: the only request credential is the companion.
+  const backend: ResolvedUsageAuth = {
+    headers: { ...auth.openaiCompanion.headers },
+    fingerprint: auth.fingerprint,
+    secrets: auth.secrets,
+    model: auth.model,
+  };
+  const read = async (url: string, description: string) => {
+    signal.throwIfAborted();
+    await guard();
+    signal.throwIfAborted();
+    const remaining = timeoutMs - (Date.now() - startedAt);
+    if (remaining <= 0) throw new Error("Timed out while fetching companion ChatGPT usage.");
+    const payload = await fetchProviderJson(url, backend, signal, remaining, description, { redirect: "error" });
+    await guard();
+    signal.throwIfAborted();
+    return payload;
+  };
+  const appPayload = await read(`${USAGE_URL}/chatpass/apps`, "ChatGPT companion app usage endpoint");
+  const app = matchingOpenAIAppBuckets(appPayload, auth.openaiClientId);
+  // Match and validate the app before reading plan data; never substitute Codex-only quotas.
+  const planPayload = await read(USAGE_URL, "ChatGPT companion plan usage endpoint");
+  const rateLimit = object(planPayload.rate_limit);
+  const planBuckets: UsageBucket[] = [];
+  for (const position of ["primary", "secondary"] as const) {
+    const window = rateLimit?.[`${position}_window`];
+    if (window !== undefined && window !== null)
+      planBuckets.push(normalizeWindow(window, `plan:${position}`, "chatgpt-plan", "Plan limits"));
+  }
+  if (planBuckets.length === 0) throw new Error("ChatGPT plan usage returned no displayable windows.");
+  return {
+    providerId: "openai",
+    providerName: "OpenAI",
+    capturedAt: Date.now(),
+    source: "openai-chatgpt-companion",
+    semantics: { kind: "consumer-subscription", label: "ChatGPT plan and app limits (experimental companion source)" },
+    buckets: [...planBuckets, ...app.buckets],
+    metrics:
+      app.allowance === undefined
+        ? []
+        : [{ id: "app-allowance", label: "App allowance", value: app.allowance, unit: "percent" }],
+    notes: [
+      "Source: companion Codex OAuth; registration matching is not independent proof of the same user/workspace.",
+      "App allowance caps shared plan usage; it is not remaining or reserved quota.",
+      `Manage usage: ${CHATGPT_USAGE_SETTINGS_URL}`,
+    ],
+  };
+}
+
+function normalizeWindow(raw: unknown, id: string, groupId: string, groupLabel: string): UsageBucket {
+  const window = object(raw);
+  const used = window?.used_percent;
+  const remaining = window?.remaining_percent;
+  const seconds = window?.limit_window_seconds;
+  const resetsAt = window?.reset_at;
+  if (
+    !percent(used) ||
+    (remaining !== undefined && (!percent(remaining) || Math.abs(used + remaining - 100) > 1)) ||
+    typeof seconds !== "number" ||
+    !Number.isSafeInteger(seconds) ||
+    seconds <= 0 ||
+    (resetsAt !== undefined &&
+      (typeof resetsAt !== "number" || !Number.isSafeInteger(resetsAt) || resetsAt < 0 || resetsAt > 8_640_000_000_000))
+  ) {
+    throw new Error("ChatGPT usage returned an invalid or contradictory window.");
+  }
+  return {
+    id,
+    label: "Subscription limit",
+    groupId,
+    groupLabel,
+    used,
+    remaining: remaining === undefined ? 100 - used : (remaining as number),
+    limit: 100,
+    unit: "percent",
+    windowMinutes: Math.ceil(seconds / 60),
+    ...(resetsAt === undefined ? {} : { resetsAt: resetsAt as number }),
+  };
+}
+
+function percent(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 100;
+}
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}

package/src/query.ts

@@ -340,6 +340,7 @@ export async function resolveUsageAuth(
   salt: Uint8Array = AUTH_FINGERPRINT_SALT,
   credentialReader: StoredCredentialReader = readStoredCredential,
   candidateReader?: OAuthCredentialCandidateReader,
+  openaiCompanionUsage = false,
 ): Promise<ResolvedUsageAuth | undefined> {
   if (ctx.model?.provider === adapter.id && !hasOfficialOrigin(ctx.model, adapter.id)) {
     throw new Error(
@@ -437,9 +438,12 @@ export async function resolveUsageAuth(
       ? await candidateReader(ctx, adapter.id)
       : fallbackOAuthCredentialCandidates(adapter.id, credentialReader);
     if (!offered.ok) throw new Error("OpenAI OAuth credential discovery failed closed.");
-    return finalize(
+    const native = finalize(
       resolveOpenAIChatGPTAuth(auth, providerResult.auth, providerResult.source, model, offered.candidates),
     );
+    if (!openaiCompanionUsage) return native;
+    const { resolveOpenAICompanionAuth } = await import("./openai-companion-auth.js");
+    return resolveOpenAICompanionAuth(ctx, native, salt, credentialReader, candidateReader);
   }
   if (adapter.id === "github-copilot") {
     const offered = candidateReader

package/src/settings.ts

@@ -12,6 +12,8 @@ export const MAX_USAGE_SETTINGS_BYTES = 64 * 1024;
 export type CodexStatusPercentage = "remaining" | "used";
 
 export interface UsageSettings {
+  /** Omitted values preserve default-off compatibility for injected settings runtimes. */
+  openaiCompanionUsage?: boolean;
   codexFastMode: boolean;
   codexStatusResetCountdown: boolean;
   codexStatusPercentage: CodexStatusPercentage;
@@ -19,6 +21,7 @@ export interface UsageSettings {
 }
 
 export const DEFAULT_USAGE_SETTINGS: Readonly<UsageSettings> = Object.freeze({
+  openaiCompanionUsage: false,
   codexFastMode: false,
   codexStatusResetCountdown: true,
   codexStatusPercentage: "remaining",
@@ -64,6 +67,7 @@ export function usageSettingsPath(): string {
 
 export function normalizeUsageSettings(value: unknown): UsageSettings | undefined {
   if (!isRecord(value)) return undefined;
+  if (Object.hasOwn(value, "openaiCompanionUsage") && typeof value.openaiCompanionUsage !== "boolean") return undefined;
   if (Object.hasOwn(value, "codexFastMode") && typeof value.codexFastMode !== "boolean") {
     return undefined;
   }
@@ -87,6 +91,7 @@ export function normalizeUsageSettings(value: unknown): UsageSettings | undefine
     effectiveTargets.fireworks = value.fireworksAccountId;
   }
   return {
+    openaiCompanionUsage: value.openaiCompanionUsage === true,
     codexFastMode:
       typeof value.codexFastMode === "boolean" ? value.codexFastMode : DEFAULT_USAGE_SETTINGS.codexFastMode,
     codexStatusResetCountdown:

package/src/types.ts

@@ -48,6 +48,10 @@ export interface UsageReport {
 }
 
 export interface ResolvedUsageAuth {
+  /** Native registration metadata stays local; only companion headers reach ChatGPT. */
+  openaiClientId?: string;
+  openaiCompanionEnabled?: boolean;
+  openaiCompanion?: { headers: Record<string, string> };
   apiKey?: string;
   headers: Record<string, string>;
   fingerprint: string;

package/src/usage-settings-ui.ts

@@ -9,7 +9,7 @@ const ON = "On";
 const REMAINING = "Remaining";
 const USED = "Used";
 
-type UsageSettingId = "codexFastMode" | "codexStatusResetCountdown" | "codexStatusPercentage";
+type UsageSettingId = "codexFastMode" | "codexStatusResetCountdown" | "codexStatusPercentage" | "openaiCompanionUsage";
 
 function settingValueLabel(id: UsageSettingId, value: UsageSettings[UsageSettingId]): string {
   if (id === "codexStatusPercentage") return value === "used" ? USED : REMAINING;
@@ -29,11 +29,12 @@ export async function showUsageSettings(
   }
   const { HorizontalRule, renderBoundedFrame } = await import("@narumitw/pi-tui-kit");
   if (parentSignal.aborted || !isCurrent()) return false;
-  return (
-    (await ctx.ui.custom<boolean>((tui, theme, _keybindings, done) => {
+  let changed = false;
+  let selectedId: UsageSettingId | undefined;
+  for (;;) {
+    const result = await ctx.ui.custom<boolean | "consent">((tui, theme, _keybindings, done) => {
       const localController = new AbortController();
       const signal = AbortSignal.any([parentSignal, localController.signal]);
-      let changed = false;
       let closing = false;
       let saveQueue = Promise.resolve();
       const state = settingsRuntime.get();
@@ -59,18 +60,28 @@ export async function showUsageSettings(
           currentValue: settingValueLabel("codexStatusPercentage", state.settings.codexStatusPercentage),
           values: [REMAINING, USED],
         },
+        {
+          id: "openaiCompanionUsage",
+          label: "Experimental ChatGPT companion usage",
+          description:
+            "Read undocumented plan/app usage using a same-account Codex login; matching registration does not prove identity.",
+          currentValue: state.settings.openaiCompanionUsage ? ON : OFF,
+          values: [OFF, ON],
+        },
       ];
       const rule = new HorizontalRule({ ruleStyle: (text) => theme.fg("border", text) });
 
       let settingsList: SettingsList;
-      const cancel = () => {
+      const close = (result: boolean | "consent") => {
         if (closing) return;
         closing = true;
         localController.abort();
-        done(changed);
+        done(result);
       };
+      const cancel = () => close(changed);
       const queueUpdate = <Id extends UsageSettingId>(id: Id, requested: UsageSettings[Id], display: string) => {
         saveQueue = saveQueue.then(async () => {
+          if (signal.aborted || !isCurrent()) return;
           const previous = settingsRuntime.get().settings[id];
           if (settingsRuntime.get().kind === "invalid") {
             settingsList.updateValue(id, settingValueLabel(id, previous));
@@ -81,6 +92,14 @@ export async function showUsageSettings(
             return;
           }
           try {
+            if (id === "openaiCompanionUsage" && requested === true && previous !== true) {
+              // Pi's confirm dialog replaces a non-overlay custom screen and restores
+              // the editor, not that screen. Complete/dispose Settings first; after
+              // consent, mount a fresh instance with the initiating row selected.
+              selectedId = id;
+              close("consent");
+              return;
+            }
             const patch: Partial<UsageSettings> = {};
             patch[id] = requested;
             await settingsRuntime.update(patch, signal);
@@ -91,6 +110,8 @@ export async function showUsageSettings(
             tui.requestRender();
             return;
           }
+          // A rename can win a cancellation race. Apply owned lifecycle cleanup after a
+          // durable save, but let the owner guard its session before touching UI.
           if (previous !== requested) {
             changed = true;
             onApplied(id);
@@ -106,15 +127,17 @@ export async function showUsageSettings(
         getSettingsListTheme(),
         (id, value) => {
           if (closing || signal.aborted || !isCurrent()) return;
+          selectedId = id as UsageSettingId;
           if (id === "codexStatusPercentage") {
             queueUpdate(id, value === USED ? "used" : "remaining", value);
-          } else if (id === "codexFastMode" || id === "codexStatusResetCountdown") {
+          } else if (id === "codexFastMode" || id === "codexStatusResetCountdown" || id === "openaiCompanionUsage") {
             queueUpdate(id, value === ON, value);
           }
         },
         cancel,
       );
 
+      if (selectedId) settingsList.selectItem(selectedId);
       parentSignal.addEventListener("abort", cancel, { once: true });
       return {
         render(width: number) {
@@ -147,6 +170,25 @@ export async function showUsageSettings(
           parentSignal.removeEventListener("abort", cancel);
         },
       };
-    })) ?? false
-  );
+    });
+    if (result !== "consent" || parentSignal.aborted || !isCurrent()) return changed;
+    try {
+      const accepted = await ctx.ui.confirm(
+        "Enable experimental ChatGPT companion usage?",
+        "Requires /login openai-codex with the same ChatGPT account/workspace as native OpenAI. Only the companion token and its matching account ID are sent to undocumented ChatGPT usage endpoints. Registration matching is not independent proof of the same user/workspace. No reset or allowance mutations are performed.",
+        { signal: parentSignal },
+      );
+      if (parentSignal.aborted || !isCurrent()) return changed;
+      if (accepted && !settingsRuntime.get().settings.openaiCompanionUsage) {
+        await settingsRuntime.update({ openaiCompanionUsage: true }, parentSignal);
+        changed = true;
+        // A durable rename may win cancellation; the owner guards lifecycle cleanup.
+        onApplied("openaiCompanionUsage");
+      }
+    } catch (error) {
+      if (parentSignal.aborted || !isCurrent()) return changed;
+      ctx.ui.notify(`Could not enable ChatGPT companion usage: ${errorMessage(error)}`, "error");
+    }
+    if (parentSignal.aborted || !isCurrent()) return changed;
+  }
 }