feat: report agent runtime hours usage in entitlements (#27985)

Populate `FeatureAgentRuntimeHours.Actual` on every entitlements refresh
for licenses that grant the feature. A new
`GetTotalUsageHBAgentRuntimeV1` query sums `runtime_ms` over the
license's usage period, reading `usage_events` directly:
`hb_agent_runtime_v1` is exactly one row per hourly bucket
deployment-wide with `created_at` at the bucket start, enforced by the
unique partial index introduced in #27983.

The measurement reuses the shared `measureUsage` policy from #27984
through a new `AgentRuntimeMsFn` closure (usage publisher subject):
failures publish the stable
`LicenseAgentRuntimeUsageUnavailableErrorText` and log the cause. Usage
is floored to whole hours, matching the unit of the
`agent_runtime_hours_*` claims, and at most one warning is emitted per
refresh: reaching the allocation supersedes the advisory soft limit. The
dashboard renders the soft-limit advisory muted without a sales link and
treats the runtime usage-unavailable text as a diagnostic.

**Precise usage.** `Feature.ActualMs` (JSON `actual_ms`), set only for
`agent_runtime_hours`, carries the exact stored milliseconds backing the
floored `Actual` so clients can render fractional hours (e.g. `10.3`).
It has the same freshness as `Actual`; the whole-hour warning thresholds
are unchanged.

**Unlimited licenses.** A license minted with the unlimited (`-1`)
allocation decodes to an enabled feature with a nil `Limit` (#27984), so
the warning write-back now guards the allocation dereference: no
thresholds can exist for an unlimited license, so no runtime hours
warning is ever emitted, while `Actual` is still measured and published.
`Feature.Compare` is unchanged; for usage-period features the
issued-at/end dates decide first, so a metered feature outranks an
unlimited one only on an exact timestamp tie, an edge pinned by a
`TestFeatureComparison` case and documented on
`decodeAgentRuntimeHours`.

**Grandfathered premium licenses.** Premium licenses without
`agent_runtime_hours_*` claims are now granted the feature disabled with
a zero limit over the license term, identical to an explicit
`allocation: 0`: usage is measured and published for every Premium
deployment, and chatd's pooled admission (#27902) caps concurrent
agentic chats until a license with a positive allocation is added. The
default carries a fixed early `UsagePeriod.IssuedAt` (2026-08-01, the
same mechanism as the managed-agents default) so any license actually
carrying the claims outranks it in the `AddFeature` merge regardless of
the licenses' relative issue dates; the constant must stay earlier than
the earliest legitimately issued claim-bearing license. Zero allocations
(explicit or grandfathered) emit no deployment-wide warning banner:
those deployments are steered by the in-page upgrade CTA and the
concurrency cap. Enterprise licenses are unchanged.

Part 3 of a 3-PR stack splitting up #27796 (see there for review
history). Stack: #27983 → #27984 → this PR.

Closes CODAGT-852.

site/src/api/typesGenerated.ts

@@ -5187,14 +5187,18 @@ export interface ExternalAuthUser {
 export interface Feature {
 	readonly entitlement: Entitlement;
 	readonly enabled: boolean;
+	/**
+	 * Limit is the maximum value the license grants for the feature, in the
+	 * feature's own unit. For FeatureAgentRuntimeHours, an enabled feature
+	 * with Limit omitted means the license grants unlimited runtime hours.
+	 */
 	readonly limit?: number;
 	/**
 	 * SoftLimit is the advisory warning threshold that accompanies Limit for
 	 * features whose license carries it. For these features, Limit carries
-	 * the purchased allocation.
-	 *
-	 * Only certain features set this field:
-	 * - FeatureAgentRuntimeHours
+	 * the purchased allocation; an unlimited allocation has no thresholds,
+	 * so SoftLimit is omitted alongside the omitted Limit. Only
+	 * FeatureAgentRuntimeHours sets this field.
 	 */
 	readonly soft_limit?: number;
 	/**
@@ -5203,18 +5207,30 @@ export interface Feature {
 	 * features that use these thresholds.
 	 */
 	readonly hard_limit?: number;
+	/**
+	 * Actual is the usage measured against Limit, when known: a
+	 * point-in-time count for most features, or usage accumulated over
+	 * UsagePeriod for features that set one. Its unit matches Limit's;
+	 * FeatureAgentRuntimeHours reports whole hours floored from the
+	 * recorded milliseconds, with the precise value available in
+	 * ActualMs. FeatureAgentRuntimeHours usage can trail by roughly one
+	 * hour because the current hour is not emitted, plus the entitlement
+	 * refresh interval.
+	 */
 	readonly actual?: number;
+	/**
+	 * ActualMs is the precise usage backing Actual, in milliseconds, for
+	 * features measured in time. It has the same freshness as Actual.
+	 * Only FeatureAgentRuntimeHours sets this field.
+	 */
+	readonly actual_ms?: number;
 	/**
 	 * UsagePeriod denotes that the usage is a counter that accumulates over
 	 * this period (and most likely resets with the issuance of the next
-	 * license).
-	 *
-	 * These dates are determined from the license that this entitlement comes
-	 * from, see enterprise/coderd/license/license.go.
-	 *
-	 * Only certain features set these fields:
-	 * - FeatureManagedAgentLimit
-	 * - FeatureAgentRuntimeHours
+	 * license). These dates are determined from the license that this
+	 * entitlement comes from, see enterprise/coderd/license/license.go.
+	 * Only FeatureManagedAgentLimit and FeatureAgentRuntimeHours set this
+	 * field.
 	 */
 	readonly usage_period?: UsagePeriod;
 }
@@ -5763,10 +5779,28 @@ export const LicenseAIGovernance90PercentWarningText =
 export const LicenseAIGovernanceOverLimitWarningText =
 	"Your organization is using %d of %d AI Governance add-on seats (%d over the limit).";
 
+// From codersdk/licenses.go
+export const LicenseAgentRuntimeHoursAllocationReachedWarningText =
+	"Your deployment has used %d of the %d Coder Agent runtime hours included in the current license term.";
+
 // From codersdk/licenses.go
 export const LicenseAgentRuntimeHoursClaimsIgnoredWarningText =
 	"A license contains unusable Coder Agent runtime hour claims, which were ignored. The rest of that license is unaffected. Check the coderd logs for the affected license and claims, and contact support to have the license re-issued.";
 
+// From codersdk/licenses.go
+/**
+ * The dashboard's LicenseBanner matches this text's pre-placeholder
+ * prefix to render it muted and without a sales link, so the license
+ * warning texts must stay pairwise distinct before their first
+ * placeholder. See TestLicenseAgentRuntimeHoursWarningTexts.
+ */
+export const LicenseAgentRuntimeHoursSoftLimitWarningText =
+	"Your deployment is approaching its Coder Agent runtime hours allocation: %d of the %d hours included in the current license term are used, at or above the advisory soft limit of %d hours.";
+
+// From codersdk/licenses.go
+export const LicenseAgentRuntimeUsageUnavailableErrorText =
+	"Unable to determine Coder Agent runtime usage. Reported runtime hours are unavailable until the next successful refresh; workspaces are unaffected. Check the coderd logs for details.";
+
 // From codersdk/licenses.go
 export const LicenseExpiryClaim = "license_expires";
 

site/src/modules/dashboard/LicenseBanner/LicenseBanner.tsx

@@ -1,6 +1,8 @@
 import type { FC } from "react";
 import {
 	LicenseAgentRuntimeHoursClaimsIgnoredWarningText,
+	LicenseAgentRuntimeHoursSoftLimitWarningText,
+	LicenseAgentRuntimeUsageUnavailableErrorText,
 	LicenseAIGovernance90PercentWarningText,
 	LicenseAIGovernanceOverLimitWarningText,
 	LicenseManagedAgentLimitExceededWarningText,
@@ -18,6 +20,8 @@ const aiGovernanceOverLimitWarningPrefix =
 	LicenseAIGovernanceOverLimitWarningText.split("%d")[0];
 const aiGovernanceNearLimitWarningPrefix =
 	LicenseAIGovernance90PercentWarningText.split("%d%%")[0];
+const agentRuntimeSoftLimitWarningPrefix =
+	LicenseAgentRuntimeHoursSoftLimitWarningText.split("%d")[0];
 const AI_GOVERNANCE_NEAR_LIMIT_FALLBACK_MESSAGE =
 	"You are approaching your AI Governance add-on seat limit.";
 
@@ -26,8 +30,12 @@ const isAIGovernanceWarning = (message: string): boolean =>
 	message.startsWith(aiGovernanceOverLimitWarningPrefix);
 
 // Substitutes the given values into the template's %d placeholders in order.
-// No other fmt verb, width, or flag is implemented.
-const formatLicenseMessage = (template: string, ...values: number[]): string =>
+// No other fmt verb, width, or flag is implemented. Exported for the
+// stories, so what they pin is what production renders.
+export const formatLicenseMessage = (
+	template: string,
+	...values: number[]
+): string =>
 	values.reduce(
 		(message, value) => message.replace("%d", `${value}`),
 		template,
@@ -37,6 +45,7 @@ const formatLicenseMessage = (template: string, ...values: number[]): string =>
 // usage itself. They render muted, without the exceedance heading or a sales
 // link, even when they arrive via entitlements.errors.
 const diagnosticMessages: readonly string[] = [
+	LicenseAgentRuntimeUsageUnavailableErrorText,
 	LicenseAgentRuntimeHoursClaimsIgnoredWarningText,
 ];
 
@@ -44,9 +53,10 @@ const isDiagnosticMessage = (message: string): boolean =>
 	diagnosticMessages.includes(message);
 
 // Advisories render muted to stay visually distinct from warnings that
-// demand action, such as exceeding a license limit.
+// demand action, such as reaching the runtime hours allocation.
 const isAdvisoryMessage = (message: string): boolean =>
-	message.startsWith(aiGovernanceNearLimitWarningPrefix);
+	message.startsWith(aiGovernanceNearLimitWarningPrefix) ||
+	message.startsWith(agentRuntimeSoftLimitWarningPrefix);
 
 const aiGovernanceOverLimitMessage = (
 	feature: ReturnType<
@@ -139,6 +149,11 @@ const messageLink = (message: string): LicenseBannerLink | undefined => {
 			showExternalIcon: false,
 		};
 	}
+	// The soft-limit advisory fires inside the purchased allocation, so it
+	// does not get a sales link.
+	if (message.startsWith(agentRuntimeSoftLimitWarningPrefix)) {
+		return undefined;
+	}
 	return {
 		href: "mailto:sales@coder.com",
 		label: "Contact sales@coder.com.",

site/src/modules/dashboard/LicenseBanner/LicenseBannerView.stories.tsx

@@ -2,7 +2,10 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
 import { expect, within } from "storybook/test";
 import {
 	type Entitlements,
+	LicenseAgentRuntimeHoursAllocationReachedWarningText,
 	LicenseAgentRuntimeHoursClaimsIgnoredWarningText,
+	LicenseAgentRuntimeHoursSoftLimitWarningText,
+	LicenseAgentRuntimeUsageUnavailableErrorText,
 	LicenseAIGovernance90PercentWarningText,
 	LicenseManagedAgentLimitExceededWarningText,
 	LicenseTelemetryRequiredErrorText,
@@ -16,7 +19,7 @@ import {
 } from "#/testHelpers/entities";
 import { docs } from "#/utils/docs";
 import { DashboardContext, type DashboardValue } from "../DashboardProvider";
-import { LicenseBanner } from "./LicenseBanner";
+import { formatLicenseMessage, LicenseBanner } from "./LicenseBanner";
 import { LicenseBannerView } from "./LicenseBannerView";
 
 const meta: Meta<typeof LicenseBannerView> = {
@@ -60,7 +63,7 @@ export const TwoWarnings: Story = {
 		const canvas = within(canvasElement);
 		await expect(canvas.getByRole("status")).toBeInTheDocument();
 		await expect(
-			canvas.getByText("Your license limits have been exceeded"),
+			canvas.getByText("Your license limits have been reached"),
 		).toBeInTheDocument();
 		await expect(
 			canvas.queryByRole("button", { name: "Show more" }),
@@ -295,6 +298,83 @@ export const AIGovernanceOverLimitGracePeriod: Story = {
 	},
 };
 
+export const AgentRuntimeHoursSoftLimit: Story = {
+	render: () =>
+		renderLicenseBanner({
+			warnings: [
+				formatLicenseMessage(
+					LicenseAgentRuntimeHoursSoftLimitWarningText,
+					90,
+					100,
+					80,
+				),
+			],
+		}),
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		const banner = canvas.getByRole("status");
+		await expect(banner).toHaveTextContent(
+			"Your deployment is approaching its Coder Agent runtime hours allocation: 90 of the 100 hours included in the current license term are used, at or above the advisory soft limit of 80 hours.",
+		);
+		await expect(
+			canvas.queryByRole("link", { name: /Contact sales@coder\.com/i }),
+		).not.toBeInTheDocument();
+	},
+};
+
+export const AgentRuntimeHoursAllocationReached: Story = {
+	render: () =>
+		renderLicenseBanner({
+			warnings: [
+				formatLicenseMessage(
+					LicenseAgentRuntimeHoursAllocationReachedWarningText,
+					100,
+					100,
+				),
+			],
+		}),
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		const banner = canvas.getByRole("status");
+		await expect(banner).toHaveTextContent(
+			"Your deployment has used 100 of the 100 Coder Agent runtime hours included in the current license term.",
+		);
+		await expect(
+			canvas.getByRole("link", { name: /Contact sales@coder\.com/i }),
+		).toHaveAttribute("href", "mailto:sales@coder.com");
+	},
+};
+
+// The allocation warning fires at exact equality (actual >= allocation), so
+// a multi-message banner containing it must use a heading that stays
+// accurate when the allocation is reached but not exceeded.
+export const AgentRuntimeHoursAllocationReachedWithDiagnostic: Story = {
+	render: () =>
+		renderLicenseBanner({
+			errors: [LicenseAgentRuntimeUsageUnavailableErrorText],
+			warnings: [
+				formatLicenseMessage(
+					LicenseAgentRuntimeHoursAllocationReachedWarningText,
+					100,
+					100,
+				),
+			],
+		}),
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		const banner = canvas.getByRole("status");
+		await expect(
+			canvas.getByText("Your license limits have been reached"),
+		).toBeInTheDocument();
+		await expect(banner).toHaveTextContent(
+			"Your deployment has used 100 of the 100 Coder Agent runtime hours included in the current license term.",
+		);
+		await expect(banner).toHaveTextContent(
+			LicenseAgentRuntimeUsageUnavailableErrorText,
+		);
+	},
+};
+
 // Each diagnostic pins role=status (not alert) and a suppressed sales
 // link. Background mutedness is covered by the visual snapshot.
 const playMutedDiagnostic =
@@ -308,6 +388,14 @@ const playMutedDiagnostic =
 		).not.toBeInTheDocument();
 	};
 
+export const AgentRuntimeUsageUnavailable: Story = {
+	render: () =>
+		renderLicenseBanner({
+			errors: [LicenseAgentRuntimeUsageUnavailableErrorText],
+		}),
+	play: playMutedDiagnostic(LicenseAgentRuntimeUsageUnavailableErrorText),
+};
+
 export const AgentRuntimeHoursClaimsIgnored: Story = {
 	render: () =>
 		renderLicenseBanner({
@@ -316,10 +404,12 @@ export const AgentRuntimeHoursClaimsIgnored: Story = {
 	play: playMutedDiagnostic(LicenseAgentRuntimeHoursClaimsIgnoredWarningText),
 };
 
-// An all-diagnostic banner must not claim license limits were exceeded.
+// An all-diagnostic banner must not claim license limits were exceeded,
+// even when a diagnostic arrives via entitlements.errors.
 export const UsageDiagnosticsOnlyHeading: Story = {
 	render: () =>
 		renderLicenseBanner({
+			errors: [LicenseAgentRuntimeUsageUnavailableErrorText],
 			warnings: [LicenseAgentRuntimeHoursClaimsIgnoredWarningText],
 		}),
 	play: async ({ canvasElement }) => {
@@ -327,7 +417,7 @@ export const UsageDiagnosticsOnlyHeading: Story = {
 		await expect(canvas.getByRole("status")).toBeInTheDocument();
 		await expect(canvas.getByText("License notices")).toBeInTheDocument();
 		await expect(
-			canvas.queryByText("Your license limits have been exceeded"),
+			canvas.queryByText("Your license limits have been reached"),
 		).not.toBeInTheDocument();
 		await expect(
 			canvas.queryByText("License errors require attention"),

site/src/modules/dashboard/LicenseBanner/LicenseBannerView.tsx

@@ -75,13 +75,15 @@ const getBannerVariant = (
 };
 
 // The muted "warning" variant means every message is an advisory or
-// diagnostic, so the heading must not assert exceedance.
+// diagnostic, so the heading must not assert a limit was hit. The prominent
+// heading says "reached" rather than "exceeded" because some limit warnings
+// fire at exact equality, which "reached" covers in both cases.
 const bannerTitle = (variant: LicenseBannerVariant): string => {
 	switch (variant) {
 		case "error":
 			return "License errors require attention";
 		case "warningProminent":
-			return "Your license limits have been exceeded";
+			return "Your license limits have been reached";
 		case "warning":
 			return "License notices";
 	}