feat(webapp): show the billing limit on the usage page, with docs and tests

Add the usage-bar marker, documentation, and test coverage.

Verified all billing + devBranch test suites load with REDIS_HOST unset.

Author: kathiekiwi

.server-changes/billing-limits.md

@@ -7,3 +7,18 @@ Add billing limits. Customers set a spend cap; when usage crosses it, billable
 environments pause for a grace period, new triggers are rejected once it ends,
 and a recovery flow resumes or cancels the queued backlog. Reconciliation keeps
 the webapp converged to billing's state.
+
+## Manual pause during billing enforcement
+
+While `pauseSource=BILLING_LIMIT`, manual resume is rejected and manual pause is
+a silent no-op (`PauseEnvironmentService` returns success with state `paused`).
+We do not stack a manual pause on top of billing enforcement because resolve
+converge unpauses all `BILLING_LIMIT`-paused environments for the org.
+
+API callers that pause during enforcement should expect the environment to
+resume when the billing limit is resolved. The queues UI hides pause/resume in
+this state; see `manualPauseEnvironmentGuard.server.ts`.
+
+The admin `runs.enable` endpoint skips billing-paused environments when
+re-enabling or disabling org runs (returns them in `skipped`, not `failures` or
+the update count). They resume only after the billing limit is resolved.

apps/webapp/app/components/billing/AnimatedOrgBannerBar.tsx

@@ -26,7 +26,7 @@ export function AnimatedOrgBannerBar({
             "flex h-10 items-center justify-between overflow-hidden py-0 pl-3 pr-2",
             variant === "warning"
               ? "border-y border-amber-400/20 bg-warning/20"
-              : "border border-error bg-repeat"
+              : "border border-error bg-repeat",
           )}
           style={
             variant === "error"

apps/webapp/app/components/billing/BillingAlertsSection.tsx

@@ -49,13 +49,13 @@ export const billingAlertsSchema = z.object({
 
     return [""];
   }, z.string().email().array().nonempty("At least one email is required")),
-  alertLevels: z.preprocess((i) => {
-    const values = typeof i === "string" ? [i] : Array.isArray(i) ? i : [];
-    return values
-      .filter((v) => v !== "")
-      .map((v) => Number(v))
-      .filter((n) => Number.isFinite(n));
-  }, z.number().array().refine(thresholdValuesAreUnique, "Each alert must be unique")),
+  alertLevels: z.preprocess(
+    (i) => {
+      const values = typeof i === "string" ? [i] : Array.isArray(i) ? i : [];
+      return values.filter((v) => v !== "").map((v) => Number(v));
+    },
+    z.number().array().refine(thresholdValuesAreUnique, "Each alert must be unique"),
+  ),
 });
 
 export type { BillingAlertsFormData } from "~/components/billing/billingAlertsFormat";
@@ -101,7 +101,7 @@ function isDuplicateThresholdRow(rows: ThresholdRow[], index: number): boolean {
   const parsed = Number(value);
   return rows.some(
     (row, rowIndex) =>
-      rowIndex !== index && !isEmptyThresholdRow(row.value) && Number(row.value) === parsed
+      rowIndex !== index && !isEmptyThresholdRow(row.value) && Number(row.value) === parsed,
   );
 }
 
