@xelauvas/xela-cli 0.1.0

package/src/services/analytics/growthbook.ts

@@ -0,0 +1,1157 @@
+import { GrowthBook } from '@growthbook/growthbook'
+import { isEqual, memoize } from 'lodash-es'
+import {
+  getIsNonInteractiveSession,
+  getSessionTrustAccepted,
+} from '../../bootstrap/state.js'
+import { getGrowthBookClientKey } from '../../constants/keys.js'
+import {
+  checkHasTrustDialogAccepted,
+  getGlobalConfig,
+  saveGlobalConfig,
+} from '../../utils/config.js'
+import { logForDebugging } from '../../utils/debug.js'
+import { toError } from '../../utils/errors.js'
+import { getAuthHeaders } from '../../utils/http.js'
+import { logError } from '../../utils/log.js'
+import { createSignal } from '../../utils/signal.js'
+import { jsonStringify } from '../../utils/slowOperations.js'
+import {
+  type GitHubActionsMetadata,
+  getUserForGrowthBook,
+} from '../../utils/user.js'
+import {
+  is1PEventLoggingEnabled,
+  logGrowthBookExperimentTo1P,
+} from './firstPartyEventLogger.js'
+
+/**
+ * User attributes sent to GrowthBook for targeting.
+ * Uses UUID suffix (not Uuid) to align with GrowthBook conventions.
+ */
+export type GrowthBookUserAttributes = {
+  id: string
+  sessionId: string
+  deviceID: string
+  platform: 'win32' | 'darwin' | 'linux'
+  apiBaseUrlHost?: string
+  organizationUUID?: string
+  accountUUID?: string
+  userType?: string
+  subscriptionType?: string
+  rateLimitTier?: string
+  firstTokenTime?: number
+  email?: string
+  appVersion?: string
+  github?: GitHubActionsMetadata
+}
+
+/**
+ * Malformed feature response from API that uses "value" instead of "defaultValue".
+ * This is a workaround until the API is fixed.
+ */
+type MalformedFeatureDefinition = {
+  value?: unknown
+  defaultValue?: unknown
+  [key: string]: unknown
+}
+
+let client: GrowthBook | null = null
+
+// Named handler refs so resetGrowthBook can remove them to prevent accumulation
+let currentBeforeExitHandler: (() => void) | null = null
+let currentExitHandler: (() => void) | null = null
+
+// Track whether auth was available when the client was created
+// This allows us to detect when we need to recreate with fresh auth headers
+let clientCreatedWithAuth = false
+
+// Store experiment data from payload for logging exposures later
+type StoredExperimentData = {
+  experimentId: string
+  variationId: number
+  inExperiment?: boolean
+  hashAttribute?: string
+  hashValue?: string
+}
+const experimentDataByFeature = new Map<string, StoredExperimentData>()
+
+// Cache for remote eval feature values - workaround for SDK not respecting remoteEval response
+// The SDK's setForcedFeatures also doesn't work reliably with remoteEval
+const remoteEvalFeatureValues = new Map<string, unknown>()
+
+// Track features accessed before init that need exposure logging
+const pendingExposures = new Set<string>()
+
+// Track features that have already had their exposure logged this session (dedup)
+// This prevents firing duplicate exposure events when getFeatureValue_CACHED_MAY_BE_STALE
+// is called repeatedly in hot paths (e.g., isAutoMemoryEnabled in render loops)
+const loggedExposures = new Set<string>()
+
+// Track re-initialization promise for security gate checks
+// When GrowthBook is re-initializing (e.g., after auth change), security gate checks
+// should wait for init to complete to avoid returning stale values
+let reinitializingPromise: Promise<unknown> | null = null
+
+// Listeners notified when GrowthBook feature values refresh (initial init or
+// periodic refresh). Use for systems that bake feature values into long-lived
+// objects at construction time (e.g. firstPartyEventLogger reads
+// tengu_1p_event_batch_config once and builds a LoggerProvider with it) and
+// need to rebuild when config changes. Per-call readers like
+// getEventSamplingConfig / isSinkKilled don't need this — they're already
+// reactive.
+//
+// NOT cleared by resetGrowthBook — subscribers register once (typically in
+// init.ts) and must survive auth-change resets.
+type GrowthBookRefreshListener = () => void | Promise<void>
+const refreshed = createSignal()
+
+/** Call a listener with sync-throw and async-rejection both routed to logError. */
+function callSafe(listener: GrowthBookRefreshListener): void {
+  try {
+    // Promise.resolve() normalizes sync returns and Promises so both
+    // sync throws (caught by outer try) and async rejections (caught
+    // by .catch) hit logError. Without the .catch, an async listener
+    // that rejects becomes an unhandled rejection — the try/catch
+    // only sees the Promise, not its eventual rejection.
+    void Promise.resolve(listener()).catch(e => {
+      logError(e)
+    })
+  } catch (e) {
+    logError(e)
+  }
+}
+
+/**
+ * Register a callback to fire when GrowthBook feature values refresh.
+ * Returns an unsubscribe function.
+ *
+ * If init has already completed with features by the time this is called
+ * (remoteEvalFeatureValues is populated), the listener fires once on the
+ * next microtask. This catch-up handles the race where GB's network response
+ * lands before the REPL's useEffect commits — on external builds with fast
+ * networks and MCP-heavy configs, init can finish in ~100ms while REPL mount
+ * takes ~600ms (see #20951 external-build trace at 30.540 vs 31.046).
+ *
+ * Change detection is on the subscriber: the callback fires on every refresh;
+ * use isEqual against your last-seen config to decide whether to act.
+ */
+export function onGrowthBookRefresh(
+  listener: GrowthBookRefreshListener,
+): () => void {
+  let subscribed = true
+  const unsubscribe = refreshed.subscribe(() => callSafe(listener))
+  if (remoteEvalFeatureValues.size > 0) {
+    queueMicrotask(() => {
+      // Re-check: listener may have been removed, or resetGrowthBook may have
+      // cleared the Map, between registration and this microtask running.
+      if (subscribed && remoteEvalFeatureValues.size > 0) {
+        callSafe(listener)
+      }
+    })
+  }
+  return () => {
+    subscribed = false
+    unsubscribe()
+  }
+}
+
+/**
+ * Parse env var overrides for GrowthBook features.
+ * Set CLAUDE_INTERNAL_FC_OVERRIDES to a JSON object mapping feature keys to values
+ * to bypass remote eval and disk cache. Useful for eval harnesses that need to
+ * test specific feature flag configurations. Only active when USER_TYPE is 'ant'.
+ *
+ * Example: CLAUDE_INTERNAL_FC_OVERRIDES='{"my_feature": true, "my_config": {"key": "val"}}'
+ */
+let envOverrides: Record<string, unknown> | null = null
+let envOverridesParsed = false
+
+function getEnvOverrides(): Record<string, unknown> | null {
+  if (!envOverridesParsed) {
+    envOverridesParsed = true
+    if (process.env.USER_TYPE === 'ant') {
+      const raw = process.env.CLAUDE_INTERNAL_FC_OVERRIDES
+      if (raw) {
+        try {
+          envOverrides = JSON.parse(raw) as Record<string, unknown>
+          logForDebugging(
+            `GrowthBook: Using env var overrides for ${Object.keys(envOverrides!).length} features: ${Object.keys(envOverrides!).join(', ')}`,
+          )
+        } catch {
+          logError(
+            new Error(
+              `GrowthBook: Failed to parse CLAUDE_INTERNAL_FC_OVERRIDES: ${raw}`,
+            ),
+          )
+        }
+      }
+    }
+  }
+  return envOverrides
+}
+
+/**
+ * Check if a feature has an env-var override (CLAUDE_INTERNAL_FC_OVERRIDES).
+ * When true, _CACHED_MAY_BE_STALE will return the override without touching
+ * disk or network — callers can skip awaiting init for that feature.
+ */
+export function hasGrowthBookEnvOverride(feature: string): boolean {
+  const overrides = getEnvOverrides()
+  return overrides !== null && feature in overrides
+}
+
+/**
+ * Local config overrides set via /config Gates tab (ant-only). Checked after
+ * env-var overrides — env wins so eval harnesses remain deterministic. Unlike
+ * getEnvOverrides this is not memoized: the user can change overrides at
+ * runtime, and getGlobalConfig() is already memory-cached (pointer-chase)
+ * until the next saveGlobalConfig() invalidates it.
+ */
+function getConfigOverrides(): Record<string, unknown> | undefined {
+  if (process.env.USER_TYPE !== 'ant') return undefined
+  try {
+    return getGlobalConfig().growthBookOverrides
+  } catch {
+    // getGlobalConfig() throws before configReadingAllowed is set (early
+    // main.tsx startup path). Same degrade as the disk-cache fallback below.
+    return undefined
+  }
+}
+
+/**
+ * Enumerate all known GrowthBook features and their current resolved values
+ * (not including overrides). In-memory payload first, disk cache fallback —
+ * same priority as the getters. Used by the /config Gates tab.
+ */
+export function getAllGrowthBookFeatures(): Record<string, unknown> {
+  if (remoteEvalFeatureValues.size > 0) {
+    return Object.fromEntries(remoteEvalFeatureValues)
+  }
+  return getGlobalConfig().cachedGrowthBookFeatures ?? {}
+}
+
+export function getGrowthBookConfigOverrides(): Record<string, unknown> {
+  return getConfigOverrides() ?? {}
+}
+
+/**
+ * Set or clear a single config override. Pass undefined to clear.
+ * Fires onGrowthBookRefresh listeners so systems that bake gate values into
+ * long-lived objects (useMainLoopModel, useSkillsChange, etc.) rebuild —
+ * otherwise overriding e.g. tengu_ant_model_override wouldn't actually
+ * change the model until the next periodic refresh.
+ */
+export function setGrowthBookConfigOverride(
+  feature: string,
+  value: unknown,
+): void {
+  if (process.env.USER_TYPE !== 'ant') return
+  try {
+    saveGlobalConfig(c => {
+      const current = c.growthBookOverrides ?? {}
+      if (value === undefined) {
+        if (!(feature in current)) return c
+        const { [feature]: _, ...rest } = current
+        if (Object.keys(rest).length === 0) {
+          const { growthBookOverrides: __, ...configWithout } = c
+          return configWithout
+        }
+        return { ...c, growthBookOverrides: rest }
+      }
+      if (isEqual(current[feature], value)) return c
+      return { ...c, growthBookOverrides: { ...current, [feature]: value } }
+    })
+    // Subscribers do their own change detection (see onGrowthBookRefresh docs),
+    // so firing on a no-op write is fine.
+    refreshed.emit()
+  } catch (e) {
+    logError(e)
+  }
+}
+
+export function clearGrowthBookConfigOverrides(): void {
+  if (process.env.USER_TYPE !== 'ant') return
+  try {
+    saveGlobalConfig(c => {
+      if (
+        !c.growthBookOverrides ||
+        Object.keys(c.growthBookOverrides).length === 0
+      ) {
+        return c
+      }
+      const { growthBookOverrides: _, ...rest } = c
+      return rest
+    })
+    refreshed.emit()
+  } catch (e) {
+    logError(e)
+  }
+}
+
+/**
+ * Log experiment exposure for a feature if it has experiment data.
+ * Deduplicates within a session - each feature is logged at most once.
+ */
+function logExposureForFeature(feature: string): void {
+  // Skip if already logged this session (dedup)
+  if (loggedExposures.has(feature)) {
+    return
+  }
+
+  const expData = experimentDataByFeature.get(feature)
+  if (expData) {
+    loggedExposures.add(feature)
+    logGrowthBookExperimentTo1P({
+      experimentId: expData.experimentId,
+      variationId: expData.variationId,
+      userAttributes: getUserAttributes(),
+      experimentMetadata: {
+        feature_id: feature,
+      },
+    })
+  }
+}
+
+/**
+ * Process a remote eval payload from the GrowthBook server and populate
+ * local caches. Called after both initial client.init() and after
+ * client.refreshFeatures() so that _BLOCKS_ON_INIT callers see fresh values
+ * across the process lifetime, not just init-time snapshots.
+ *
+ * Without this running on refresh, remoteEvalFeatureValues freezes at its
+ * init-time snapshot and getDynamicConfig_BLOCKS_ON_INIT returns stale values
+ * for the entire process lifetime — which broke the tengu_max_version_config
+ * kill switch for long-running sessions.
+ */
+async function processRemoteEvalPayload(
+  gbClient: GrowthBook,
+): Promise<boolean> {
+  // WORKAROUND: Transform remote eval response format
+  // The API returns { "value": ... } but SDK expects { "defaultValue": ... }
+  // TODO: Remove this once the API is fixed to return correct format
+  const payload = gbClient.getPayload()
+  // Empty object is truthy — without the length check, `{features: {}}`
+  // (transient server bug, truncated response) would pass, clear the maps
+  // below, return true, and syncRemoteEvalToDisk would wholesale-write `{}`
+  // to disk: total flag blackout for every process sharing ~/.claude.json.
+  if (!payload?.features || Object.keys(payload.features).length === 0) {
+    return false
+  }
+
+  // Clear before rebuild so features removed between refreshes don't
+  // leave stale ghost entries that short-circuit getFeatureValueInternal.
+  experimentDataByFeature.clear()
+
+  const transformedFeatures: Record<string, MalformedFeatureDefinition> = {}
+  for (const [key, feature] of Object.entries(payload.features)) {
+    const f = feature as MalformedFeatureDefinition
+    if ('value' in f && !('defaultValue' in f)) {
+      transformedFeatures[key] = {
+        ...f,
+        defaultValue: f.value,
+      }
+    } else {
+      transformedFeatures[key] = f
+    }
+
+    // Store experiment data for later logging when feature is accessed
+    if (f.source === 'experiment' && f.experimentResult) {
+      const expResult = f.experimentResult as {
+        variationId?: number
+      }
+      const exp = f.experiment as { key?: string } | undefined
+      if (exp?.key && expResult.variationId !== undefined) {
+        experimentDataByFeature.set(key, {
+          experimentId: exp.key,
+          variationId: expResult.variationId,
+        })
+      }
+    }
+  }
+  // Re-set the payload with transformed features
+  await gbClient.setPayload({
+    ...payload,
+    features: transformedFeatures,
+  })
+
+  // WORKAROUND: Cache the evaluated values directly from remote eval response.
+  // The SDK's evalFeature() tries to re-evaluate rules locally, ignoring the
+  // pre-evaluated 'value' from remoteEval. setForcedFeatures also doesn't work
+  // reliably. So we cache values ourselves and use them in getFeatureValueInternal.
+  remoteEvalFeatureValues.clear()
+  for (const [key, feature] of Object.entries(transformedFeatures)) {
+    // Under remoteEval:true the server pre-evaluates. Whether the answer
+    // lands in `value` (current API) or `defaultValue` (post-TODO API shape),
+    // it's the authoritative value for this user. Guarding on both keeps
+    // syncRemoteEvalToDisk correct across a partial or full API migration.
+    const v = 'value' in feature ? feature.value : feature.defaultValue
+    if (v !== undefined) {
+      remoteEvalFeatureValues.set(key, v)
+    }
+  }
+  return true
+}
+
+/**
+ * Write the complete remoteEvalFeatureValues map to disk. Called exactly
+ * once per successful processRemoteEvalPayload — never from a failure path,
+ * so init-timeout poisoning is structurally impossible (the .catch() at init
+ * never reaches here).
+ *
+ * Wholesale replace (not merge): features deleted server-side are dropped
+ * from disk on the next successful payload. Ant builds ⊇ external, so
+ * switching builds is safe — the write is always a complete answer for this
+ * process's SDK key.
+ */
+function syncRemoteEvalToDisk(): void {
+  const fresh = Object.fromEntries(remoteEvalFeatureValues)
+  const config = getGlobalConfig()
+  if (isEqual(config.cachedGrowthBookFeatures, fresh)) {
+    return
+  }
+  saveGlobalConfig(current => ({
+    ...current,
+    cachedGrowthBookFeatures: fresh,
+  }))
+}
+
+/**
+ * Check if GrowthBook operations should be enabled
+ */
+function isGrowthBookEnabled(): boolean {
+  // GrowthBook depends on 1P event logging.
+  return is1PEventLoggingEnabled()
+}
+
+/**
+ * Hostname of ANTHROPIC_BASE_URL when it points at a non-Anthropic proxy.
+ *
+ * Enterprise-proxy deployments (Epic, Marble, etc.) typically use
+ * apiKeyHelper auth, which means isAnthropicAuthEnabled() returns false and
+ * organizationUUID/accountUUID/email are all absent from GrowthBook
+ * attributes. Without this, there's no stable attribute to target them on
+ * — only per-device IDs. See src/utils/auth.ts isAnthropicAuthEnabled().
+ *
+ * Returns undefined for unset/default (api.anthropic.com) so the attribute
+ * is absent for direct-API users. Hostname only — no path/query/creds.
+ */
+export function getApiBaseUrlHost(): string | undefined {
+  const baseUrl = process.env.ANTHROPIC_BASE_URL
+  if (!baseUrl) return undefined
+  try {
+    const host = new URL(baseUrl).host
+    if (host === 'api.anthropic.com') return undefined
+    return host
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Get user attributes for GrowthBook from CoreUserData
+ */
+function getUserAttributes(): GrowthBookUserAttributes {
+  const user = getUserForGrowthBook()
+
+  // For ants, always try to include email from OAuth config even if ANTHROPIC_API_KEY is set.
+  // This ensures GrowthBook targeting by email works regardless of auth method.
+  let email = user.email
+  if (!email && process.env.USER_TYPE === 'ant') {
+    email = getGlobalConfig().oauthAccount?.emailAddress
+  }
+
+  const apiBaseUrlHost = getApiBaseUrlHost()
+
+  const attributes = {
+    id: user.deviceId,
+    sessionId: user.sessionId,
+    deviceID: user.deviceId,
+    platform: user.platform,
+    ...(apiBaseUrlHost && { apiBaseUrlHost }),
+    ...(user.organizationUuid && { organizationUUID: user.organizationUuid }),
+    ...(user.accountUuid && { accountUUID: user.accountUuid }),
+    ...(user.userType && { userType: user.userType }),
+    ...(user.subscriptionType && { subscriptionType: user.subscriptionType }),
+    ...(user.rateLimitTier && { rateLimitTier: user.rateLimitTier }),
+    ...(user.firstTokenTime && { firstTokenTime: user.firstTokenTime }),
+    ...(email && { email }),
+    ...(user.appVersion && { appVersion: user.appVersion }),
+    ...(user.githubActionsMetadata && {
+      githubActionsMetadata: user.githubActionsMetadata,
+    }),
+  }
+  return attributes
+}
+
+/**
+ * Get or create the GrowthBook client instance
+ */
+const getGrowthBookClient = memoize(
+  (): { client: GrowthBook; initialized: Promise<void> } | null => {
+    if (!isGrowthBookEnabled()) {
+      return null
+    }
+
+    const attributes = getUserAttributes()
+    const clientKey = getGrowthBookClientKey()
+    if (process.env.USER_TYPE === 'ant') {
+      logForDebugging(
+        `GrowthBook: Creating client with clientKey=${clientKey}, attributes: ${jsonStringify(attributes)}`,
+      )
+    }
+    const baseUrl =
+      process.env.USER_TYPE === 'ant'
+        ? process.env.CLAUDE_CODE_GB_BASE_URL || 'https://api.anthropic.com/'
+        : 'https://api.anthropic.com/'
+
+    // Skip auth if trust hasn't been established yet
+    // This prevents executing apiKeyHelper commands before the trust dialog
+    // Non-interactive sessions implicitly have workspace trust
+    // getSessionTrustAccepted() covers the case where the TrustDialog auto-resolved
+    // without persisting trust for the specific CWD (e.g., home directory) —
+    // showSetupScreens() sets this after the trust dialog flow completes.
+    const hasTrust =
+      checkHasTrustDialogAccepted() ||
+      getSessionTrustAccepted() ||
+      getIsNonInteractiveSession()
+    const authHeaders = hasTrust
+      ? getAuthHeaders()
+      : { headers: {}, error: 'trust not established' }
+    const hasAuth = !authHeaders.error
+    clientCreatedWithAuth = hasAuth
+
+    // Capture in local variable so the init callback operates on THIS client,
+    // not a later client if reinitialization happens before init completes
+    const thisClient = new GrowthBook({
+      apiHost: baseUrl,
+      clientKey,
+      attributes,
+      remoteEval: true,
+      // Re-fetch when user ID or org changes (org change = login to different org)
+      cacheKeyAttributes: ['id', 'organizationUUID'],
+      // Add auth headers if available
+      ...(authHeaders.error
+        ? {}
+        : { apiHostRequestHeaders: authHeaders.headers }),
+      // Debug logging for Ants
+      ...(process.env.USER_TYPE === 'ant'
+        ? {
+            log: (msg: string, ctx: Record<string, unknown>) => {
+              logForDebugging(`GrowthBook: ${msg} ${jsonStringify(ctx)}`)
+            },
+          }
+        : {}),
+    })
+    client = thisClient
+
+    if (!hasAuth) {
+      // No auth available yet — skip HTTP init, rely on disk-cached values.
+      // initializeGrowthBook() will reset and re-create with auth when available.
+      return { client: thisClient, initialized: Promise.resolve() }
+    }
+
+    const initialized = thisClient
+      .init({ timeout: 5000 })
+      .then(async result => {
+        // Guard: if this client was replaced by a newer one, skip processing
+        if (client !== thisClient) {
+          if (process.env.USER_TYPE === 'ant') {
+            logForDebugging(
+              'GrowthBook: Skipping init callback for replaced client',
+            )
+          }
+          return
+        }
+
+        if (process.env.USER_TYPE === 'ant') {
+          logForDebugging(
+            `GrowthBook initialized successfully, source: ${result.source}, success: ${result.success}`,
+          )
+        }
+
+        const hadFeatures = await processRemoteEvalPayload(thisClient)
+        // Re-check: processRemoteEvalPayload yields at `await setPayload`.
+        // Microtask-only today (no encryption, no sticky-bucket service), but
+        // the guard at the top of this callback runs before that await;
+        // this runs after.
+        if (client !== thisClient) return
+
+        if (hadFeatures) {
+          for (const feature of pendingExposures) {
+            logExposureForFeature(feature)
+          }
+          pendingExposures.clear()
+          syncRemoteEvalToDisk()
+          // Notify subscribers: remoteEvalFeatureValues is populated and
+          // disk is freshly synced. _CACHED_MAY_BE_STALE reads memory first
+          // (#22295), so subscribers see fresh values immediately.
+          refreshed.emit()
+        }
+
+        // Log what features were loaded
+        if (process.env.USER_TYPE === 'ant') {
+          const features = thisClient.getFeatures()
+          if (features) {
+            const featureKeys = Object.keys(features)
+            logForDebugging(
+              `GrowthBook loaded ${featureKeys.length} features: ${featureKeys.slice(0, 10).join(', ')}${featureKeys.length > 10 ? '...' : ''}`,
+            )
+          }
+        }
+      })
+      .catch(error => {
+        if (process.env.USER_TYPE === 'ant') {
+          logError(toError(error))
+        }
+      })
+
+    // Register cleanup handlers for graceful shutdown (named refs so resetGrowthBook can remove them)
+    currentBeforeExitHandler = () => client?.destroy()
+    currentExitHandler = () => client?.destroy()
+    process.on('beforeExit', currentBeforeExitHandler)
+    process.on('exit', currentExitHandler)
+
+    return { client: thisClient, initialized }
+  },
+)
+
+/**
+ * Initialize GrowthBook client (blocks until ready)
+ */
+export const initializeGrowthBook = memoize(
+  async (): Promise<GrowthBook | null> => {
+    if (process.env.OPENAI_API_KEY) return null;
+    let clientWrapper = getGrowthBookClient()
+    if (!clientWrapper) {
+      return null
+    }
+
+    // Check if auth has become available since the client was created
+    // If so, we need to recreate the client with fresh auth headers
+    // Only check if trust is established to avoid triggering apiKeyHelper before trust dialog
+    if (!clientCreatedWithAuth) {
+      const hasTrust =
+        checkHasTrustDialogAccepted() ||
+        getSessionTrustAccepted() ||
+        getIsNonInteractiveSession()
+      if (hasTrust) {
+        const currentAuth = getAuthHeaders()
+        if (!currentAuth.error) {
+          if (process.env.USER_TYPE === 'ant') {
+            logForDebugging(
+              'GrowthBook: Auth became available after client creation, reinitializing',
+            )
+          }
+          // Use resetGrowthBook to properly destroy old client and stop periodic refresh
+          // This prevents double-init where old client's init promise continues running
+          resetGrowthBook()
+          clientWrapper = getGrowthBookClient()
+          if (!clientWrapper) {
+            return null
+          }
+        }
+      }
+    }
+
+    await clientWrapper.initialized
+
+    // Set up periodic refresh after successful initialization
+    // This is called here (not separately) so it's always re-established after any reinit
+    setupPeriodicGrowthBookRefresh()
+
+    return clientWrapper.client
+  },
+)
+
+/**
+ * Get a feature value with a default fallback - blocks until initialized.
+ * @internal Used by both deprecated and cached functions.
+ */
+async function getFeatureValueInternal<T>(
+  feature: string,
+  defaultValue: T,
+  logExposure: boolean,
+): Promise<T> {
+  // Check env var overrides first (for eval harnesses)
+  const overrides = getEnvOverrides()
+  if (overrides && feature in overrides) {
+    return overrides[feature] as T
+  }
+  const configOverrides = getConfigOverrides()
+  if (configOverrides && feature in configOverrides) {
+    return configOverrides[feature] as T
+  }
+
+  if (!isGrowthBookEnabled()) {
+    return defaultValue
+  }
+
+  const growthBookClient = await initializeGrowthBook()
+  if (!growthBookClient) {
+    return defaultValue
+  }
+
+  // Use cached remote eval values if available (workaround for SDK bug)
+  let result: T
+  if (remoteEvalFeatureValues.has(feature)) {
+    result = remoteEvalFeatureValues.get(feature) as T
+  } else {
+    result = growthBookClient.getFeatureValue(feature, defaultValue) as T
+  }
+
+  // Log experiment exposure using stored experiment data
+  if (logExposure) {
+    logExposureForFeature(feature)
+  }
+
+  if (process.env.USER_TYPE === 'ant') {
+    logForDebugging(
+      `GrowthBook: getFeatureValue("${feature}") = ${jsonStringify(result)}`,
+    )
+  }
+  return result
+}
+
+/**
+ * @deprecated Use getFeatureValue_CACHED_MAY_BE_STALE instead, which is non-blocking.
+ * This function blocks on GrowthBook initialization which can slow down startup.
+ */
+export async function getFeatureValue_DEPRECATED<T>(
+  feature: string,
+  defaultValue: T,
+): Promise<T> {
+  return getFeatureValueInternal(feature, defaultValue, true)
+}
+
+/**
+ * Get a feature value from disk cache immediately. Pure read — disk is
+ * populated by syncRemoteEvalToDisk on every successful payload (init +
+ * periodic refresh), not by this function.
+ *
+ * This is the preferred method for startup-critical paths and sync contexts.
+ * The value may be stale if the cache was written by a previous process.
+ */
+export function getFeatureValue_CACHED_MAY_BE_STALE<T>(
+  feature: string,
+  defaultValue: T,
+): T {
+  // Check env var overrides first (for eval harnesses)
+  const overrides = getEnvOverrides()
+  if (overrides && feature in overrides) {
+    return overrides[feature] as T
+  }
+  const configOverrides = getConfigOverrides()
+  if (configOverrides && feature in configOverrides) {
+    return configOverrides[feature] as T
+  }
+
+  if (!isGrowthBookEnabled()) {
+    return defaultValue
+  }
+
+  // Log experiment exposure if data is available, otherwise defer until after init
+  if (experimentDataByFeature.has(feature)) {
+    logExposureForFeature(feature)
+  } else {
+    pendingExposures.add(feature)
+  }
+
+  // In-memory payload is authoritative once processRemoteEvalPayload has run.
+  // Disk is also fresh by then (syncRemoteEvalToDisk runs synchronously inside
+  // init), so this is correctness-equivalent to the disk read below — but it
+  // skips the config JSON parse and is what onGrowthBookRefresh subscribers
+  // depend on to read fresh values the instant they're notified.
+  if (remoteEvalFeatureValues.has(feature)) {
+    return remoteEvalFeatureValues.get(feature) as T
+  }
+
+  // Fall back to disk cache (survives across process restarts)
+  try {
+    const cached = getGlobalConfig().cachedGrowthBookFeatures?.[feature]
+    return cached !== undefined ? (cached as T) : defaultValue
+  } catch {
+    return defaultValue
+  }
+}
+
+/**
+ * @deprecated Disk cache is now synced on every successful payload load
+ * (init + 20min/6h periodic refresh). The per-feature TTL never fetched
+ * fresh data from the server — it only re-wrote in-memory state to disk,
+ * which is now redundant. Use getFeatureValue_CACHED_MAY_BE_STALE directly.
+ */
+export function getFeatureValue_CACHED_WITH_REFRESH<T>(
+  feature: string,
+  defaultValue: T,
+  _refreshIntervalMs: number,
+): T {
+  return getFeatureValue_CACHED_MAY_BE_STALE(feature, defaultValue)
+}
+
+/**
+ * Check a Statsig feature gate value via GrowthBook, with fallback to Statsig cache.
+ *
+ * **MIGRATION ONLY**: This function is for migrating existing Statsig gates to GrowthBook.
+ * For new features, use `getFeatureValue_CACHED_MAY_BE_STALE()` instead.
+ *
+ * - Checks GrowthBook disk cache first
+ * - Falls back to Statsig's cachedStatsigGates during migration
+ * - The value may be stale if the cache hasn't been updated recently
+ *
+ * @deprecated Use getFeatureValue_CACHED_MAY_BE_STALE() for new code. This function
+ * exists only to support migration of existing Statsig gates.
+ */
+export function checkStatsigFeatureGate_CACHED_MAY_BE_STALE(
+  gate: string,
+): boolean {
+  // Check env var overrides first (for eval harnesses)
+  const overrides = getEnvOverrides()
+  if (overrides && gate in overrides) {
+    return Boolean(overrides[gate])
+  }
+  const configOverrides = getConfigOverrides()
+  if (configOverrides && gate in configOverrides) {
+    return Boolean(configOverrides[gate])
+  }
+
+  if (!isGrowthBookEnabled()) {
+    return false
+  }
+
+  // Log experiment exposure if data is available, otherwise defer until after init
+  if (experimentDataByFeature.has(gate)) {
+    logExposureForFeature(gate)
+  } else {
+    pendingExposures.add(gate)
+  }
+
+  // Return cached value immediately from disk
+  // First check GrowthBook cache, then fall back to Statsig cache for migration
+  const config = getGlobalConfig()
+  const gbCached = config.cachedGrowthBookFeatures?.[gate]
+  if (gbCached !== undefined) {
+    return Boolean(gbCached)
+  }
+  // Fallback to Statsig cache for migration period
+  return config.cachedStatsigGates?.[gate] ?? false
+}
+
+/**
+ * Check a security restriction gate, waiting for re-init if in progress.
+ *
+ * Use this for security-critical gates where we need fresh values after auth changes.
+ *
+ * Behavior:
+ * - If GrowthBook is re-initializing (e.g., after login), waits for it to complete
+ * - Otherwise, returns cached value immediately (Statsig cache first, then GrowthBook)
+ *
+ * Statsig cache is checked first as a safety measure for security-related checks:
+ * if the Statsig cache indicates the gate is enabled, we honor it.
+ */
+export async function checkSecurityRestrictionGate(
+  gate: string,
+): Promise<boolean> {
+  // Check env var overrides first (for eval harnesses)
+  const overrides = getEnvOverrides()
+  if (overrides && gate in overrides) {
+    return Boolean(overrides[gate])
+  }
+  const configOverrides = getConfigOverrides()
+  if (configOverrides && gate in configOverrides) {
+    return Boolean(configOverrides[gate])
+  }
+
+  if (!isGrowthBookEnabled()) {
+    return false
+  }
+
+  // If re-initialization is in progress, wait for it to complete
+  // This ensures we get fresh values after auth changes
+  if (reinitializingPromise) {
+    await reinitializingPromise
+  }
+
+  // Check Statsig cache first - it may have correct value from previous logged-in session
+  const config = getGlobalConfig()
+  const statsigCached = config.cachedStatsigGates?.[gate]
+  if (statsigCached !== undefined) {
+    return Boolean(statsigCached)
+  }
+
+  // Then check GrowthBook cache
+  const gbCached = config.cachedGrowthBookFeatures?.[gate]
+  if (gbCached !== undefined) {
+    return Boolean(gbCached)
+  }
+
+  // No cache - return false (don't block on init for uncached gates)
+  return false
+}
+
+/**
+ * Check a boolean entitlement gate with fallback-to-blocking semantics.
+ *
+ * Fast path: if the disk cache already says `true`, return it immediately.
+ * Slow path: if disk says `false`/missing, await GrowthBook init and fetch the
+ * fresh server value (max ~5s). Disk is populated by syncRemoteEvalToDisk
+ * inside init, so by the time the slow path returns, disk already has the
+ * fresh value — no write needed here.
+ *
+ * Use for user-invoked features (e.g. /remote-control) that are gated on
+ * subscription/org, where a stale `false` would unfairly block access but a
+ * stale `true` is acceptable (the server is the real gatekeeper).
+ */
+export async function checkGate_CACHED_OR_BLOCKING(
+  gate: string,
+): Promise<boolean> {
+  // Check env var overrides first (for eval harnesses)
+  const overrides = getEnvOverrides()
+  if (overrides && gate in overrides) {
+    return Boolean(overrides[gate])
+  }
+  const configOverrides = getConfigOverrides()
+  if (configOverrides && gate in configOverrides) {
+    return Boolean(configOverrides[gate])
+  }
+
+  if (!isGrowthBookEnabled()) {
+    return false
+  }
+
+  // Fast path: disk cache already says true — trust it
+  const cached = getGlobalConfig().cachedGrowthBookFeatures?.[gate]
+  if (cached === true) {
+    // Log experiment exposure if data is available, otherwise defer
+    if (experimentDataByFeature.has(gate)) {
+      logExposureForFeature(gate)
+    } else {
+      pendingExposures.add(gate)
+    }
+    return true
+  }
+
+  // Slow path: disk says false/missing — may be stale, fetch fresh
+  return getFeatureValueInternal(gate, false, true)
+}
+
+/**
+ * Refresh GrowthBook after auth changes (login/logout).
+ *
+ * NOTE: This must destroy and recreate the client because GrowthBook's
+ * apiHostRequestHeaders cannot be updated after client creation.
+ */
+export function refreshGrowthBookAfterAuthChange(): void {
+  if (!isGrowthBookEnabled()) {
+    return
+  }
+
+  try {
+    // Reset the client completely to get fresh auth headers
+    // This is necessary because apiHostRequestHeaders can't be updated after creation
+    resetGrowthBook()
+
+    // resetGrowthBook cleared remoteEvalFeatureValues. If re-init below
+    // times out (hadFeatures=false) or short-circuits on !hasAuth (logout),
+    // the init-callback notify never fires — subscribers stay synced to the
+    // previous account's memoized state. Notify here so they re-read now
+    // (falls to disk cache). If re-init succeeds, they'll notify again with
+    // fresh values; if not, at least they're synced to the post-reset state.
+    refreshed.emit()
+
+    // Reinitialize with fresh auth headers and attributes
+    // Track this promise so security gate checks can wait for it.
+    // .catch before .finally: initializeGrowthBook can reject if its sync
+    // helpers throw (getGrowthBookClient, getAuthHeaders, resetGrowthBook —
+    // clientWrapper.initialized itself has its own .catch so never rejects),
+    // and .finally re-settles with the original rejection — the sync
+    // try/catch below cannot catch async rejections.
+    reinitializingPromise = initializeGrowthBook()
+      .catch(error => {
+        logError(toError(error))
+        return null
+      })
+      .finally(() => {
+        reinitializingPromise = null
+      })
+  } catch (error) {
+    if (process.env.NODE_ENV === 'development') {
+      throw error
+    }
+    logError(toError(error))
+  }
+}
+
+/**
+ * Reset GrowthBook client state (primarily for testing)
+ */
+export function resetGrowthBook(): void {
+  stopPeriodicGrowthBookRefresh()
+  // Remove process handlers before destroying client to prevent accumulation
+  if (currentBeforeExitHandler) {
+    process.off('beforeExit', currentBeforeExitHandler)
+    currentBeforeExitHandler = null
+  }
+  if (currentExitHandler) {
+    process.off('exit', currentExitHandler)
+    currentExitHandler = null
+  }
+  client?.destroy()
+  client = null
+  clientCreatedWithAuth = false
+  reinitializingPromise = null
+  experimentDataByFeature.clear()
+  pendingExposures.clear()
+  loggedExposures.clear()
+  remoteEvalFeatureValues.clear()
+  getGrowthBookClient.cache?.clear?.()
+  initializeGrowthBook.cache?.clear?.()
+  envOverrides = null
+  envOverridesParsed = false
+}
+
+// Periodic refresh interval (matches Statsig's 6-hour interval)
+const GROWTHBOOK_REFRESH_INTERVAL_MS =
+  process.env.USER_TYPE !== 'ant'
+    ? 6 * 60 * 60 * 1000 // 6 hours
+    : 20 * 60 * 1000 // 20 min (for ants)
+let refreshInterval: ReturnType<typeof setInterval> | null = null
+let beforeExitListener: (() => void) | null = null
+
+/**
+ * Light refresh - re-fetch features from server without recreating client.
+ * Use this for periodic refresh when auth headers haven't changed.
+ *
+ * Unlike refreshGrowthBookAfterAuthChange() which destroys and recreates the client,
+ * this preserves client state and just fetches fresh feature values.
+ */
+export async function refreshGrowthBookFeatures(): Promise<void> {
+  if (!isGrowthBookEnabled()) {
+    return
+  }
+
+  try {
+    const growthBookClient = await initializeGrowthBook()
+    if (!growthBookClient) {
+      return
+    }
+
+    await growthBookClient.refreshFeatures()
+
+    // Guard: if this client was replaced during the in-flight refresh
+    // (e.g. refreshGrowthBookAfterAuthChange ran), skip processing the
+    // stale payload. Mirrors the init-callback guard above.
+    if (growthBookClient !== client) {
+      if (process.env.USER_TYPE === 'ant') {
+        logForDebugging(
+          'GrowthBook: Skipping refresh processing for replaced client',
+        )
+      }
+      return
+    }
+
+    // Rebuild remoteEvalFeatureValues from the refreshed payload so that
+    // _BLOCKS_ON_INIT callers (e.g. getMaxVersion for the auto-update kill
+    // switch) see fresh values, not the stale init-time snapshot.
+    const hadFeatures = await processRemoteEvalPayload(growthBookClient)
+    // Same re-check as init path: covers the setPayload yield inside
+    // processRemoteEvalPayload (the guard above only covers refreshFeatures).
+    if (growthBookClient !== client) return
+
+    if (process.env.USER_TYPE === 'ant') {
+      logForDebugging('GrowthBook: Light refresh completed')
+    }
+
+    // Gate on hadFeatures: if the payload was empty/malformed,
+    // remoteEvalFeatureValues wasn't rebuilt — skip both the no-op disk
+    // write and the spurious subscriber churn (clearCommandMemoizationCaches
+    // + getCommands + 4× model re-renders).
+    if (hadFeatures) {
+      syncRemoteEvalToDisk()
+      refreshed.emit()
+    }
+  } catch (error) {
+    if (process.env.NODE_ENV === 'development') {
+      throw error
+    }
+    logError(toError(error))
+  }
+}
+
+/**
+ * Set up periodic refresh of GrowthBook features.
+ * Uses light refresh (refreshGrowthBookFeatures) to re-fetch without recreating client.
+ *
+ * Call this after initialization for long-running sessions to ensure
+ * feature values stay fresh. Matches Statsig's 6-hour refresh interval.
+ */
+export function setupPeriodicGrowthBookRefresh(): void {
+  if (!isGrowthBookEnabled()) {
+    return
+  }
+
+  // Clear any existing interval to avoid duplicates
+  if (refreshInterval) {
+    clearInterval(refreshInterval)
+  }
+
+  refreshInterval = setInterval(() => {
+    void refreshGrowthBookFeatures()
+  }, GROWTHBOOK_REFRESH_INTERVAL_MS)
+  // Allow process to exit naturally - this timer shouldn't keep the process alive
+  refreshInterval.unref?.()
+
+  // Register cleanup listener only once
+  if (!beforeExitListener) {
+    beforeExitListener = () => {
+      stopPeriodicGrowthBookRefresh()
+    }
+    process.once('beforeExit', beforeExitListener)
+  }
+}
+
+/**
+ * Stop periodic refresh (for testing or cleanup)
+ */
+export function stopPeriodicGrowthBookRefresh(): void {
+  if (refreshInterval) {
+    clearInterval(refreshInterval)
+    refreshInterval = null
+  }
+  if (beforeExitListener) {
+    process.removeListener('beforeExit', beforeExitListener)
+    beforeExitListener = null
+  }
+}
+
+// ============================================================================
+// Dynamic Config Functions
+// These are semantic wrappers around feature functions for Statsig API parity.
+// In GrowthBook, dynamic configs are just features with object values.
+// ============================================================================
+
+/**
+ * Get a dynamic config value - blocks until GrowthBook is initialized.
+ * Prefer getFeatureValue_CACHED_MAY_BE_STALE for startup-critical paths.
+ */
+export async function getDynamicConfig_BLOCKS_ON_INIT<T>(
+  configName: string,
+  defaultValue: T,
+): Promise<T> {
+  if (process.env.OPENAI_API_KEY) return defaultValue;
+  return getFeatureValue_DEPRECATED(configName, defaultValue)
+}
+
+/**
+ * Get a dynamic config value from disk cache immediately. Pure read — see
+ * getFeatureValue_CACHED_MAY_BE_STALE.
+ * This is the preferred method for startup-critical paths and sync contexts.
+ *
+ * In GrowthBook, dynamic configs are just features with object values.
+ */
+export function getDynamicConfig_CACHED_MAY_BE_STALE<T>(
+  configName: string,
+  defaultValue: T,
+): T {
+  return getFeatureValue_CACHED_MAY_BE_STALE(configName, defaultValue)
+}