opencode-anthropic-fix 0.6.0 → 2.0.0

package/lib/account-state.mjs

@@ -1,3 +1,51 @@
+import { OAUTH_EXPIRY_SKEW_SECONDS } from "./oauth-constants.mjs";
+
+/** The attested 30-second expiry skew, in milliseconds. @see docs/oauth-2.1.280-contract.md §3 */
+export const TOKEN_EXPIRY_SKEW_MS = OAUTH_EXPIRY_SKEW_SECONDS * 1000;
+
+/**
+ * The single expiry predicate. Every "is this access token still usable?"
+ * question in this repository routes through here.
+ *
+ * ATTESTED: §13.8 (byte 4418342) records `expiry skew (seconds): 30`. A token is
+ * therefore treated as expired 30 s before its nominal expiry, so a request is
+ * never sent with a credential that dies in flight.
+ *
+ * WHY leadMs IS A FLOOR AND NOT AN ADDEND. Some callers deliberately refresh far
+ * ahead of expiry — a foreground buffer, an idle-refresh window. Adding the skew
+ * to those would silently retune them; dropping the skew for them would leave a
+ * site that can still call a token valid seconds before it dies. Taking the
+ * larger of the two keeps every tuned lead time exactly as it was while
+ * guaranteeing the 30 s floor everywhere.
+ *
+ * A missing or non-numeric `expires` is EXPIRED, not valid: an unknown expiry is
+ * not evidence of freshness, and the alternative is sending a dead token.
+ *
+ * @param {number | null | undefined} expires - Absolute expiry, ms since epoch
+ * @param {number} [leadMs=0] - Extra lead time this caller wants
+ * @param {number} [now=Date.now()] - Injectable clock for tests
+ * @returns {boolean}
+ * @see docs/oauth-2.1.280-contract.md §3
+ */
+export function isTokenExpired(expires, leadMs = 0, now = Date.now()) {
+  if (typeof expires !== "number" || !Number.isFinite(expires)) return true;
+  const lead = Math.max(Number.isFinite(leadMs) ? leadMs : 0, TOKEN_EXPIRY_SKEW_MS);
+  return now >= expires - lead;
+}
+
+/**
+ * Convenience inverse of {@link isTokenExpired}. Exists so call sites read as
+ * the question they are asking instead of as a negation.
+ *
+ * @param {number | null | undefined} expires
+ * @param {number} [leadMs=0]
+ * @param {number} [now=Date.now()]
+ * @returns {boolean}
+ */
+export function isTokenUsable(expires, leadMs = 0, now = Date.now()) {
+  return !isTokenExpired(expires, leadMs, now);
+}
+
 /**
  * @typedef {import('./storage.mjs').AccountMetadata} AccountMetadata
  * @typedef {import('./storage.mjs').AccountStorage} AccountStorage

package/lib/accounts.mjs

@@ -1,8 +1,10 @@
 import { createHash } from "node:crypto";
+import { isTokenUsable } from "./account-state.mjs";
 import { loadAccounts, saveAccounts, createDefaultStats } from "./storage.mjs";
 import { HealthScoreTracker, TokenBucketTracker, selectAccount } from "./rotation.mjs";
 import { calculateBackoffMs } from "./backoff.mjs";
 import { readCCCredentials } from "./cc-credentials.mjs";
+import { HEADLESS_REFRESH_TOKEN_VAR, resolveHeadlessLogin } from "./oauth-env.mjs";
 
 /** QA fix M12: hash token fragment instead of leaking raw prefix */
 function hashTokenFragment(token) {
@@ -22,7 +24,7 @@ function hashTokenFragment(token) {
  */
 
 /**
- * @typedef {'oauth' | 'cc-keychain' | 'cc-file'} AccountSource
+ * @typedef {'oauth' | 'cc-keychain' | 'cc-file' | 'env'} AccountSource
  */
 
 /**
@@ -42,7 +44,9 @@ function hashTokenFragment(token) {
  * @property {number | null} lastFailureTime
  * @property {string} [lastSwitchReason]
  * @property {AccountStats} stats
- * @property {AccountSource} [source] - Origin of the account. CC accounts must not enter OAuth HTTP refresh.
+ * @property {AccountSource} [source] - Origin of the account. CC accounts must not enter OAuth HTTP refresh. env accounts are process-lifetime only and are never persisted.
+ * @property {string} [clientId] - OAuth client id to refresh with. Only set for `env` accounts.
+ * @property {string[]} [scopes] - Scopes the operator declared for an `env` account. In-memory only.
  */
 
 const MAX_ACCOUNTS = 10;
@@ -58,6 +62,38 @@ const RATE_LIMIT_KEY_FAST = "anthropic:fast";
 
 export { RATE_LIMIT_KEY, RATE_LIMIT_KEY_FAST };
 
+/** One-shot latch so a rotating env credential warns once per process, not once per refresh. */
+let ephemeralRotationWarned = false;
+
+/**
+ * Warn when the server rotates the refresh token of an `env`-sourced account.
+ *
+ * An env credential is process-lifetime only by design, so its successor is
+ * written nowhere. Left silent, the next process start would re-seed the
+ * retired token from the environment and fail with no explanation. This is the
+ * one place that can see both the account's origin and the server's response.
+ *
+ * @param {{ source?: AccountSource, refreshToken?: string }} account
+ * @param {string | undefined} rotatedToken - `refresh_token` from the token response
+ * @returns {boolean} whether a warning was emitted
+ * @see docs/oauth-2.1.280-contract.md §5.2
+ */
+export function warnOnEphemeralTokenRotation(account, rotatedToken) {
+  if (account?.source !== "env") return false;
+  if (!rotatedToken || rotatedToken === account.refreshToken) return false;
+  if (ephemeralRotationWarned) return false;
+  ephemeralRotationWarned = true;
+  console.warn(
+    `[anthropic-auth] the server rotated the refresh token for the ${HEADLESS_REFRESH_TOKEN_VAR} account. The new token is held in memory only and will be lost when this process exits; update the environment variable to keep it.`,
+  );
+  return true;
+}
+
+/** Reset the one-shot rotation warning. Exported for tests only. */
+export function resetEphemeralRotationWarning() {
+  ephemeralRotationWarned = false;
+}
+
 /**
  * @typedef {object} StatsDelta
  * @property {number} requests
@@ -103,9 +139,10 @@ export class AccountManager {
    * Load accounts from disk, optionally merging with an OpenCode auth fallback.
    * @param {AnthropicAuthConfig} config
    * @param {{refresh: string, access?: string, expires?: number} | null} [authFallback]
+   * @param {Record<string, string | undefined>} [env]
    * @returns {Promise<AccountManager>}
    */
-  static async load(config, authFallback) {
+  static async load(config, authFallback, env = process.env) {
     const manager = new AccountManager(config);
     const stored = await loadAccounts();
 
@@ -144,7 +181,7 @@ export class AccountManager {
           const fallbackHasAccess = typeof authFallback.access === "string" && authFallback.access.length > 0;
           const fallbackExpires = typeof authFallback.expires === "number" ? authFallback.expires : 0;
           const matchExpires = typeof match.expires === "number" ? match.expires : 0;
-          const fallbackLooksFresh = fallbackHasAccess && fallbackExpires > Date.now();
+          const fallbackLooksFresh = fallbackHasAccess && isTokenUsable(fallbackExpires);
           const shouldAdoptFallback =
             fallbackLooksFresh && (!match.access || !match.expires || fallbackExpires > matchExpires);
           if (shouldAdoptFallback) {
@@ -158,6 +195,7 @@ export class AccountManager {
       // Merge CC credentials if enabled
       manager.#mergeCC(config);
 
+      manager.#seedEnvAccount(env);
       return manager;
     }
 
@@ -190,6 +228,7 @@ export class AccountManager {
     // Merge CC credentials if enabled
     manager.#mergeCC(config);
 
+    manager.#seedEnvAccount(env);
     return manager;
   }
 
@@ -270,6 +309,98 @@ export class AccountManager {
     }
   }
 
+  /**
+   * Seed a process-lifetime account from CLAUDE_CODE_OAUTH_REFRESH_TOKEN.
+   *
+   * The seeded account is marked `source: "env"` and is filtered out of every
+   * write to `anthropic-accounts.json`: persisting a credential the operator
+   * injected transiently would turn an environment variable into a stored
+   * secret the user never asked for.
+   *
+   * It is appended LAST so the positional mapping between `stored.accounts[i]`
+   * and `this.#accounts[i]` that `syncActiveIndexFromDisk` relies on still holds
+   * for every disk-backed account.
+   *
+   * A malformed declaration throws rather than degrading to disk accounts: an
+   * operator who set the variable meant to use it, and silently ignoring it
+   * would run the wrong credential.
+   *
+   * @param {Record<string, string | undefined> | undefined} env
+   */
+  #seedEnvAccount(env) {
+    const headless = resolveHeadlessLogin(env);
+    if (!headless) return;
+
+    // Already managed on disk. Leave the stored account untouched — re-tagging
+    // it `source: "env"` would make the next save silently delete it.
+    if (this.#accounts.some((acc) => acc.refreshToken === headless.refreshToken)) return;
+
+    if (this.#accounts.length >= MAX_ACCOUNTS) {
+      console.warn(
+        `[anthropic-auth] ${HEADLESS_REFRESH_TOKEN_VAR} was ignored: the account pool is already at its maximum of ${MAX_ACCOUNTS}.`,
+      );
+      return;
+    }
+
+    // The id is derived from the token hash alone and is therefore stable across
+    // restarts: a timestamp would add nothing the hash does not and would break
+    // id-keyed correlation between runs.
+    const now = Date.now();
+    this.#accounts.push({
+      id: `env:${hashTokenFragment(headless.refreshToken)}`,
+      index: this.#accounts.length,
+      email: undefined,
+      refreshToken: headless.refreshToken,
+      access: undefined,
+      expires: undefined,
+      tokenUpdatedAt: now,
+      addedAt: now,
+      lastUsed: 0,
+      enabled: true,
+      rateLimitResetTimes: {},
+      consecutiveFailures: 0,
+      lastFailureTime: null,
+      lastSwitchReason: "env",
+      stats: createDefaultStats(now),
+      source: "env",
+      clientId: headless.clientId,
+      scopes: headless.scopes,
+    });
+
+    if (this.#currentIndex < 0) this.#currentIndex = this.#accounts.length - 1;
+  }
+
+  /**
+   * Accounts that may be written to disk. `env` accounts are excluded by design.
+   * @returns {ManagedAccount[]}
+   */
+  #persistableAccounts() {
+    return this.#accounts.filter((acc) => acc.source !== "env");
+  }
+
+  /**
+   * Discard pending stats deltas belonging to `env` accounts.
+   *
+   * A delta is the amount to add to the value ON DISK; `recordUsage` has already
+   * applied the same increment to the in-memory record, which is why the normal
+   * save path rebuilds `mergedStats` from disk plus delta rather than from
+   * `acc.stats`. An env account has no disk row, so its in-memory stats are
+   * already the whole truth and re-applying the delta would double-count.
+   *
+   * The deltas must still be dropped: `saveToDisk` can return before the capture
+   * point, and a key that is never captured is never cleared, so env deltas would
+   * otherwise accumulate for the life of the process.
+   *
+   * @param {Set<string>} [keys] - Restrict to these delta keys; all when omitted.
+   */
+  #drainEnvStatsDeltas(keys) {
+    for (const acc of this.#accounts) {
+      if (acc.source !== "env") continue;
+      if (keys && !keys.has(acc.id)) continue;
+      this.#statsDeltas.delete(acc.id);
+    }
+  }
+
   /**
    * Get the number of enabled accounts.
    * @returns {number}
@@ -717,10 +848,26 @@ export class AccountManager {
       return null;
     };
 
+    // `env` accounts never reach disk. The persisted activeIndex is resolved by
+    // account id rather than by position, so it stays correct no matter where an
+    // env account sits in the in-memory list.
+    const persistable = this.#persistableAccounts();
+    const currentAccount = this.#currentIndex >= 0 ? this.#accounts[this.#currentIndex] : undefined;
+    const persistedActiveIndex = currentAccount ? persistable.findIndex((acc) => acc.id === currentAccount.id) : -1;
+
+    // Nothing to persist and nothing on disk: do not create an empty store.
+    // Writing `accounts: []` here would make the next load take the
+    // "disk is authoritative" branch and permanently refuse to bootstrap from an
+    // auth fallback — a process-lifetime env credential must not have that effect.
+    if (persistable.length === 0 && diskAccountsById === null) {
+      this.#drainEnvStatsDeltas();
+      return;
+    }
+
     /** @type {AccountStorage} */
     const storage = {
       version: 1,
-      accounts: this.#accounts.map((acc) => {
+      accounts: persistable.map((acc) => {
         const delta = this.#statsDeltas.get(acc.id);
         let mergedStats = acc.stats;
         const diskAcc = findDiskAccount(acc);
@@ -794,7 +941,7 @@ export class AccountManager {
           source: acc.source,
         };
       }),
-      activeIndex: Math.max(0, this.#currentIndex),
+      activeIndex: Math.max(0, persistedActiveIndex),
     };
 
     // QA fix H8: snapshot delta keys before the async write to avoid losing
@@ -809,6 +956,11 @@ export class AccountManager {
     const preloadedDiskData = diskAccountsById ? { version: 1, accounts: [...diskAccountsById.values()] } : null;
     await saveAccounts(storage, preloadedDiskData);
 
+    // Env accounts are absent from `storage`, so their deltas were never merged.
+    // Fold them into the in-memory record before the captured keys are dropped,
+    // otherwise every save silently discards an env account's usage.
+    this.#drainEnvStatsDeltas(capturedDeltaKeys);
+
     // Clear only the captured deltas; new ones added during await are preserved
     for (const key of capturedDeltaKeys) {
       this.#statsDeltas.delete(key);
@@ -833,9 +985,18 @@ export class AccountManager {
     const stored = await loadAccounts();
     if (!stored) return;
 
-    // Reconcile account list/enabled states with disk (CLI may add/remove/enable/disable)
-    const existingByTokenForSnapshot = new Map(this.#accounts.map((acc) => [acc.refreshToken, acc]));
-    const memSnapshot = this.#accounts.map((acc) => `${acc.id}:${acc.refreshToken}:${acc.enabled ? 1 : 0}`).join("|");
+    // Reconcile account list/enabled states with disk (CLI may add/remove/enable/disable).
+    // `env` accounts have no disk representation, so they are held aside and
+    // re-appended; comparing them against the disk snapshot would report a
+    // difference on every tick and rebuild the list forever.
+    // Captured before any rebuild: after the list is rebuilt, position is
+    // meaningless and only identity survives.
+    const currentBeforeSync = this.#currentIndex >= 0 ? this.#accounts[this.#currentIndex] : undefined;
+
+    const envAccounts = this.#accounts.filter((acc) => acc.source === "env");
+    const persistedMem = this.#persistableAccounts();
+    const existingByTokenForSnapshot = new Map(persistedMem.map((acc) => [acc.refreshToken, acc]));
+    const memSnapshot = persistedMem.map((acc) => `${acc.id}:${acc.refreshToken}:${acc.enabled ? 1 : 0}`).join("|");
 
     const diskSnapshot = stored.accounts
       .map((acc) => {
@@ -845,10 +1006,10 @@ export class AccountManager {
       .join("|");
 
     if (diskSnapshot !== memSnapshot) {
-      const existingById = new Map(this.#accounts.map((acc) => [acc.id, acc]));
-      const existingByToken = new Map(this.#accounts.map((acc) => [acc.refreshToken, acc]));
+      const existingById = new Map(persistedMem.map((acc) => [acc.id, acc]));
+      const existingByToken = new Map(persistedMem.map((acc) => [acc.refreshToken, acc]));
 
-      this.#accounts = stored.accounts.map((acc, index) => {
+      const rebuilt = stored.accounts.map((acc, index) => {
         const existing =
           (acc.id && existingById.get(acc.id)) || (!acc.id ? existingByToken.get(acc.refreshToken) : null);
         return {
@@ -871,6 +1032,17 @@ export class AccountManager {
         };
       });
 
+      // An env token that has since appeared on disk is no longer ephemeral:
+      // keeping both copies would give one credential two account entries that
+      // invalidate each other on the first refresh.
+      const rebuiltTokens = new Set(rebuilt.map((acc) => acc.refreshToken));
+      const survivingEnvAccounts = envAccounts.filter((acc) => !rebuiltTokens.has(acc.refreshToken));
+
+      this.#accounts = [...rebuilt, ...survivingEnvAccounts];
+      this.#accounts.forEach((acc, i) => {
+        acc.index = i;
+      });
+
       // Trackers are index-based; reset when account set/order changes.
       this.#healthTracker = new HealthScoreTracker(this.#config.health_score);
       this.#tokenTracker = new TokenBucketTracker(this.#config.token_bucket);
@@ -886,8 +1058,35 @@ export class AccountManager {
         this.#cursor = 0;
         return;
       }
+
+      // Re-anchor the selection by identity. Positions shift whenever disk gains
+      // or loses an account, so carrying the old index over silently switches the
+      // caller to a different credential.
+      const reanchored = currentBeforeSync ? this.#accounts.findIndex((acc) => acc.id === currentBeforeSync.id) : -1;
+      if (reanchored >= 0) {
+        this.#currentIndex = reanchored;
+        this.#cursor = reanchored;
+        // This is a BASELINE, not an override. The disk `activeIndex` remains
+        // authoritative for selection — that is the whole point of this method —
+        // so the handshake below still runs. Re-anchoring only decides where we
+        // stand if the handshake declines to move us (its target is disabled or
+        // absent); without it we would be left on whatever account happened to
+        // inherit our old numeric position.
+      } else if (this.#currentIndex >= this.#accounts.length) {
+        // The selected account is gone (a CLI logout-all can empty the disk list
+        // while an env account survives). Land on the last remaining account.
+        this.#currentIndex = this.#accounts.length - 1;
+        this.#cursor = this.#currentIndex;
+      }
     }
 
+    // `activeIndex` addresses the persisted list, which has no slot for an env
+    // account. When an env account is selected, `saveToDisk` necessarily wrote
+    // some other index, so honouring it here would deselect the env credential on
+    // the very next tick after every save.
+    const current = this.#currentIndex >= 0 ? this.#accounts[this.#currentIndex] : undefined;
+    if (current?.source === "env") return;
+
     const diskIndex = Math.min(stored.activeIndex, this.#accounts.length - 1);
     if (diskIndex >= 0 && diskIndex !== this.#currentIndex) {
       const diskAccount = stored.accounts[diskIndex];

package/lib/betas.mjs

@@ -0,0 +1,131 @@
+/**
+ * Host beta policy.
+ *
+ * Three things live here, and none of them is wire construction:
+ *  - `EXPERIMENTAL_BETA_FLAGS`: the betas the HOST treats as experimental, i.e.
+ *    the set it filters out when `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` is on;
+ *  - `BETA_SHORTCUTS`: CLI UX aliases for `/anthropic betas` and
+ *    `config.custom_betas`;
+ *  - `resolveBetaShortcut`: the resolver behind those aliases.
+ *
+ * The betas that actually go on the wire are the shared package's business
+ * (`lib/mimicry/wire-compat.mjs`); this module only decides what the plugin
+ * ADDS or SUPPRESSES on top of them.
+ *
+ * RECONCILIATION IS ENFORCED BY TEST, not by convention. Every literal header
+ * below is checked against the package's `BETA_REGISTRY_2_1_233` — the genuine
+ * client's own registry — by `lib/betas.test.mjs`, which fails on a stale date
+ * stamp and requires the host-only entries (the ones upstream has no registry
+ * slot for) to be enumerated and justified rather than merely accumulated. Add
+ * a beta here that upstream does not ship and the test will tell you to say why.
+ */
+
+/**
+ * Set of all known experimental/optional beta flags.
+ * Used to filter betas when CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.
+ * WARNING: this set intentionally overlaps with always-on betas - only use
+ * it with the disable-experimental guard, never unconditionally.
+ */
+export const EXPERIMENTAL_BETA_FLAGS = new Set([
+  "adaptive-thinking-2026-01-28",
+  "advanced-tool-use-2025-11-20",
+  "advisor-tool-2026-03-01",
+  "afk-mode-2026-01-31",
+  "cache-diagnosis-2026-04-07",
+  // CCR bring-your-own-cloud beta. Registered in the 2.1.154 binary's _W() table
+  // but not emitted on /v1/messages; kept here for the disable-experimental guard.
+  "ccr-byoc-2025-07-29",
+  "code-execution-2025-08-25",
+  "compact-2026-01-12",
+  "context-1m-2025-08-07",
+  "context-hint-2026-04-09",
+  "context-management-2025-06-27",
+  "environments-2025-11-01",
+  "extended-cache-ttl-2025-04-11",
+  // Refusal-fallback credit beta from the upstream Udd registry (CC 2.1.195).
+  // Opt-in/GrowthBook-gated; never auto-emitted on a default /v1/messages turn.
+  // Listed here for the disable-experimental guard + manual opt-in ONLY.
+  "fallback-credit-2026-06-01",
+  "fast-mode-2026-02-01",
+  "files-api-2025-04-14",
+  "interleaved-thinking-2025-05-14",
+  // Registered in the 2.1.154 binary's _W() table (mcp_servers label). Plugin
+  // proxies MCP tool calls inline and does not emit this on chat completions.
+  "mcp-servers-2025-12-04",
+  // Registered in CC v2.1.143 but NOT in real CC's always-on emission set
+  // (master registry only, not in the always-on subset). Likely GrowthBook-gated
+  // pending server rollout. Paired telemetry: tengu_mid_conv_system_fallback_retry.
+  "mid-conversation-system-2026-04-07",
+  "prompt-caching-scope-2026-01-05",
+  "redact-thinking-2026-02-12",
+  // Server-side refusal-fallback beta from the upstream Udd registry (CC 2.1.195).
+  // Opt-in/GrowthBook-gated; never auto-emitted on a default /v1/messages turn.
+  // Listed here for the disable-experimental guard + manual opt-in ONLY.
+  "server-side-fallback-2026-06-01",
+  "structured-outputs-2025-12-15",
+  // Revived in CC 2.1.159 as registry label `narration_summaries` (it was a dead
+  // slot from v2.1.90-2.1.154). Real CC emits it only when GrowthBook flag
+  // `pewter_owl_header` is on (default-off), first-party, and NOT in fast-mode.
+  // Listed here for the disable-guard + manual opt-in ONLY; never emitted always-on.
+  "summarize-connector-text-2026-03-13",
+  "task-budgets-2026-03-13",
+  "tool-search-tool-2025-10-19",
+  // SDK admin route beta (used for /v1/user_profiles* endpoints). Registered for
+  // forward-compat; the plugin proxies /v1/messages only and does NOT emit this
+  // on chat completions.
+  "user-profiles-2026-03-24",
+  "web-search-2025-03-05",
+]);
+
+/** Friendly shortcut aliases for config.custom_betas values. */
+export const BETA_SHORTCUTS = new Map([
+  ["1m", "context-1m-2025-08-07"],
+  ["1m-context", "context-1m-2025-08-07"],
+  ["context-1m", "context-1m-2025-08-07"],
+  ["cache-diagnosis", "cache-diagnosis-2026-04-07"],
+  ["cache-diag", "cache-diagnosis-2026-04-07"],
+  ["cache-ttl", "extended-cache-ttl-2025-04-11"],
+  ["context-hint", "context-hint-2026-04-09"],
+  ["environments", "environments-2025-11-01"],
+  ["extended-cache-ttl", "extended-cache-ttl-2025-04-11"],
+  ["hint", "context-hint-2026-04-09"],
+  ["fast", "fast-mode-2026-02-01"],
+  ["fast-mode", "fast-mode-2026-02-01"],
+  ["opus-fast", "fast-mode-2026-02-01"],
+  ["task-budgets", "task-budgets-2026-03-13"],
+  ["budgets", "task-budgets-2026-03-13"],
+  ["redact-thinking", "redact-thinking-2026-02-12"],
+  ["mid-conv-system", "mid-conversation-system-2026-04-07"],
+  ["mid-system", "mid-conversation-system-2026-04-07"],
+  ["context-management", "context-management-2025-06-27"],
+  ["structured-outputs", "structured-outputs-2025-12-15"],
+  ["web-search", "web-search-2025-03-05"],
+  ["advanced-tool-use", "advanced-tool-use-2025-11-20"],
+  ["tool-search-tool", "tool-search-tool-2025-10-19"],
+  ["effort", "effort-2025-11-24"],
+  ["prompt-caching-scope", "prompt-caching-scope-2026-01-05"],
+  ["thinking-token-count", "thinking-token-count-2026-05-13"],
+  ["afk-mode", "afk-mode-2026-01-31"],
+  ["advisor-tool", "advisor-tool-2026-03-01"],
+  ["mcp-servers", "mcp-servers-2025-12-04"],
+  ["ccr-byoc", "ccr-byoc-2025-07-29"],
+  ["connector-text", "summarize-connector-text-2026-03-13"],
+  ["narration-summaries", "summarize-connector-text-2026-03-13"],
+  ["summarize-connector-text", "summarize-connector-text-2026-03-13"],
+  ["server-side-fallback", "server-side-fallback-2026-06-01"],
+  ["fallback", "server-side-fallback-2026-06-01"],
+  ["fallback-credit", "fallback-credit-2026-06-01"],
+]);
+
+/**
+ * Resolve a beta shortcut alias to its canonical flag name.
+ * Returns the value unchanged if no alias matches.
+ * @param {string | null | undefined} value
+ * @returns {string}
+ */
+export function resolveBetaShortcut(value) {
+  if (!value) return "";
+  const trimmed = value.trim();
+  const mapped = BETA_SHORTCUTS.get(trimmed.toLowerCase());
+  return mapped || trimmed;
+}