@@ -136,27 +136,26 @@ export function BillingAlertsSection({
   const alertPreviewLimitCents = getAlertPreviewLimitCents(
     alerts,
     effectiveLimitCents,
-    planLimitCents
+    planLimitCents,
   );
   const maxAlerts = isPercentageMode ? MAX_PERCENTAGE_ALERTS : MAX_ABSOLUTE_ALERTS;
 
   const savedThresholds = useMemo(
     () => storedAlertsToThresholds(alerts, billingLimitMode, effectiveLimitCents, planLimitCents),
-    [alerts, billingLimitMode, effectiveLimitCents, planLimitCents]
+    [alerts, billingLimitMode, effectiveLimitCents, planLimitCents],
   );
   const savedEmails = useMemo(() => alerts.emails, [alerts.emails]);
   const hasLegacySpikes = useMemo(
-    () =>
-      hasLegacySpikeAlertLevels(alerts, billingLimitMode, effectiveLimitCents, planLimitCents),
-    [alerts, billingLimitMode, effectiveLimitCents, planLimitCents]
+    () => hasLegacySpikeAlertLevels(alerts, billingLimitMode, effectiveLimitCents, planLimitCents),
+    [alerts, billingLimitMode, effectiveLimitCents, planLimitCents],
   );
 
   const nextThresholdIdRef = useRef(savedThresholds.length);
   const [thresholdRows, setThresholdRows] = useState<ThresholdRow[]>(() =>
-    toThresholdRows(savedThresholds)
+    toThresholdRows(savedThresholds),
   );
   const [emailValues, setEmailValues] = useState<string[]>(
-    savedEmails.length > 0 ? [...savedEmails, ""] : [""]
+    savedEmails.length > 0 ? [...savedEmails, ""] : [""],
   );
   const actionData = useActionData<BillingAlertsActionData>();
   const alertsSubmission =
@@ -192,7 +191,7 @@ export function BillingAlertsSection({
 
   function updateThresholdRow(index: number, rawValue: string) {
     setThresholdRows((current) =>
-      current.map((row, rowIndex) => (rowIndex === index ? { ...row, value: rawValue } : row))
+      current.map((row, rowIndex) => (rowIndex === index ? { ...row, value: rawValue } : row)),
     );
   }
 
@@ -262,7 +261,7 @@ export function BillingAlertsSection({
                               if (e.target.value === "") return;
                               const clamped = Math.min(
                                 MAX_PERCENTAGE_THRESHOLD,
-                                Math.max(1, Number(e.target.value))
+                                Math.max(1, Number(e.target.value)),
                               );
                               if (String(clamped) !== e.target.value) {
                                 updateThresholdRow(index, String(clamped));
@@ -281,9 +280,9 @@ export function BillingAlertsSection({
                             {formatCurrency(
                               previewDollarAmountForPercent(
                                 Number.isFinite(parsed) ? parsed : 0,
-                                alertPreviewLimitCents
+                                alertPreviewLimitCents,
                               ),
-                              false
+                              false,
                             )}
                             )
                           </span>
@@ -343,7 +342,7 @@ export function BillingAlertsSection({
             {emailFields.map((email, index) => {
               const { defaultValue: _emailDefaultValue, ...emailInputProps } = conform.input(
                 email,
-                { type: "email" }
+                { type: "email" },
               );
 
               return (

apps/webapp/app/components/billing/BillingLimitConfigSection.tsx

@@ -79,7 +79,7 @@ export function isBillingLimitFormDirty(input: {
 export function getBillingLimitFormLastSubmission(
   submission: BillingLimitActionData["submission"] | undefined,
   mode: "none" | "plan" | "custom",
-  isDirty: boolean
+  isDirty: boolean,
 ) {
   if (!isDirty || !submission) {
     return undefined;
@@ -151,7 +151,7 @@ export function BillingLimitConfigSection({
   });
   const lastSubmission = useMemo(
     () => getBillingLimitFormLastSubmission(limitSubmission, mode, isDirty),
-    [limitSubmission, mode, isDirty]
+    [limitSubmission, mode, isDirty],
   );
 
   const [form, fields] = useForm({

apps/webapp/app/components/billing/BillingLimitResolveProgress.tsx

@@ -14,8 +14,7 @@ export function BillingLimitResolveProgress({
   return (
     <div className="space-y-3">
       <AnimatedCallout show variant="success">
-        Billing limit resolved. Environments are being unpaused — this usually takes a few
-        seconds.
+        Billing limit resolved. Environments are being unpaused — this usually takes a few seconds.
       </AnimatedCallout>
       {cancellingQueuedRuns && (
         <AnimatedCallout show variant="info">

apps/webapp/app/components/billing/OrgBanner.tsx

@@ -9,17 +9,19 @@ import {
   useOptionalOrganization,
   useOrganization,
   useBillingLimit,
+  useCanManageBilling,
 } from "~/hooks/useOrganizations";
 import { useOptionalProject, useProject } from "~/hooks/useProject";
 import { useShowSelfServe } from "~/hooks/useShowSelfServe";
 import { useCurrentPlan } from "~/routes/_app.orgs.$organizationSlug/route";
 import { v3BillingLimitsPath, v3BillingPath, v3QueuesPath } from "~/utils/pathBuilder";
+import { ENVIRONMENT_PAUSE_SOURCE_BILLING_LIMIT } from "~/utils/environmentPauseSource";
 
 function getUpgradeResetDate(): Date {
   const nextMonth = new Date();
-  nextMonth.setUTCMonth(nextMonth.getMonth() + 1);
   nextMonth.setUTCDate(1);
   nextMonth.setUTCHours(0, 0, 0, 0);
+  nextMonth.setUTCMonth(nextMonth.getUTCMonth() + 1);
   return nextMonth;
 }
 
@@ -41,7 +43,7 @@ export function OrgBanner() {
     project &&
     environment &&
     environment.paused &&
-    environment.pauseSource !== "BILLING_LIMIT"
+    environment.pauseSource !== ENVIRONMENT_PAUSE_SOURCE_BILLING_LIMIT
   );
   const isArchived = !!(organization && project && environment && environment.archivedAt);
 
@@ -77,30 +79,39 @@ export function OrgBanner() {
 
 function LimitRejectedBanner() {
   const organization = useOrganization();
+  const showSelfServe = useShowSelfServe();
+  const canManageBilling = useCanManageBilling();
+  const canResolve = showSelfServe && canManageBilling;
 
   return (
     <AnimatedOrgBannerBar
       show
       variant="error"
       action={
-        <LinkButton
-          variant="danger/small"
-          leadingIconClassName="px-0"
-          to={v3BillingLimitsPath(organization)}
-        >
-          Resolve
-        </LinkButton>
+        canResolve ? (
+          <LinkButton
+            variant="danger/small"
+            leadingIconClassName="px-0"
+            to={v3BillingLimitsPath(organization)}
+          >
+            Resolve
+          </LinkButton>
+        ) : undefined
       }
     >
       <span className="font-medium">Billing limit exceeded</span> — New triggers are currently
       blocked.
+      {!canResolve ? " Contact your organization administrator to resolve this issue." : null}
     </AnimatedOrgBannerBar>
   );
 }
 
 function LimitGraceBanner() {
   const organization = useOrganization();
   const billingLimit = useBillingLimit();
+  const showSelfServe = useShowSelfServe();
+  const canManageBilling = useCanManageBilling();
+  const canResolve = showSelfServe && canManageBilling;
 
   const graceEndsAt =
     billingLimit?.isConfigured && billingLimit.limitState.status === "grace"
@@ -112,35 +123,43 @@ function LimitGraceBanner() {
       show={graceEndsAt !== null}
       variant="error"
       action={
-        <LinkButton
-          variant="danger/small"
-          leadingIconClassName="px-0"
-          to={v3BillingLimitsPath(organization)}
-        >
-          Resolve
-        </LinkButton>
+        canResolve ? (
+          <LinkButton
+            variant="danger/small"
+            leadingIconClassName="px-0"
+            to={v3BillingLimitsPath(organization)}
+          >
+            Resolve
+          </LinkButton>
+        ) : undefined
       }
     >
       <span className="font-medium">Billing limit reached</span> — Queues have been paused. New runs
       will continue to queue until <DateTime date={graceEndsAt ?? new Date()} includeTime />.
+      {!canResolve ? " Contact your organization administrator to resolve this issue." : null}
     </AnimatedOrgBannerBar>
   );
 }
 
 function NoLimitConfiguredBanner() {
   const organization = useOrganization();
+  const canManageBilling = useCanManageBilling();
 
   return (
     <AnimatedOrgBannerBar
       show
       variant="warning"
       action={
-        <LinkButton variant="tertiary/small" to={v3BillingLimitsPath(organization)}>
-          Configure billing limit
-        </LinkButton>
+        canManageBilling ? (
+          <LinkButton variant="tertiary/small" to={v3BillingLimitsPath(organization)}>
+            Configure billing limit
+          </LinkButton>
+        ) : undefined
       }
     >
-      Protect your organization from unexpected usage spikes.
+      {canManageBilling
+        ? "Protect your organization from unexpected usage spikes."
+        : "Billing limits are not configured for this organization. Contact an organization administrator to configure them."}
     </AnimatedOrgBannerBar>
   );
 }