@bitkyc08/opencodex 2.49.0 → 2.51.0

package/src/lib/test-home-guard.ts

@@ -61,6 +61,16 @@ function canonicalize(path: string): string {
 const REAL_HOME = process.env[REAL_HOME_ENV]?.trim() || homedir();
 const PROTECTED_HOME = canonicalize(join(REAL_HOME, ".opencodex"));
 const PROTECTED_CODEX_HOME = canonicalize(join(REAL_HOME, ".codex"));
+/**
+ * `~/Library/LaunchAgents` needs its own entry because HOME isolation does not reach it:
+ * `os.homedir()` reads the password database, not `$HOME`, so a macOS test that rewrites
+ * HOME still resolves `plistPath()` to the developer's real LaunchAgents directory. The
+ * launchd install tests were doing exactly that — replacing the live
+ * `com.opencodex.proxy.plist` with one whose token file, log path and Bun paths all point
+ * into a temp sandbox, for as long as the case ran. launchd holds its own parsed copy, so
+ * nothing broke until the job next restarted.
+ */
+const PROTECTED_LAUNCH_AGENTS = canonicalize(join(REAL_HOME, "Library", "LaunchAgents"));
 
 /** The production home this process protects. Exported for the guard's own tests. */
 export function protectedHomeForTests(): string {
@@ -76,6 +86,23 @@ export function isTestHomeGuardArmed(): boolean {
   return process.env[GUARD_ENV] === "1";
 }
 
+/**
+ * Whether `dir` IS the protected production home, decided with the SAME canonicalization as
+ * {@link assertNotRealHomeUnderTest}.
+ *
+ * For the caller that must FILTER the real home out of a candidate list instead of refusing
+ * one write: `serviceStatePaths()` in `src/service.ts` keeps a legacy
+ * `~/.opencodex/service-state.json` entry so an install made before OPENCODEX_HOME existed
+ * can still be found, and under an armed test process that entry is the developer's live
+ * record. Exported so that filter cannot drift onto a weaker comparison — `resolve()` alone
+ * calls `/var/folders/...` and `/private/var/folders/...` different paths, which is exactly
+ * how a macOS sandbox path slips past a string compare.
+ */
+export function isProtectedHomeUnderTest(dir: string): boolean {
+  if (!isTestHomeGuardArmed()) return false;
+  return canonicalize(dir) === PROTECTED_HOME;
+}
+
 /**
  * Throw when an armed test process is about to write the real OpenCodex home.
  *
@@ -94,6 +121,28 @@ export function assertNotRealHomeUnderTest(dir: string): void {
   );
 }
 
+/** The production LaunchAgents directory this process protects. Exported for its tests. */
+export function protectedLaunchAgentsDirForTests(): string {
+  return PROTECTED_LAUNCH_AGENTS;
+}
+
+/**
+ * Throw when an armed test process is about to write the real `~/Library/LaunchAgents`.
+ *
+ * Same contract as {@link assertNotRealHomeUnderTest}: call before any mkdir/write, and
+ * pass a DIRECTORY. A launchd test gives `installLaunchd` an explicit plist path inside its
+ * own fixture directory instead.
+ */
+export function assertNotRealLaunchAgentsUnderTest(dir: string): void {
+  if (!isTestHomeGuardArmed()) return;
+  if (canonicalize(dir) !== PROTECTED_LAUNCH_AGENTS) return;
+  throw new Error(
+    `refusing to write the real LaunchAgents directory (${PROTECTED_LAUNCH_AGENTS}) from a test `
+    + "process: os.homedir() ignores HOME, so rewriting HOME does not move this path. Pass an "
+    + "explicit plist path inside the test's own fixture directory instead.",
+  );
+}
+
 /** Throw when an armed test process is about to write the real native Codex home. */
 export function assertNotRealCodexHomeUnderTest(dir: string): void {
   if (!isTestHomeGuardArmed()) return;

package/src/oauth/health.ts

@@ -1,7 +1,7 @@
 import { getCodexAccountHealthSnapshot, type CodexCooldownSource } from "../codex/routing";
 import { getAnthropicAccountHealthSnapshot } from "./anthropic-routing";
 import { isAccountNeedsReauth } from "../codex/account-runtime-state";
-import { getCodexAccountCredential, listCodexAccountIds } from "../codex/account-store";
+import { getCodexAccountCredential, listCodexAccountIds, readCodexAccountRecord } from "../codex/account-store";
 import { MAIN_CODEX_ACCOUNT_ID } from "../codex/main-account";
 import { readRuntimePort } from "../config/process-state";
 import { LOCAL_MANAGEMENT_READ_PATHS } from "../lib/local-management-capability";
@@ -15,7 +15,7 @@ export type OAuthAccountHealth =
   | { status: "healthy" }
   | { status: "cooldown"; until: string; reason: "rate_limit" | "quota" }
   | { status: "reauth_required"; reason: "unauthorized" | "forbidden" | "refresh_failed" }
-  | { status: "warning"; reason: "refresh_conflict" | "metadata_mismatch" | "stale_credentials" };
+  | { status: "warning"; reason: "refresh_conflict" | "metadata_mismatch" | "stale_credentials" | "validation_pending" };
 
 export type OAuthHealthLabel =
   | "Healthy"
@@ -24,7 +24,8 @@ export type OAuthHealthLabel =
   | "Reauthentication required"
   | "Refresh failed"
   | "Metadata mismatch"
-  | "Credential conflict";
+  | "Credential conflict"
+  | "Validation pending";
 
 /** Shared masked-id fallback when `maskAccountId` returns nullish. */
 export const MASKED_ACCOUNT_FALLBACK = "account-…????";
@@ -88,6 +89,9 @@ export function projectOAuthAccountHealth(input: {
 export const CODEX_REAUTH_ACTION = "reauthenticate via the dashboard Codex account pool";
 
 function actionFor(provider: string, health: OAuthAccountHealth): string | undefined {
+  if (health.status === "warning" && health.reason === "validation_pending") {
+    return "wait for quota recovery, then click Refresh quotas in the dashboard Codex account pool to finish validation";
+  }
   if (health.status === "reauth_required") {
     if (provider === "codex") return CODEX_REAUTH_ACTION;
     return `run \`ocx login ${provider}\``;
@@ -112,6 +116,8 @@ export function oauthHealthLabel(health: OAuthAccountHealth): OAuthHealthLabel {
       return health.reason === "refresh_failed" ? "Refresh failed" : "Reauthentication required";
     case "warning":
       switch (health.reason) {
+        case "validation_pending":
+          return "Validation pending";
         case "refresh_conflict":
           return "Credential conflict";
         case "metadata_mismatch":
@@ -198,11 +204,42 @@ export function projectCodexAccountHealth(input: {
   needsReauth: boolean;
   now?: number;
 }): OAuthAccountHealth {
+  // One read serves every verdict below. Each lookup re-reads and re-hardens the whole store
+  // file, and the main account lives in the native Codex auth file rather than the pool store,
+  // so a lookup for it could only ever miss.
+  const stored = input.accountId !== MAIN_CODEX_ACCOUNT_ID ? readCodexAccountRecord(input.accountId) : null;
+  const record = stored?.deletedAt == null ? stored : null;
+
+  // A successful quota read is not evidence that model authorization recovered.
+  // Preserve this guidance until validation succeeds or reauthentication replaces it.
+  const validationAuthFailed = record !== null
+    && record.codexValidationPending === true
+    && record.lastCodexValidationStatus === "failed"
+    && (record.lastCodexValidationError === "http_status:401" || record.lastCodexValidationError === "http_status:403");
+
+  // A persisted terminal verdict outranks the in-memory reauth flag rather than duplicating it:
+  // the flag lives in this process and a revoked grant does not. Without it, an account whose
+  // grant was revoked upstream keeps its login-time `lastCodexValidationStatus: "ok"` and every
+  // surface reports it healthy until someone tries to use it (#4120). Only a re-login clears the
+  // marker, so `reauth_required` is the accurate projection — and it is deliberately checked
+  // ahead of any cooldown, because telling an operator to wait out a rate limit on a credential
+  // that will never work again is a false promise.
+  const terminalGrantFailure = record !== null
+    && record.lastCodexValidationTerminal === true
+    && record.lastCodexValidationStatus === "failed";
+
+  const needsReauth = input.needsReauth || validationAuthFailed || terminalGrantFailure;
+
+  // Deferred validation is only worth reporting while the credential itself is still viable. A
+  // revoked grant needs a re-login, not a "Refresh quotas" click, so reauth is resolved first.
+  if (!needsReauth && record?.codexValidationPending) {
+    return { status: "warning", reason: "validation_pending" };
+  }
   const now = input.now ?? Date.now();
   const snap = getCodexAccountHealthSnapshot(input.accountId, now);
   return projectOAuthAccountHealth({
-    needsReauth: input.needsReauth,
-    reauthReason: input.needsReauth ? "refresh_failed" : undefined,
+    needsReauth,
+    reauthReason: needsReauth ? "refresh_failed" : undefined,
     cooldownUntilMs: snap?.cooldownUntil,
     cooldownReason: cooldownReasonFromSource(snap?.cooldownSource),
     now,
@@ -272,13 +309,11 @@ function collectLocalCodexEntries(now: number): OAuthHealthEntry[] {
     const hasPoolCredential = accountId !== MAIN_CODEX_ACCOUNT_ID && getCodexAccountCredential(accountId) !== null;
     if (!hasPoolCredential && !needsReauth && !snap) continue;
 
-    const health = projectOAuthAccountHealth({
-      needsReauth,
-      reauthReason: needsReauth ? "refresh_failed" : undefined,
-      cooldownUntilMs: snap?.cooldownUntil,
-      cooldownReason: cooldownReasonFromSource(snap?.cooldownSource),
-      now,
-    });
+    // Call the projector rather than inlining a second copy of it. This collector serves the CLI
+    // (`ocx status`, `ocx doctor`) while the dashboard DTO goes through projectCodexAccountHealth,
+    // and the duplicated body is exactly how the CLI would have kept reporting a revoked account
+    // as healthy after the dashboard stopped.
+    const health = projectCodexAccountHealth({ accountId, needsReauth, now });
     pushEntry(entries, "codex", accountId, health);
   }
   return entries;

package/src/oauth/index.ts

@@ -4,7 +4,7 @@ import { parseCallbackInput } from "./callback-server";
 import type { OcxConfig, OcxProviderConfig, RefreshPolicy } from "../types";
 import { ConfigMutationLockError, loadConfig, mutatePersistedConfig, saveConfig } from "../config";
 import { resolveProviderApiKey } from "../providers/key-store";
-import { maskEmail } from "../lib/privacy";
+import { projectEmail } from "../lib/privacy";
 import { KiroTokenRefreshError, environmentKiroRoutingMetadata, loginKiro, refreshKiroToken, settleKiroLoginTransaction } from "./kiro";
 import {
   OAuthMutationBusyError,
@@ -1781,19 +1781,54 @@ export function submitManualLoginCode(provider: string, input: string): { ok: tr
   return { ok: true };
 }
 
-export interface OAuthAccountSummary { id: string; alias?: string; email?: string; active: boolean; needsReauth?: boolean; expiresAt?: number }
+export interface OAuthAccountSummary {
+  id: string;
+  alias?: string;
+  email?: string;
+  active: boolean;
+  needsReauth?: boolean;
+  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).
+   *
+   * 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
+   * 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`.
+   */
+  plan: string | null;
+}
 
-export function getLoginStatus(provider: string): { loggedIn: boolean; email?: string; source?: OAuthCredentials["source"]; error?: string; done: boolean; activeAccountId?: string; accounts?: OAuthAccountSummary[] } {
+/**
+ * Token-safe login state for one provider.
+ *
+ * `maskEmails` is an explicit boolean rather than a config read (#3859). This module must not
+ * acquire a dependency on config I/O to answer a redaction question: the caller already holds
+ * the config at its request boundary and resolves the policy there with `emailMaskingEnabled`.
+ * The default masks, so every existing caller keeps today's behaviour.
+ */
+export function getLoginStatus(provider: string, maskEmails = true): { loggedIn: boolean; email?: string; source?: OAuthCredentials["source"]; error?: string; done: boolean; activeAccountId?: string; accounts?: OAuthAccountSummary[] } {
   const cred = getCredential(provider);
   const st = loginState.get(provider);
   const set = getAccountSet(provider);
   const accounts: OAuthAccountSummary[] | undefined = set?.accounts.map(a => ({
     id: a.id,
     ...(a.alias ? { alias: a.alias } : {}),
-    email: maskEmail(a.credential.email) ?? undefined,
+    email: projectEmail(a.credential.email, maskEmails) ?? undefined,
     active: a.id === set.activeAccountId,
     ...(a.needsReauth ? { needsReauth: true } : {}),
     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,
   }));
 
   // A stored credential counts as "logged in" when it exists and is not marked for
@@ -1805,7 +1840,7 @@ export function getLoginStatus(provider: string): { loggedIn: boolean; email?: s
     .find(a => a.id === set.activeAccountId)?.needsReauth === true;
   return {
     loggedIn: !!cred && !activeNeedsReauth,
-    email: maskEmail(cred?.email) ?? undefined,
+    email: projectEmail(cred?.email, maskEmails) ?? undefined,
     source: cred?.source,
     error: st?.error,
     done: st?.done ?? false,
@@ -1813,10 +1848,13 @@ export function getLoginStatus(provider: string): { loggedIn: boolean; email?: s
   };
 }
 
-/** Token-safe per-provider login state for the CLI `ocx status` logins section (no tokens, masked email). */
-export function oauthLoginSummary(): Array<{ provider: string; loggedIn: boolean; email?: string }> {
+/**
+ * Token-safe per-provider login state for the CLI `ocx status` logins section. Never tokens; the
+ * email follows the operator's `privacy.maskEmails` policy, masked by default (#3859).
+ */
+export function oauthLoginSummary(maskEmails = true): Array<{ provider: string; loggedIn: boolean; email?: string }> {
   return listOAuthProviders().map(provider => {
-    const status = getLoginStatus(provider);
+    const status = getLoginStatus(provider, maskEmails);
     return { provider, loggedIn: status.loggedIn, ...(status.email ? { email: status.email } : {}) };
   });
 }

package/src/oauth/token-guardian.ts

@@ -211,21 +211,30 @@ export async function guardianSweep(nowMs: number = Date.now()): Promise<Guardia
       if (!cred) continue;
       const needsRefresh = cred.expiresAt <= nowMs + horizonMs;
       const needsWarmup = opts.codexWarmupEnabled
+        && !record.codexValidationPending
         && (record.lastCodexValidatedAt === undefined || nowMs - record.lastCodexValidatedAt > opts.codexWarmupMaxAgeSeconds * 1000);
       if (!needsRefresh && !needsWarmup) continue;
       const key = `codex:${id}`;
       if (inBackoff(key, nowMs)) { result.skippedBackoff.push(key); continue; }
+      // The generation this sweep is acting on. A successful refresh commits a new one, and a
+      // failure that follows belongs to THAT credential, so the fence has to move with it.
+      let observedGeneration = record.generation;
       tasks.push(async () => {
+        let warmupGeneration: number | undefined;
         try {
           const token = await getValidCodexToken(id);
+          observedGeneration = token.generation;
           if (needsRefresh) result.refreshed.push(key);
-          if (needsWarmup) {
+          const current = readCodexAccountRecord(id);
+          if (needsWarmup && current?.credential && current.deletedAt == null
+            && !current.codexValidationPending && current.generation === token.generation) {
+            warmupGeneration = token.generation;
             await warmCodexAccount({
               accessToken: token.accessToken,
               chatgptAccountId: token.chatgptAccountId,
               model: opts.codexWarmupModel,
             });
-            markCodexAccountValidated(id, Date.now());
+            markCodexAccountValidated(id, Date.now(), token.generation);
             result.warmed.push(key);
           }
           backoff.delete(key);
@@ -235,11 +244,28 @@ export async function guardianSweep(nowMs: number = Date.now()): Promise<Guardia
             result.skippedBackoff.push(key);
             return;
           }
-          const permanent = err instanceof TokenRefreshError && (err.reason === "revoked" || err.reason === "expired");
-          if (needsWarmup && !(err instanceof TokenRefreshError)) {
-            markCodexAccountValidationFailed(id, codexWarmupFailureReason(err));
+          const terminal = err instanceof TokenRefreshError && (err.reason === "revoked" || err.reason === "expired")
+            ? err
+            : undefined;
+          if (terminal) {
+            // A revoked or expired refresh grant is the strongest terminal evidence there is, and
+            // it used to be the one class that never reached the record: the persisted-verdict
+            // branch below requires `needsWarmup`, which is false in the default configuration,
+            // and additionally excluded every TokenRefreshError. The verdict landed only in the
+            // in-memory backoff map, which no health surface reads and no restart survives, so the
+            // account kept its login-time "ok" while every request with it 401'd (#4120).
+            markCodexAccountValidationFailed(id, `refresh_${terminal.reason}`, {
+              expectedGeneration: observedGeneration,
+              terminal: true,
+            });
+          } else if (warmupGeneration !== undefined && !(err instanceof TokenRefreshError)) {
+            // warmupGeneration is set only once the warmup actually started against a record
+            // still at the token's generation, so it is a tighter fence than the pre-sweep read.
+            markCodexAccountValidationFailed(id, codexWarmupFailureReason(err), {
+              expectedGeneration: warmupGeneration,
+            });
           }
-          recordFailure(key, nowMs, opts.backoffBaseSeconds, opts.backoffMaxSeconds, permanent, writerGeneration);
+          recordFailure(key, nowMs, opts.backoffBaseSeconds, opts.backoffMaxSeconds, terminal !== undefined, writerGeneration);
           result.failed.push(key);
         }
       });

package/src/providers/google-ai-studio-model-discovery.ts

@@ -0,0 +1,74 @@
+import {
+  extractModelEnvelopeRows,
+  isValidModelDiscoveryModelId,
+  type ProviderModelItemsResult,
+  type ProviderModelsApiItem,
+} from "./model-discovery";
+
+const GOOGLE_MODEL_PREFIX = "models/";
+const MAX_GENERATION_METHODS = 32;
+const MAX_GENERATION_METHOD_LENGTH = 64;
+
+/** Returns the value if it is a positive safe integer; otherwise undefined. */
+function positiveSafeInteger(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0
+    ? value
+    : undefined;
+}
+
+/**
+ * Extracts and normalizes supported model items from a Google AI Studio
+ * /v1beta/models response payload.
+ *
+ * Validates the native models[] envelope, strips the 'models/' prefix, filters
+ * to rows supporting 'generateContent', maps input/output token limits, and
+ * resiliently skips toxic or malformed individual rows.
+ */
+export function extractGoogleAiStudioModelItems(
+  value: unknown,
+  maxModels: number,
+): ProviderModelItemsResult {
+  const envelope = extractModelEnvelopeRows(value, maxModels, ["models"]);
+  if (!envelope.ok) return envelope;
+
+  const items: ProviderModelsApiItem[] = [];
+  const seen = new Set<string>();
+  for (const raw of envelope.rows) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+      continue;
+    }
+    const name = Reflect.get(raw, "name");
+    const generationMethods = Reflect.get(raw, "supportedGenerationMethods");
+    if (!isValidModelDiscoveryModelId(name)) {
+      continue;
+    }
+    if (generationMethods === undefined) continue;
+    if (
+      !Array.isArray(generationMethods)
+      || generationMethods.length > MAX_GENERATION_METHODS
+      || generationMethods.some(method => typeof method !== "string" || method.length > MAX_GENERATION_METHOD_LENGTH)
+    ) {
+      continue;
+    }
+    if (!generationMethods.includes("generateContent")) continue;
+
+    const id = name.startsWith(GOOGLE_MODEL_PREFIX)
+      ? name.slice(GOOGLE_MODEL_PREFIX.length)
+      : name;
+    if (!isValidModelDiscoveryModelId(id) || seen.has(id)) continue;
+    seen.add(id);
+
+    const inputTokenLimit = positiveSafeInteger(Reflect.get(raw, "inputTokenLimit"));
+    const outputTokenLimit = positiveSafeInteger(Reflect.get(raw, "outputTokenLimit"));
+    items.push({
+      id,
+      owned_by: "google",
+      ...(inputTokenLimit !== undefined
+        ? { context_length: inputTokenLimit, max_input_tokens: inputTokenLimit }
+        : {}),
+      ...(outputTokenLimit !== undefined ? { max_output_tokens: outputTokenLimit } : {}),
+    });
+  }
+  return { ok: true, items, rawCount: envelope.rows.length };
+}
+

package/src/providers/opencode-go-transport.ts

@@ -22,7 +22,15 @@ export function deriveOpenCodeGoSessionId(sessionLane: string): string {
   return `ocx_${digest}`;
 }
 
-/** Add per-conversation Go affinity only to the canonical fixed-key destination. */
+/**
+ * Add Go affinity only to the canonical fixed-key destination.
+ *
+ * Callers on the request path resolve the lane with `getOrAllocateRequestSessionLane`, which returns
+ * real conversation identity when the client supplied it and a per-request value otherwise, so a
+ * request reaching this helper from the proxy always carries a lane. The `!sessionLane` guard stays
+ * for direct callers that have no request context; it is not a per-request identity of its own, and
+ * minting one here would hand each retry a different value.
+ */
 export function resolveOpenCodeGoTransport<T extends OcxProviderConfig>(
   provider: T,
   sessionLane: string | undefined,

package/src/providers/opencode-zen-rate-limit.ts

@@ -7,6 +7,11 @@
  * bodies and may omit `Retry-After` / `X-RateLimit-*`; when those headers are
  * present they still take precedence. Distinct from the keyless desktop
  * ~200 requests / 5h quota documented on `opencode-free`.
+ *
+ * The same module also owns the keyless free-tier admission explanation (#4121):
+ * Zen rejects a request that carries no `x-opencode-session` header with
+ * `MissingSessionID` / "OpenCode's free tier can only be used in OpenCode".
+ * opencodex does not synthesize that header — see {@link enrichOpenCodeZenFreeTierMessage}.
  */
 import { validateClientRetryAfterHeader } from "../lib/retry-after";
 import { registryEntryForProviderDestination } from "./registry";
@@ -100,3 +105,73 @@ export function enrichOpenCodeZenRateLimitMessage(
     + paceHint
   );
 }
+
+/**
+ * Zen's keyless free tier admits only OpenCode's own client. A request without an
+ * `x-opencode-session` header is refused with error type `MissingSessionID` and the
+ * message "OpenCode's free tier can only be used in OpenCode" (#4121).
+ *
+ * Presence of the header is the whole gate — any value clears it — so opencodex could
+ * pass by minting one. It does not. Fabricating a session identifier and a versioned
+ * `opencode/<version>` User-Agent is a claim to *be* the OpenCode client, and no upstream
+ * contract authorizes a third-party agent to make it; an HTTP 200 obtained that way is a
+ * bypassed admission check, not permission. Until OpenCode publishes a third-party
+ * integration path for this exact keyless tier, the supported route is the keyed
+ * `opencode-zen` provider.
+ *
+ * Two markers are matched because the two request surfaces expose different parts of the
+ * upstream envelope: the Responses path forwards the bounded raw body (which carries the
+ * `MissingSessionID` type), while the native Chat path forwards only the parsed message.
+ */
+const OPENCODE_ZEN_FREE_TIER_LOCK_IN = /MissingSessionID|free tier can only be used in OpenCode/i;
+
+/** Idempotence marker — the appended guidance must not stack across enrichment layers. */
+const FREE_TIER_ENRICHMENT_MARKER = "does not send a fabricated OpenCode session header";
+
+/** True when an upstream error body is Zen's keyless free-tier admission refusal. */
+export function isOpenCodeZenFreeTierLockIn(message: string, upstreamErrorType?: string | null): boolean {
+  if (upstreamErrorType && OPENCODE_ZEN_FREE_TIER_LOCK_IN.test(upstreamErrorType)) return true;
+  return OPENCODE_ZEN_FREE_TIER_LOCK_IN.test(message);
+}
+
+/**
+ * Replace a raw `MissingSessionID` passthrough with an explanation of the upstream
+ * restriction and the supported alternative. No-op for every other provider and every
+ * other error, and idempotent so layered enrichment cannot append it twice.
+ */
+export function enrichOpenCodeZenFreeTierMessage(
+  message: string,
+  opts: {
+    providerName?: string;
+    baseUrl?: string;
+    adapter?: string;
+    /** Upstream `error.type`, when the caller parsed one out of the envelope. */
+    upstreamErrorType?: string | null;
+  },
+): string {
+  if (message.includes(FREE_TIER_ENRICHMENT_MARKER)) return message;
+  if (!isOpenCodeZenFreeTierLockIn(message, opts.upstreamErrorType)) return message;
+  if (!isOpenCodeZenRateLimitProvider(opts)) return message;
+  return (
+    `${message}`
+    + " OpenCode Zen's keyless free tier admits only OpenCode's own client: it refuses any"
+    + " request that arrives without an x-opencode-session header."
+    + ` opencodex ${FREE_TIER_ENRICHMENT_MARKER}, because presenting itself as the OpenCode`
+    + " client is a claim no upstream contract supports."
+    + " Use the keyed opencode-zen provider with an OpenCode Zen API key"
+    + " (https://opencode.ai/auth), or route this model through another provider."
+    + " Upstream terms: https://opencode.ai/docs/zen/."
+  );
+}
+
+/**
+ * Single entry point for Zen upstream-error guidance on the Responses wire: short-window
+ * rate limits first, then the keyless free-tier admission refusal. Each layer is a no-op
+ * outside its own case, so the composition is safe for every other upstream failure.
+ */
+export function enrichOpenCodeZenUpstreamMessage(
+  message: string,
+  opts: Parameters<typeof enrichOpenCodeZenRateLimitMessage>[1] & { upstreamErrorType?: string | null },
+): string {
+  return enrichOpenCodeZenFreeTierMessage(enrichOpenCodeZenRateLimitMessage(message, opts), opts);
+}

package/src/providers/quota.ts

@@ -1398,6 +1398,21 @@ function parseClaudeLimit(value: unknown): { label: string; percent: number; res
 /** Claude's OAuth usage endpoint, probed with ONE account's own bearer token. */
 const anthropicUsageInflight = new Map<string, Promise<ProviderQuota | null>>();
 
+/**
+ * Anthropic per-credential usage.
+ *
+ * This endpoint reports quota only. Its body carries `five_hour`, `seven_day`, the
+ * model-scoped weekly buckets (`seven_day_fable`/`_opus`/`_sonnet`) and a `limits` array,
+ * and **no subscription or tier field** — nor does the OAuth token response, which yields only
+ * `account.uuid` and `account.email_address` (`src/oauth/anthropic.ts`). That is why
+ * `OAuthAccountSummary.plan` is `null` for Anthropic rather than populated here (#3777); it is
+ * a missing upstream field, not an unfinished mapping.
+ *
+ * A tier must not be inferred from what is here. Percentages are normalized per account, so a
+ * Max x5 seat at 50% is byte-identical to a Max x20 seat at 50%, and the presence of a
+ * model-scoped window tracks entitlement rather than seat size. Populate `plan` only when
+ * upstream returns the tier itself.
+ */
 async function fetchAnthropicUsageQuota(accessToken: string): Promise<ProviderQuota | null> {
   const joinable = anthropicUsageInflight.get(accessToken);
   if (joinable) return joinable;
@@ -2891,7 +2906,11 @@ function keyQuotaReaderForProvider(name: string, provider: OcxProviderConfig): K
   if (name === "deepseek" && isCanonicalDeepSeekBaseUrl(provider.baseUrl)) return fetchDeepSeekQuota;
   if (name === "cline-pass" && isCanonicalClineBaseUrl(provider.baseUrl)) return fetchClineQuota;
   if (isCanonicalOllamaCloudBaseUrl(provider.baseUrl ?? getProviderRegistryEntry(name)?.baseUrl)) return fetchOllamaCloudQuota;
-  if (["zai", "glm", "glm-cn", "zhipu-bigmodel-coding"].includes(name) && isCanonicalZaiBaseUrl(provider.baseUrl)) return fetchZaiQuota;
+  // #4201: the Responses preset is the same domestic GLM Coding Plan subscription on the OpenAI
+  // Responses wire, so it reads the same monitor endpoint. Eligibility stays a name list AND the
+  // canonical-URL guard: the guard is what keeps BigModel's bare-key Authorization from reaching a
+  // lookalike host, so a same-named custom destination still dispatches nothing.
+  if (["zai", "glm", "glm-cn", "zhipu-bigmodel-coding", "zhipu-bigmodel-responses"].includes(name) && isCanonicalZaiBaseUrl(provider.baseUrl)) return fetchZaiQuota;
   if (["minimax", "minimax-cn"].includes(name) && isCanonicalMinimaxBaseUrl(provider.baseUrl)) return fetchMinimaxQuota;
   if (name === "moonshot" && isCanonicalMoonshotBaseUrl(provider.baseUrl)) return fetchMoonshotQuota;
   if (name === "venice" && isCanonicalVeniceBaseUrl(provider.baseUrl)) return fetchVeniceQuota;

package/src/providers/registry.ts

@@ -2640,6 +2640,23 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
   // Narrowed carry of #3641: the official Codex example declares a local static catalog,
   // not an HTTP /models contract. Keep Responses separate from the Chat endpoint above.
   // Source: https://docs.bigmodel.cn/cn/coding-plan/tool/codex.md (checked 2026-09-07).
+  //
+  // #4201 completes the roster. The `models.json` example on that Codex page is a *starter
+  // catalog*, not the set of models the endpoint serves, and reading it as the latter is what
+  // left Flash off a subscription that sells it. Three upstream pages say so directly, all
+  // checked 2026-09-11:
+  //   - coding-plan/latest-model.md pins Codex to THIS baseUrl
+  //     (`Codex：https://open.bigmodel.cn/api/v1`) and opens with GLM Coding Plan supporting
+  //     GLM-5.3 and GLM-5.3-Flash for every tier (Max & Pro & Lite), then treats
+  //     `glm-5.3-flash` as an already-callable id in that same tool.
+  //   - coding-plan/overview.md: every plan supports GLM-5.3 and GLM-5.3-Flash, and calls to
+  //     GLM-5-Turbo are auto-switched to GLM-5.3-Flash. Turbo below is therefore an alias of
+  //     the very model this row omitted, which is the clearest statement that the endpoint
+  //     serves Flash: it was already serving it under another name.
+  //   - guide/models/vlm/glm-5.3-flash.md: native multimodal input, 1M context, and text
+  //     parameters explicitly "consistent with GLM-5.3".
+  // No authenticated /models probe is implied by any of this, so `liveModels` and
+  // `apiKeyValidation` below are deliberately unchanged.
   {
     id: "zhipu-bigmodel-responses",
     label: "Zhipu AI — BigModel Coding Plan (Responses)",
@@ -2648,22 +2665,34 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     authKind: "key",
     dashboardUrl: "https://bigmodel.cn/console/usercenter/apikeys",
     defaultModel: "glm-5.3",
-    models: ["glm-5.3", "glm-5-turbo"],
+    models: ["glm-5.3", "glm-5.3-flash", "glm-5-turbo"],
     liveModels: false,
     // The local Codex catalog does not establish an authenticated HTTP /models contract.
     apiKeyValidation: "unknown",
     jawcodeBundle: "zai",
     // A pre-existing same-named custom provider must retain its destination and key boundary.
     preserveCustomDestination: true,
-    modelContextWindows: { "glm-5.3": 1_048_576, "glm-5-turbo": 204_800 },
-    modelInputModalities: { "glm-5.3": ["text"], "glm-5-turbo": ["text"] },
+    // Flash tracks its 5.3 sibling on this row rather than the Chat row's 1_000_000. Both
+    // models are documented as "1M", and this preset expresses that family's 1M the way
+    // BigModel's own Codex declaration does. Splitting the two would leave one preset
+    // claiming two different sizes for one documented window.
+    modelContextWindows: { "glm-5.3": 1_048_576, "glm-5.3-flash": 1_048_576, "glm-5-turbo": 204_800 },
+    // Flash is the only row here that can actually see an image. Its siblings are declared
+    // text-only and get `image` back from the vision sidecar at catalog-build time; declaring
+    // Flash text-only would route a native VLM's pictures through a describe-it-first detour
+    // and hand the model prose about an image it could have read (same defect
+    // ZAI_GLM_5X_SIDECAR_VISION_MODELS exists to prevent on the Chat rows).
+    modelInputModalities: { "glm-5.3": ["text"], "glm-5.3-flash": ["text", "image"], "glm-5-turbo": ["text"] },
     modelReasoningEfforts: {
       "glm-5.3": ZAI_GLM_53_REASONING_EFFORTS,
+      // Same three effective tiers: upstream documents Flash's text parameters as identical
+      // to GLM-5.3, and the Codex effort table folds every inbound value into low/high/max.
+      "glm-5.3-flash": ZAI_GLM_53_REASONING_EFFORTS,
       // Explicitly empty: Turbo must not inherit the generic selectable effort ladder.
       "glm-5-turbo": [],
     },
-    modelDefaultReasoningEfforts: { "glm-5.3": "max", "glm-5-turbo": "max" },
-    modelSupportsReasoningSummaries: { "glm-5.3": true, "glm-5-turbo": true },
+    modelDefaultReasoningEfforts: { "glm-5.3": "max", "glm-5.3-flash": "max", "glm-5-turbo": "max" },
+    modelSupportsReasoningSummaries: { "glm-5.3": true, "glm-5.3-flash": true, "glm-5-turbo": true },
     // Responses replay uses this provider-level flag, not the Chat-path model list.
     preserveResponsesReasoningContent: true,
     note: "Domestic BigModel Coding Plan Responses endpoint; static model roster",
@@ -3018,7 +3047,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     keyOptional: true,
     featured: true,
     liveModels: true,
-    note: "No key needed — public desktop tier. OpenCode currently advertises about 200 Big Pickle/free-model requests per 5 hours. The same Zen gateway can also short-window rate-limit free models at roughly 15-20 requests/minute, and may return generic 429s without Retry-After (opencodex synthesizes backoff only when that header is omitted). Free models are discovered live from Zen. Data use: per OpenCode's Zen docs (https://opencode.ai/docs/zen/), prompts sent to free models may be retained and used for training/improvement — do not send confidential material through this provider.",
+    note: "No key needed, but OpenCode now gates this tier to its own client: Zen refuses any request that arrives without an x-opencode-session header (error type MissingSessionID, \"OpenCode's free tier can only be used in OpenCode\"). opencodex does not mint that header or claim an OpenCode client identity, because no upstream contract authorizes a third-party agent to present itself as OpenCode. Until OpenCode publishes a third-party integration path for the keyless tier, use the keyed opencode-zen provider instead (https://opencode.ai/auth). Quota figures for when the tier admitted a request: OpenCode advertises about 200 Big Pickle/free-model requests per 5 hours, and the same Zen gateway can short-window rate-limit free models at roughly 15-20 requests/minute, and may return generic 429s without Retry-After (opencodex synthesizes backoff only when that header is omitted). Free models are discovered live from Zen. Data use: per OpenCode's Zen docs (https://opencode.ai/docs/zen/), prompts sent to free models may be retained and used for training/improvement — do not send confidential material through this provider.",
     dashboardUrl: "https://opencode.ai",
     staticHeaders: {
       // Zen answers a bare runtime User-Agent (Bun/x.y.z) more aggressively than a client