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

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

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/BillingAlertsSection.tsx

@@ -53,8 +53,7 @@ export const billingAlertsSchema = z.object({
     const values = typeof i === "string" ? [i] : Array.isArray(i) ? i : [];
     return values
       .filter((v) => v !== "")
-      .map((v) => Number(v))
-      .filter((n) => Number.isFinite(n));
+      .map((v) => Number(v));
   }, z.number().array().refine(thresholdValuesAreUnique, "Each alert must be unique")),
 });
 

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>
   );
 }

apps/webapp/app/components/billing/billingAlertsFormat.ts

@@ -18,7 +18,7 @@ export type BillingLimitMode = "plan" | "custom" | "none";
 
 export function getBillingLimitMode(billingLimit: BillingLimitResult): BillingLimitMode {
   if (!billingLimit.isConfigured) {
-    return "plan";
+    return "none";
   }
   return billingLimit.mode;
 }
@@ -240,14 +240,16 @@ export function normalizeBillingAlertsFromApi(apiAlerts: {
   // Platform API stores amount in cents.
   let amountDollars = rawAmount / 100;
 
-  // Legacy percentage alerts sometimes stored plan dollars directly (e.g. 100 for $100).
-  // Never apply to absolute dollar alerts — those use a fixed $1 base (100 cents).
+  // Legacy percentage alerts sometimes stored plan dollars directly (e.g. 100 for $100)
+  // with whole-number percents (10, 50, 80). New saves store cents and fractional levels
+  // (0.75, 0.9) via thresholdsToAlertPayload — never treat those as legacy dollars.
   if (
     rawAmount !== ABSOLUTE_ALERT_BASE_CENTS &&
     Number.isFinite(rawAmount) &&
     rawAmount >= 10 &&
     rawAmount / 100 < 10 &&
-    alertLevels.length > 0
+    alertLevels.length > 0 &&
+    !usesFractionAlertLevelFormat(alertLevels)
   ) {
     amountDollars = rawAmount;
   }
@@ -311,11 +313,8 @@ export function storedAlertsToThresholds(
     return [];
   }
 
-  // Legacy percentage alerts keep their saved base amount even if billing limit changed.
-  if (
-    percentageAlertAmountMatches(amountCents, effectiveLimitCents, planLimitCents) ||
-    amountCents > 0
-  ) {
+  // Saved percentage alerts keep their thresholds whenever a positive base amount is stored.
+  if (amountCents > 0) {
     return uiThresholds.slice(0, MAX_PERCENTAGE_ALERTS);
   }
 

apps/webapp/app/components/billing/selectOrgBanner.ts

@@ -31,14 +31,16 @@ export function selectOrgBanner(input: {
     if (status === "grace") {
       return OrgBannerKind.LimitGrace;
     }
-  } else if (billingLimit && !billingLimit.isConfigured && showSelfServe) {
-    return OrgBannerKind.NoLimitConfigured;
   }
 
   if (hasExceededFreeTier) {
     return OrgBannerKind.Upgrade;
   }
 
+  if (billingLimit && !billingLimit.isConfigured && showSelfServe) {
+    return OrgBannerKind.NoLimitConfigured;
+  }
+
   if (showEnvironmentWarning) {
     return OrgBannerKind.EnvironmentWarning;
   }

apps/webapp/app/components/layout/AppLayout.tsx

@@ -1,3 +1,4 @@
+import { forwardRef } from "react";
 import { cn } from "~/utils/cn";
 
 /** This container is used to surround the entire app, it correctly places the nav bar */
@@ -34,17 +35,17 @@ export function PageContainer({
   );
 }
 
-export function PageBody({
-  children,
-  scrollable = true,
-  className,
-}: {
-  children: React.ReactNode;
-  scrollable?: boolean;
-  className?: string;
-}) {
+export const PageBody = forwardRef<
+  HTMLDivElement,
+  {
+    children: React.ReactNode;
+    scrollable?: boolean;
+    className?: string;
+  }
+>(function PageBody({ children, scrollable = true, className }, ref) {
   return (
     <div
+      ref={ref}
       className={cn(
         scrollable
           ? "overflow-y-auto p-3 scrollbar-thin scrollbar-track-transparent scrollbar-thumb-charcoal-600"
@@ -55,7 +56,7 @@ export function PageBody({
       {children}
     </div>
   );
-}
+});
 
 export function MainCenteredContainer({
   children,

apps/webapp/app/entry.server.tsx

@@ -10,7 +10,7 @@ import { PassThrough } from "stream";
 import * as Worker from "~/services/worker.server";
 import { initMollifierDrainerWorker } from "~/v3/mollifierDrainerWorker.server";
 import { initMollifierStaleSweepWorker } from "~/v3/mollifierStaleSweepWorker.server";
-import "~/v3/billingLimitWorker.server";
+import { initBillingLimitWorker } from "~/v3/billingLimitWorker.server";
 import { bootstrap } from "./bootstrap";
 import { LocaleContextProvider } from "./components/primitives/LocaleProvider";
 import {
@@ -236,6 +236,7 @@ Worker.init().catch((error) => {
 
 initMollifierDrainerWorker();
 initMollifierStaleSweepWorker();
+initBillingLimitWorker();
 
 bootstrap().catch((error) => {
   logError(error);

apps/webapp/app/hooks/useOrganizations.ts

@@ -95,3 +95,11 @@ export function useBillingLimit(matches?: UIMatch[]) {
   });
   return data?.billingLimit;
 }
+
+export function useCanManageBilling(matches?: UIMatch[]) {
+  const data = useTypedMatchesData<typeof orgLoader>({
+    id: "routes/_app.orgs.$organizationSlug",
+    matches,
+  });
+  return data?.canManageBilling === true;
+}

apps/webapp/app/hooks/useScrollContainerToTop.ts

@@ -0,0 +1,14 @@
+import { useLocation } from "@remix-run/react";
+import { useEffect, useRef } from "react";
+
+/** Scroll a page body container back to the top when navigating to a route. */
+export function useScrollContainerToTop<T extends HTMLElement>() {
+  const ref = useRef<T>(null);
+  const location = useLocation();
+
+  useEffect(() => {
+    ref.current?.scrollTo(0, 0);
+  }, [location.key]);
+
+  return ref;
+}

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.queues/route.tsx

@@ -10,7 +10,6 @@ import {
 import { DialogClose } from "@radix-ui/react-dialog";
 import { Form, useNavigation, useSearchParams, type MetaFunction } from "@remix-run/react";
 import { type ActionFunctionArgs, type LoaderFunctionArgs } from "@remix-run/server-runtime";
-import { EnvironmentPauseSource } from "@trigger.dev/database";
 import type { RuntimeEnvironmentType } from "@trigger.dev/database";
 import type { QueueItem } from "@trigger.dev/core/v3/schemas";
 import { useEffect, useState } from "react";
@@ -68,6 +67,7 @@ import { EnvironmentQueuePresenter } from "~/presenters/v3/EnvironmentQueuePrese
 import { QueueListPresenter } from "~/presenters/v3/QueueListPresenter.server";
 import { requireUserId } from "~/services/session.server";
 import { cn } from "~/utils/cn";
+import { ENVIRONMENT_PAUSE_SOURCE_BILLING_LIMIT } from "~/utils/environmentPauseSource";
 import {
   concurrencyPath,
   docsPath,
@@ -183,24 +183,22 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
   }
 
   switch (action) {
-    case "environment-pause":
+    case "environment-pause": {
       const pauseService = new PauseEnvironmentService();
-      {
-        const result = await pauseService.call(environment, "paused");
-        if (!result.success) {
-          return redirectWithErrorMessage(redirectPath, request, result.error);
-        }
+      const result = await pauseService.call(environment, "paused");
+      if (!result.success) {
+        return redirectWithErrorMessage(redirectPath, request, result.error);
       }
       return redirectWithSuccessMessage(redirectPath, request, "Environment paused");
-    case "environment-resume":
+    }
+    case "environment-resume": {
       const resumeService = new PauseEnvironmentService();
-      {
-        const result = await resumeService.call(environment, "resumed");
-        if (!result.success) {
-          return redirectWithErrorMessage(redirectPath, request, result.error);
-        }
+      const result = await resumeService.call(environment, "resumed");
+      if (!result.success) {
+        return redirectWithErrorMessage(redirectPath, request, result.error);
       }
       return redirectWithSuccessMessage(redirectPath, request, "Environment resumed");
+    }
     case "queue-pause":
     case "queue-resume": {
       const friendlyId = formData.get("friendlyId");
@@ -357,7 +355,8 @@ export default function Page() {
               animate
               accessory={
                 <div className="flex items-start gap-1">
-                  {environment.runsEnabled && env.pauseSource !== EnvironmentPauseSource.BILLING_LIMIT ? (
+                  {environment.runsEnabled &&
+                  env.pauseSource !== ENVIRONMENT_PAUSE_SOURCE_BILLING_LIMIT ? (
                     <EnvironmentPauseResumeButton env={env} />
                   ) : null}
                   <LinkButton