fix(webapp): show stored org values for locked flags in the admin flags dialog

The admin org flags dialog now shows an org's own value for read-only flags, and says what that value does: it overrides the global value, it's stored but ignored, or it's a server-written stamp. Stored org flags are now read one key at a time, so a single invalid value no longer makes the dialog and the admin API treat the org as having no flags. Saves keep stored values they didn't change, including keys the running version doesn't know yet.

Mono-RevId: 061e76440f3462887e0b63d75b556a70ae02c480

Author: Mariefay

apps/webapp/app/components/admin/FeatureFlagsDialog.tsx

@@ -13,7 +13,15 @@ import { Callout } from "~/components/primitives/Callout";
 import { LockClosedIcon } from "@heroicons/react/20/solid";
 import { CheckboxWithLabel } from "~/components/primitives/Checkbox";
 import { cn } from "~/utils/cn";
-import { FEATURE_FLAG, ORG_LOCKED_FLAGS, type FlagControlType } from "~/v3/featureFlags";
+import {
+  FEATURE_FLAG,
+  ORG_LOCKED_FLAG_EFFECT,
+  ORG_LOCKED_FLAGS,
+  isUnchangedInvalidFlag,
+  type FeatureFlagKey,
+  type FlagControlType,
+  type OrgLockedFlagEffect,
+} from "~/v3/featureFlags";
 import {
   UNSET_VALUE,
   BooleanControl,
@@ -33,6 +41,7 @@ import {
 type LoaderData = {
   org: { id: string; title: string; slug: string };
   orgFlags: Record<string, unknown>;
+  invalidOrgFlags?: Record<string, unknown>;
   globalFlags: Record<string, unknown>;
   controlTypes: Record<string, FlagControlType>;
   workerGroupName?: string;
@@ -41,6 +50,22 @@ type LoaderData = {
   isManagedCloud?: boolean;
 };
 
+const LOCKED_EFFECT_LABEL: Record<OrgLockedFlagEffect, string> = {
+  live: "overrides global",
+  ignored: "stored, ignored",
+  derived: "grace stamp",
+};
+
+// Most flags fall back to global when the org value fails its schema, but not all of them.
+const INVALID_VALUE_LABEL: Partial<Record<string, string>> = {
+  [FEATURE_FLAG.dashboardAgentTurnEvalsEnabled]: "invalid, treated as off",
+  [FEATURE_FLAG.workerQueueEnvironmentOverrides]: "invalid, valid entries still apply",
+};
+
+function formatStoredValue(value: unknown): string {
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+
 type ActionData = {
   success?: boolean;
   error?: string;
@@ -85,7 +110,8 @@ export function FeatureFlagsDialog({
 
   useEffect(() => {
     if (loadFetcher.data) {
-      const loaded = loadFetcher.data.orgFlags ?? {};
+      // Invalid stored values ride along unchanged, so a save keeps them unless unset.
+      const loaded = { ...loadFetcher.data.orgFlags, ...loadFetcher.data.invalidOrgFlags };
       // oxlint-disable-next-line react/set-state-in-effect -- This effect intentionally synchronizes local state after an external or lifecycle change.
       setOverrides({ ...loaded });
       setInitialOverrides({ ...loaded });
@@ -102,8 +128,16 @@ export function FeatureFlagsDialog({
   }, [saveFetcher.data]);
 
   const isDirty = stableStringify(overrides) !== stableStringify(initialOverrides);
-  const environmentOverrides = (overrides[FEATURE_FLAG.workerQueueEnvironmentOverrides] ??
-    {}) as WorkerQueueEnvironmentOverrides;
+  // An untouched invalid stored value isn't a draft: it renders as an invalid row, not the editor.
+  const environmentOverrides = (
+    isUnchangedInvalidFlag(
+      FEATURE_FLAG.workerQueueEnvironmentOverrides,
+      overrides,
+      loadFetcher.data?.invalidOrgFlags
+    )
+      ? {}
+      : (overrides[FEATURE_FLAG.workerQueueEnvironmentOverrides] ?? {})
+  ) as WorkerQueueEnvironmentOverrides;
   const hasIncompleteOverrides = incompleteOverrideScopes(environmentOverrides).length > 0;
 
   const setFlagValue = (key: string, value: unknown) => {
@@ -179,18 +213,86 @@ export function FeatureFlagsDialog({
                       ? String(globalValue)
                       : "unset";
 
+                const effect = ORG_LOCKED_FLAG_EFFECT[key as FeatureFlagKey];
+                const invalidStored = data.invalidOrgFlags?.[key];
+                const isInvalidStored = isUnchangedInvalidFlag(
+                  key,
+                  overrides,
+                  data.invalidOrgFlags
+                );
+
+                if (isInvalidStored) {
+                  return (
+                    <div
+                      key={key}
+                      className="flex items-center justify-between rounded-md border border-error/30 bg-error/5 px-3 py-2.5"
+                    >
+                      <div className="min-w-0 flex-1">
+                        <div className="truncate text-sm text-text-bright">{key}</div>
+                        <div className="truncate text-xs text-text-dimmed">
+                          org: {formatStoredValue(invalidStored)} (
+                          {INVALID_VALUE_LABEL[key] ?? "invalid"}) · global: {globalDisplay}
+                        </div>
+                      </div>
+                      {locked && effect === "derived" ? (
+                        <LockClosedIcon className="size-4 text-text-faint" />
+                      ) : (
+                        <Button variant="minimal/small" onClick={() => unsetFlag(key)}>
+                          unset
+                        </Button>
+                      )}
+                    </div>
+                  );
+                }
+
                 if (locked) {
+                  const hasOrgValue = key in overrides;
+                  const orgValue = overrides[key];
+                  const orgWorkerGroup =
+                    isWorkerGroup && hasOrgValue
+                      ? data.workerGroups?.find((group) => group.id === orgValue)
+                      : undefined;
+                  const orgDisplay = orgWorkerGroup
+                    ? `${orgWorkerGroup.name} (${String(orgValue).slice(0, 8)}...)`
+                    : formatStoredValue(orgValue);
+                  const canUnset = hasOrgValue && effect !== "derived";
+
                   return (
                     <div
                       key={key}
-                      className="flex items-center justify-between rounded-md border border-transparent bg-background-hover px-3 py-2.5"
+                      className={cn(
+                        "flex items-center justify-between rounded-md border px-3 py-2.5",
+                        hasOrgValue
+                          ? "border-indigo-500/20 bg-indigo-500/5"
+                          : "border-transparent bg-background-hover"
+                      )}
                       title="Global-level setting - not editable per org"
                     >
                       <div className="min-w-0 flex-1">
-                        <div className="truncate text-sm text-text-dimmed">{key}</div>
-                        <div className="text-xs text-text-dimmed">global: {globalDisplay}</div>
+                        <div
+                          className={cn(
+                            "truncate text-sm",
+                            hasOrgValue ? "text-text-bright" : "text-text-dimmed"
+                          )}
+                        >
+                          {key}
+                        </div>
+                        {hasOrgValue ? (
+                          <div className="truncate text-xs text-text-dimmed">
+                            org: {orgDisplay} ({effect ? LOCKED_EFFECT_LABEL[effect] : "stored"}) ·
+                            global: {globalDisplay}
+                          </div>
+                        ) : (
+                          <div className="text-xs text-text-dimmed">global: {globalDisplay}</div>
+                        )}
                       </div>
-                      <LockClosedIcon className="size-4 text-text-faint" />
+                      {canUnset ? (
+                        <Button variant="minimal/small" onClick={() => unsetFlag(key)}>
+                          unset
+                        </Button>
+                      ) : (
+                        <LockClosedIcon className="size-4 text-text-faint" />
+                      )}
                     </div>
                   );
                 }

apps/webapp/app/routes/admin.api.v1.orgs.$organizationId.feature-flags.ts

@@ -7,7 +7,11 @@ import { prisma } from "~/db.server";
 import { requireAdminApiRequest } from "~/services/personalAccessToken.server";
 import { controlPlaneResolver } from "~/v3/runOpsMigration/controlPlaneResolver.server";
 import { selectMintBaselineSource, stampMintKindFlip } from "~/v3/runOpsMigration/mintFlipGrace";
-import { validatePartialFeatureFlags } from "~/v3/featureFlags";
+import {
+  isPlainFlagObject,
+  parseStoredOrgFlags,
+  validatePartialFeatureFlags,
+} from "~/v3/featureFlags";
 import { flags as getGlobalFlags } from "~/v3/featureFlags.server";
 
 const ParamsSchema = z.object({
@@ -34,11 +38,7 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
     return json({ error: "Organization not found" }, { status: 404 });
   }
 
-  const flagsResult = organization.featureFlags
-    ? validatePartialFeatureFlags(organization.featureFlags as Record<string, unknown>)
-    : { success: false as const };
-
-  const featureFlags = flagsResult.success ? flagsResult.data : {};
+  const featureFlags = parseStoredOrgFlags(organization.featureFlags).valid;
 
   return json({
     organizationId: organization.id,
@@ -89,10 +89,9 @@ export async function action({ request, params }: ActionFunctionArgs) {
       }
 
       const existingRaw = rows[0].featureFlags as Record<string, unknown> | null;
-      const existingResult = existingRaw
-        ? validatePartialFeatureFlags(existingRaw)
-        : ({ success: false } as const);
-      const existingData = existingResult.success ? existingResult.data : {};
+      // Merge onto the raw object: keys this release doesn't know, or values that no longer
+      // validate, belong to the org and must survive an unrelated write.
+      const existingData = isPlainFlagObject(existingRaw) ? existingRaw : {};
 
       // Stamp the flip from the control-plane DB clock so the grace-window cutover is anchored to
       // one authoritative time source, not whichever webapp process handled this request.
@@ -130,15 +129,11 @@ export async function action({ request, params }: ActionFunctionArgs) {
     // Org feature flags are embedded in every env of the org; drop all its cached env rows.
     controlPlaneResolver.invalidateOrganization(organizationId);
 
-    const updatedFlagsResult = updatedOrganization.featureFlags
-      ? validatePartialFeatureFlags(updatedOrganization.featureFlags as Record<string, unknown>)
-      : { success: false as const };
-
     return json({
       success: true,
       organizationId: updatedOrganization.id,
       organizationSlug: updatedOrganization.slug,
-      featureFlags: updatedFlagsResult.success ? updatedFlagsResult.data : {},
+      featureFlags: parseStoredOrgFlags(updatedOrganization.featureFlags).valid,
     });
   } catch (error) {
     return json(

apps/webapp/app/routes/admin.api.v2.orgs.$organizationId.feature-flags.ts

@@ -10,8 +10,10 @@ import { selectMintBaselineSource, stampMintKindFlip } from "~/v3/runOpsMigratio
 import { flags as getGlobalFlags } from "~/v3/featureFlags.server";
 import {
   FEATURE_FLAG,
-  validatePartialFeatureFlags,
   getAllFlagControlTypes,
+  isPlainFlagObject,
+  mergeReplacedOrgFlags,
+  parseStoredOrgFlags,
 } from "~/v3/featureFlags";
 import { featuresForRequest } from "~/features.server";
 
@@ -69,11 +71,9 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
     throw new Response("Organization not found", { status: 404 });
   }
 
-  const orgFlagsResult = organization.featureFlags
-    ? validatePartialFeatureFlags(organization.featureFlags as Record<string, unknown>)
-    : ({ success: false } as const);
-
-  const orgFlags = orgFlagsResult.success ? orgFlagsResult.data : {};
+  const { valid: orgFlags, invalid: invalidOrgFlags } = parseStoredOrgFlags(
+    organization.featureFlags
+  );
   const controlTypes = getAllFlagControlTypes();
 
   // Resolve worker group name for display
@@ -98,6 +98,7 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
       slug: organization.slug,
     },
     orgFlags,
+    invalidOrgFlags,
     globalFlags,
     controlTypes,
     workerGroupName,
@@ -127,42 +128,13 @@ export async function action({ request, params }: ActionFunctionArgs) {
     return json({ error: "Invalid JSON body" }, { status: 400 });
   }
 
-  if (
-    body === null ||
-    (typeof body === "object" && !Array.isArray(body) && Object.keys(body).length === 0)
-  ) {
-    // Clear all flags. No grace stamp (nothing to flip) and no read-then-write race.
-    try {
-      await prisma.organization.update({
-        where: { id: organizationId },
-        data: { featureFlags: Prisma.JsonNull },
-      });
-    } catch (e) {
-      if (e instanceof Prisma.PrismaClientKnownRequestError && e.code === "P2025") {
-        throw new Response("Organization not found", { status: 404 });
-      }
-      throw e;
-    }
-
-    controlPlaneResolver.invalidateOrganization(organizationId);
-    return json({ success: true });
-  }
-
-  const validationResult = validatePartialFeatureFlags(body as Record<string, unknown>);
-  if (!validationResult.success) {
-    return json(
-      { error: "Invalid feature flags", details: validationResult.error.issues },
-      { status: 400 }
-    );
+  // null (the dialog with nothing set) clears every known flag. Stored keys this release
+  // doesn't know survive it, like any other save: the dialog never showed them.
+  const requestedBody = body === null ? {} : body;
+  if (!isPlainFlagObject(requestedBody)) {
+    return json({ error: "Invalid feature flags" }, { status: 400 });
   }
 
-  // Derived grace-stamp fields are computed server-side; never trust them from the body.
-  const {
-    runOpsMintKindPrev: _ignoredPrev,
-    runOpsMintKindFlippedAt: _ignoredFlippedAt,
-    ...requestedFlags
-  } = validationResult.data;
-
   // Seed the flip baseline from the current GLOBAL mint flags so an org's FIRST per-org override
   // is graced from the currently-effective global kind, not the hardcoded default "cuid".
   const globalFlags = (await getGlobalFlags()) as Record<string, unknown>;
@@ -174,11 +146,24 @@ export async function action({ request, params }: ActionFunctionArgs) {
       SELECT "featureFlags" FROM "Organization" WHERE "id" = ${organizationId} FOR UPDATE`;
 
     if (rows.length === 0) {
-      return false;
+      return { status: "not_found" } as const;
     }
 
     const existingRaw = rows[0].featureFlags as Record<string, unknown> | null;
 
+    // Validated against the stored row, so an unchanged invalid value can be sent back as is.
+    const merged = mergeReplacedOrgFlags(requestedBody, existingRaw);
+    if (!merged.success) {
+      return { status: "rejected", rejectedKeys: merged.rejectedKeys } as const;
+    }
+
+    // Derived grace-stamp fields are computed server-side; never trust them from the body.
+    const {
+      runOpsMintKindPrev: _ignoredPrev,
+      runOpsMintKindFlippedAt: _ignoredFlippedAt,
+      ...requestedFlags
+    } = merged.flags;
+
     // Anchor the flip stamp to the control-plane DB clock (see the v1 route), not this process's.
     const [{ now: controlPlaneNow }] = await tx.$queryRaw<{ now: Date }[]>`SELECT now() AS now`;
 
@@ -191,16 +176,29 @@ export async function action({ request, params }: ActionFunctionArgs) {
 
     await tx.organization.update({
       where: { id: organizationId },
-      data: { featureFlags: stamped as Prisma.InputJsonValue },
+      data: {
+        featureFlags:
+          Object.keys(stamped).length === 0 ? Prisma.JsonNull : (stamped as Prisma.InputJsonValue),
+      },
     });
 
-    return true;
+    return { status: "updated" } as const;
   });
 
-  if (!updated) {
+  if (updated.status === "not_found") {
     throw new Response("Organization not found", { status: 404 });
   }
 
+  if (updated.status === "rejected") {
+    return json(
+      {
+        error: `Invalid feature flags: ${updated.rejectedKeys.join(", ")}`,
+        details: updated.rejectedKeys.map((key) => ({ path: [key], message: "Invalid value" })),
+      },
+      { status: 400 }
+    );
+  }
+
   // Org feature flags are embedded in every env of the org; drop all its cached env rows.
   controlPlaneResolver.invalidateOrganization(organizationId);