From 7b2079e11942f8ff6c7655b625fd177361bd9e3f Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Sun, 9 Aug 2026 13:10:09 +0000
Subject: [PATCH 01/20] feat(site): show total agent hours consumption on the
 licenses page

---
 .../LicensesSettingsPageView.stories.tsx      |  32 ++++
 .../LicensesSettingsPageView.tsx              |   3 +
 .../TotalAgentHoursCard.stories.tsx           | 176 ++++++++++++++++++
 .../TotalAgentHoursCard.tsx                   | 126 +++++++++++++
 4 files changed, 337 insertions(+)
 create mode 100644 site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
 create mode 100644 site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx
index afcd0065e34..9668b06f0b4 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx
@@ -27,6 +27,10 @@ const meta: Meta<typeof LicensesSettingsPageView> = {
 			enabled: false,
 			entitlement: "not_entitled",
 		} satisfies Feature,
+		agentRuntimeHoursFeature: {
+			enabled: false,
+			entitlement: "not_entitled",
+		} satisfies Feature,
 	},
 };
 
@@ -71,3 +75,31 @@ export const ActiveAIGovernanceAddOnUsage: Story = {
 		await expect(canvas.getByText("1,000")).toBeInTheDocument();
 	},
 };
+
+/** The Total agent hours panel renders full width, directly above Agent Workspace Builds. */
+export const TotalAgentHoursUsage: Story = {
+	args: {
+		agentRuntimeHoursFeature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 2000,
+			soft_limit: 1700,
+			actual: 435,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		const agentHoursHeading = canvas.getByRole("heading", {
+			name: "Total agent hours",
+		});
+		await expect(canvas.getByText("435")).toBeInTheDocument();
+		await expect(canvas.getByText("2,000")).toBeInTheDocument();
+		const managedAgentsSection = canvas.getByText(
+			"Agent Workspace Builds Disabled",
+		);
+		await expect(
+			agentHoursHeading.compareDocumentPosition(managedAgentsSection) &
+				Node.DOCUMENT_POSITION_FOLLOWING,
+		).toBeTruthy();
+	},
+};
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.tsx
index 5a46201f2e6..b2c99b41950 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.tsx
@@ -25,6 +25,7 @@ import { LicenseCard } from "./LicenseCard";
 import { LicenseSeatConsumptionChart } from "./LicenseSeatConsumptionChart";
 import { ManagedAgentsConsumption } from "./ManagedAgentsConsumption";
 import { SeatUsageBarCard } from "./SeatUsageBarCard";
+import { TotalAgentHoursCard } from "./TotalAgentHoursCard";
 
 type Props = {
 	showConfetti: boolean;
@@ -192,6 +193,8 @@ const LicensesSettingsPageView: FC<Props> = ({
 							/>
 						</div>
 
+						<TotalAgentHoursCard feature={agentRuntimeHoursFeature} />
+
 						<ManagedAgentsConsumption
 							managedAgentFeature={managedAgentFeature}
 						/>
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
new file mode 100644
index 00000000000..5efa5548301
--- /dev/null
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -0,0 +1,176 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, within } from "storybook/test";
+import type { Feature } from "#/api/typesGenerated";
+import { TotalAgentHoursCard } from "./TotalAgentHoursCard";
+
+const meta: Meta<typeof TotalAgentHoursCard> = {
+	title:
+		"pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard",
+	component: TotalAgentHoursCard,
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 1000,
+			soft_limit: 850,
+			actual: 400,
+		} satisfies Feature,
+	},
+};
+
+export default meta;
+type Story = StoryObj<typeof TotalAgentHoursCard>;
+
+const hoverInfoIcon = async (canvasElement: HTMLElement) => {
+	const canvas = within(canvasElement);
+	await userEvent.hover(
+		canvas.getByRole("button", { name: "Total agent hours information" }),
+	);
+	return within(canvasElement.ownerDocument.body);
+};
+
+// Tooltip text appears in both the tooltip popover and its hidden
+// accessibility duplicate, so assertions match all occurrences.
+const expectTooltipText = async (
+	body: ReturnType<typeof within>,
+	text: RegExp,
+) => {
+	const matches = await body.findAllByText(text);
+	expect(matches.length).toBeGreaterThanOrEqual(1);
+};
+
+export const Default: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("400")).toBeInTheDocument();
+		await expect(canvas.getByText("1,000")).toBeInTheDocument();
+		const body = await hoverInfoIcon(canvasElement);
+		await expectTooltipText(
+			body,
+			/Total time agents have been working across all workspaces this license\. A soft-limit warning appears at 85%/,
+		);
+	},
+};
+
+export const NoSoftLimit: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 1000,
+			actual: 400,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const body = await hoverInfoIcon(canvasElement);
+		await expectTooltipText(
+			body,
+			/^Total time agents have been working across all workspaces this license\.$/,
+		);
+	},
+};
+
+export const ReachedSoftLimit: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 1000,
+			soft_limit: 850,
+			actual: 850,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("850")).toBeInTheDocument();
+		const body = await hoverInfoIcon(canvasElement);
+		await expectTooltipText(
+			body,
+			/You've used 85% or more of your Total Agent hours for this license\. Agent sessions are still working normally, but you'll want to plan for the 100% limit\./,
+		);
+	},
+};
+
+export const ReachedAllocation: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 1000,
+			soft_limit: 850,
+			actual: 1000,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getAllByText("1,000")).toHaveLength(2);
+		const body = await hoverInfoIcon(canvasElement);
+		await expectTooltipText(
+			body,
+			/You've used 100% of your Total Agent hours for this license\. Contact sales to receive more Agent hours\./,
+		);
+	},
+};
+
+export const OverAllocation: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 1000,
+			soft_limit: 850,
+			actual: 1200,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("1,200")).toBeInTheDocument();
+		await expect(canvas.getByText("1,000")).toBeInTheDocument();
+	},
+};
+
+export const MissingActual: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 1000,
+			soft_limit: 850,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("\u2014")).toBeInTheDocument();
+	},
+};
+
+export const Disabled: Story = {
+	args: {
+		feature: {
+			enabled: false,
+			entitlement: "not_entitled",
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			canvas.queryByRole("heading", { name: "Total agent hours" }),
+		).not.toBeInTheDocument();
+	},
+};
+
+export const ErrorInvalidLimit: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			actual: 100,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			canvas.getByText("Invalid license usage limits"),
+		).toBeInTheDocument();
+	},
+};
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
new file mode 100644
index 00000000000..fab0036945d
--- /dev/null
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -0,0 +1,126 @@
+import { InfoIcon } from "lucide-react";
+import type { FC } from "react";
+import type { Feature } from "#/api/typesGenerated";
+import { ErrorAlert } from "#/components/Alert/ErrorAlert";
+import {
+	Tooltip,
+	TooltipContent,
+	TooltipTrigger,
+} from "#/components/Tooltip/Tooltip";
+import { cn } from "#/utils/cn";
+
+type TotalAgentHoursCardProps = {
+	feature?: Feature;
+};
+
+export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
+	feature,
+}) => {
+	// A zero-hour allocation arrives with enabled=false, which hides the
+	// panel entirely rather than showing an empty bar.
+	if (!feature?.enabled) {
+		return null;
+	}
+
+	const { limit, soft_limit: softLimit, actual } = feature;
+
+	if (limit === undefined || limit < 0) {
+		return (
+			<section className="border border-solid rounded">
+				<div className="p-4">
+					<ErrorAlert error="Invalid license usage limits" />
+				</div>
+			</section>
+		);
+	}
+
+	const usedHours = actual ?? 0;
+	// The backend warns with >= for both thresholds, so "reached" (not
+	// "exceeded") flips the bar color.
+	const reachedAllocation = actual !== undefined && usedHours >= limit;
+	const reachedSoftLimit =
+		!reachedAllocation && softLimit !== undefined && usedHours >= softLimit;
+	const usagePercentage =
+		limit > 0 ? Math.min((usedHours / limit) * 100, 100) : 0;
+
+	const usedLabel =
+		actual === undefined ? "\u2014" : usedHours.toLocaleString("en-US");
+	const limitLabel = limit.toLocaleString("en-US");
+
+	const softLimitPercent =
+		softLimit !== undefined && limit > 0
+			? Math.round((softLimit / limit) * 100)
+			: undefined;
+
+	let tooltip: string;
+	if (reachedAllocation) {
+		tooltip =
+			"You've used 100% of your Total Agent hours for this license. Contact sales to receive more Agent hours.";
+	} else if (reachedSoftLimit) {
+		tooltip = `You've used ${softLimitPercent}% or more of your Total Agent hours for this license. Agent sessions are still working normally, but you'll want to plan for the 100% limit.`;
+	} else if (softLimitPercent !== undefined) {
+		tooltip = `Total time agents have been working across all workspaces this license. A soft-limit warning appears at ${softLimitPercent}%`;
+	} else {
+		tooltip =
+			"Total time agents have been working across all workspaces this license.";
+	}
+
+	return (
+		<section className="border border-solid rounded">
+			<div className="p-4">
+				<div className="flex flex-col gap-2">
+					<div className="flex items-center gap-1">
+						<h3 className="text-md m-0 font-medium">Total agent hours</h3>
+						<Tooltip>
+							<TooltipTrigger asChild>
+								<button
+									type="button"
+									aria-label="Total agent hours information"
+									className="m-0 inline-flex appearance-none border-0 bg-transparent p-0 text-content-secondary"
+								>
+									<InfoIcon className="size-3" />
+								</button>
+							</TooltipTrigger>
+							<TooltipContent side="top" className="max-w-xs">
+								{tooltip}
+							</TooltipContent>
+						</Tooltip>
+					</div>
+
+					<div
+						className="relative h-5 w-full overflow-hidden rounded bg-surface-secondary"
+						aria-hidden="true"
+					>
+						<div
+							className={cn(
+								"h-full rounded-l transition-[width] duration-300",
+								reachedAllocation
+									? "bg-highlight-red"
+									: reachedSoftLimit
+										? "bg-highlight-orange"
+										: "bg-highlight-green",
+							)}
+							style={{ width: `${usagePercentage}%` }}
+						/>
+					</div>
+
+					<div className="flex items-start justify-between text-sm font-medium whitespace-nowrap">
+						<p className="m-0 text-content-primary">
+							<span className="text-content-secondary">Used: </span>
+							<span
+								className={cn({
+									"text-content-destructive": reachedAllocation,
+								})}
+							>
+								{usedLabel}
+							</span>
+						</p>
+						<p className="m-0 text-content-secondary">
+							Limit: <span className="text-content-primary">{limitLabel}</span>
+						</p>
+					</div>
+				</div>
+			</div>
+		</section>
+	);
+};

From 20803d775f7f797ade2b86cf874e4d0a20a57a26 Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Tue, 11 Aug 2026 08:05:09 +0000
Subject: [PATCH 02/20] feat(site): render unlimited agent runtime hours
 allocation

An enabled agent_runtime_hours feature with the limit omitted means the
license grants unlimited runtime hours (allocation claim -1). The card
previously rendered the invalid-limits error for that shape; it now
shows a full neutral bar with "Limit: Unlimited" and the tooltip
without threshold copy, mirroring SeatUsageBarCard's unlimited state.
The invalid-limits error is kept for negative limits, which can only
come from a decoding bug.
---
 .../TotalAgentHoursCard.stories.tsx           | 31 ++++++++++++++++
 .../TotalAgentHoursCard.tsx                   | 35 ++++++++++++++-----
 2 files changed, 57 insertions(+), 9 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index 5efa5548301..0fde0c0dc90 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -159,11 +159,42 @@ export const Disabled: Story = {
 	},
 };
 
+// An enabled feature with the limit omitted means the license grants
+// unlimited runtime hours: the bar renders full and neutral with no
+// threshold copy in the tooltip, mirroring SeatUsageBarCard's unlimited
+// state.
+export const Unlimited: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			actual: 1200,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("1,200")).toBeInTheDocument();
+		await expect(canvas.getByText("Unlimited")).toBeInTheDocument();
+		await expect(
+			canvas.queryByText("Invalid license usage limits"),
+		).not.toBeInTheDocument();
+		const body = await hoverInfoIcon(canvasElement);
+		await expectTooltipText(
+			body,
+			/^Total time agents have been working across all workspaces this license\.$/,
+		);
+	},
+};
+
 export const ErrorInvalidLimit: Story = {
 	args: {
 		feature: {
 			enabled: true,
 			entitlement: "entitled",
+			// A negative limit can only come from a decoding bug: the
+			// claim-level unlimited sentinel decodes to an omitted limit,
+			// never a negative one.
+			limit: -100,
 			actual: 100,
 		} satisfies Feature,
 	},
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index fab0036945d..2f6c7136302 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -24,7 +24,13 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 
 	const { limit, soft_limit: softLimit, actual } = feature;
 
-	if (limit === undefined || limit < 0) {
+	// An enabled feature with the limit omitted is the unlimited
+	// allocation: the license grants unlimited runtime hours and carries no
+	// thresholds, so the bar renders full and neutral like
+	// SeatUsageBarCard's allowUnlimited state.
+	const isUnlimited = limit === undefined;
+
+	if (!isUnlimited && limit < 0) {
 		return (
 			<section className="border border-solid rounded">
 				<div className="p-4">
@@ -34,22 +40,33 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		);
 	}
 
+	const meteredLimit = limit ?? 0;
 	const usedHours = actual ?? 0;
 	// The backend warns with >= for both thresholds, so "reached" (not
-	// "exceeded") flips the bar color.
-	const reachedAllocation = actual !== undefined && usedHours >= limit;
+	// "exceeded") flips the bar color. An unlimited allocation has no
+	// thresholds to reach.
+	const reachedAllocation =
+		!isUnlimited && actual !== undefined && usedHours >= meteredLimit;
 	const reachedSoftLimit =
-		!reachedAllocation && softLimit !== undefined && usedHours >= softLimit;
-	const usagePercentage =
-		limit > 0 ? Math.min((usedHours / limit) * 100, 100) : 0;
+		!isUnlimited &&
+		!reachedAllocation &&
+		softLimit !== undefined &&
+		usedHours >= softLimit;
+	const usagePercentage = isUnlimited
+		? 100
+		: meteredLimit > 0
+			? Math.min((usedHours / meteredLimit) * 100, 100)
+			: 0;
 
 	const usedLabel =
 		actual === undefined ? "\u2014" : usedHours.toLocaleString("en-US");
-	const limitLabel = limit.toLocaleString("en-US");
+	const limitLabel = isUnlimited
+		? "Unlimited"
+		: meteredLimit.toLocaleString("en-US");
 
 	const softLimitPercent =
-		softLimit !== undefined && limit > 0
-			? Math.round((softLimit / limit) * 100)
+		!isUnlimited && softLimit !== undefined && meteredLimit > 0
+			? Math.round((softLimit / meteredLimit) * 100)
 			: undefined;
 
 	let tooltip: string;

From eafd9113065a0ad33c4779624c530904e8982431 Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Thu, 13 Aug 2026 05:50:43 +0000
Subject: [PATCH 03/20] fix(site): report exact threshold percentages on total
 agent hours card

The allocation-reached tooltip now reports the floored actual usage
percentage (1,200 of 1,000 hours shows 120%) instead of always claiming
100%. The soft-limit percentage is floored rather than rounded so a
999/1,000-hour soft limit displays as 99% instead of crossing the
allocation boundary. Missing usage data no longer counts as reaching a
zero soft limit, and story tooltip assertions query the role=tooltip
node so they fail when the popover does not open.
---
 .../TotalAgentHoursCard.stories.tsx           | 62 +++++++++++++++++--
 .../TotalAgentHoursCard.tsx                   | 20 +++++-
 2 files changed, 75 insertions(+), 7 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index 0fde0c0dc90..02358f9f293 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -29,14 +29,16 @@ const hoverInfoIcon = async (canvasElement: HTMLElement) => {
 	return within(canvasElement.ownerDocument.body);
 };
 
-// Tooltip text appears in both the tooltip popover and its hidden
-// accessibility duplicate, so assertions match all occurrences.
+// Radix mounts the role="tooltip" node only while the popover is open,
+// so this fails when hovering does not actually open the popover. The
+// role node is the visually hidden accessibility copy of the content,
+// which is intentionally clipped, so there is no visibility to assert.
 const expectTooltipText = async (
 	body: ReturnType<typeof within>,
 	text: RegExp,
 ) => {
-	const matches = await body.findAllByText(text);
-	expect(matches.length).toBeGreaterThanOrEqual(1);
+	const tooltip = await body.findByRole("tooltip");
+	expect(tooltip).toHaveTextContent(text);
 };
 
 export const Default: Story = {
@@ -126,6 +128,34 @@ export const OverAllocation: Story = {
 		const canvas = within(canvasElement);
 		await expect(canvas.getByText("1,200")).toBeInTheDocument();
 		await expect(canvas.getByText("1,000")).toBeInTheDocument();
+		const body = await hoverInfoIcon(canvasElement);
+		await expectTooltipText(
+			body,
+			/You've used 120% of your Total Agent hours for this license\. Contact sales to receive more Agent hours\./,
+		);
+	},
+};
+
+// 999 of 1,000 hours is 99.9% used: the tooltip floors to 99% because
+// rounding up would falsely claim the allocation is reached.
+export const NearAllocation: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 1000,
+			soft_limit: 999,
+			actual: 999,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("999")).toBeInTheDocument();
+		const body = await hoverInfoIcon(canvasElement);
+		await expectTooltipText(
+			body,
+			/You've used 99% or more of your Total Agent hours for this license\. Agent sessions are still working normally, but you'll want to plan for the 100% limit\./,
+		);
 	},
 };
 
@@ -144,6 +174,30 @@ export const MissingActual: Story = {
 	},
 };
 
+// A zero soft limit is valid and reached by any usage, but usage data
+// missing because the usage query failed must not count as reaching it:
+// the card keeps the neutral informational tooltip instead of warning
+// about usage it does not know.
+export const MissingActualZeroSoftLimit: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 1000,
+			soft_limit: 0,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("\u2014")).toBeInTheDocument();
+		const body = await hoverInfoIcon(canvasElement);
+		await expectTooltipText(
+			body,
+			/^Total time agents have been working across all workspaces this license\. A soft-limit warning appears at 0%$/,
+		);
+	},
+};
+
 export const Disabled: Story = {
 	args: {
 		feature: {
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index 2f6c7136302..5fb78493685 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -47,9 +47,13 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	// thresholds to reach.
 	const reachedAllocation =
 		!isUnlimited && actual !== undefined && usedHours >= meteredLimit;
+	// Missing usage data (the usage query failed) must not count as
+	// reaching the soft limit: a soft limit of zero is valid and would
+	// otherwise compare as reached against the defaulted zero usage.
 	const reachedSoftLimit =
 		!isUnlimited &&
 		!reachedAllocation &&
+		actual !== undefined &&
 		softLimit !== undefined &&
 		usedHours >= softLimit;
 	const usagePercentage = isUnlimited
@@ -64,15 +68,25 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		? "Unlimited"
 		: meteredLimit.toLocaleString("en-US");
 
+	// Floored so the percentage never crosses a boundary the underlying
+	// hours have not reached: a soft limit of 999/1,000 hours displays as
+	// 99%, never rounding up to a false 100%.
 	const softLimitPercent =
 		!isUnlimited && softLimit !== undefined && meteredLimit > 0
-			? Math.round((softLimit / meteredLimit) * 100)
+			? Math.floor((softLimit / meteredLimit) * 100)
 			: undefined;
 
 	let tooltip: string;
 	if (reachedAllocation) {
-		tooltip =
-			"You've used 100% of your Total Agent hours for this license. Contact sales to receive more Agent hours.";
+		// Flooring cannot understate reaching the allocation because usage
+		// is at least the limit here, so the percentage is at least 100 and
+		// reports over-allocation (1,200 of 1,000 hours shows 120%). The
+		// zero-limit fallback is unreachable for well-formed licenses: the
+		// backend reports a zero-hour allocation as a disabled feature,
+		// which hides the card entirely.
+		const usedPercent =
+			meteredLimit > 0 ? Math.floor((usedHours / meteredLimit) * 100) : 100;
+		tooltip = `You've used ${usedPercent}% of your Total Agent hours for this license. Contact sales to receive more Agent hours.`;
 	} else if (reachedSoftLimit) {
 		tooltip = `You've used ${softLimitPercent}% or more of your Total Agent hours for this license. Agent sessions are still working normally, but you'll want to plan for the 100% limit.`;
 	} else if (softLimitPercent !== undefined) {

From 783eac92bb506df8eab0e93564481002c3cdc8aa Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Thu, 13 Aug 2026 06:14:03 +0000
Subject: [PATCH 04/20] feat(site): render unlimited agent hours allocation as
 striped bar

A full green bar with no thresholds read as 100% usage. Unlimited
allocations now fill the track with purple diagonal stripes so the
full-width bar reads as an unmetered allocation instead of usage
approaching a limit.
---
 .../TotalAgentHoursCard.stories.tsx           |  6 ++---
 .../TotalAgentHoursCard.tsx                   | 23 ++++++++++++-------
 2 files changed, 18 insertions(+), 11 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index 02358f9f293..c75cc35273a 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -214,9 +214,9 @@ export const Disabled: Story = {
 };
 
 // An enabled feature with the limit omitted means the license grants
-// unlimited runtime hours: the bar renders full and neutral with no
-// threshold copy in the tooltip, mirroring SeatUsageBarCard's unlimited
-// state.
+// unlimited runtime hours: the bar renders as a full track of purple
+// diagonal stripes (an unmetered allocation, not 100% usage) with no
+// threshold copy in the tooltip.
 export const Unlimited: Story = {
 	args: {
 		feature: {
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index 5fb78493685..90ec6a495f2 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -25,9 +25,8 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	const { limit, soft_limit: softLimit, actual } = feature;
 
 	// An enabled feature with the limit omitted is the unlimited
-	// allocation: the license grants unlimited runtime hours and carries no
-	// thresholds, so the bar renders full and neutral like
-	// SeatUsageBarCard's allowUnlimited state.
+	// allocation: the license grants unlimited runtime hours and carries
+	// no thresholds to warn about.
 	const isUnlimited = limit === undefined;
 
 	if (!isUnlimited && limit < 0) {
@@ -76,6 +75,18 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 			? Math.floor((softLimit / meteredLimit) * 100)
 			: undefined;
 
+	// An unlimited allocation renders as a full bar of purple diagonal
+	// stripes: the hatched pattern reads as an unmetered allocation, so
+	// the full-width bar cannot be mistaken for 100% usage. The stripes
+	// use the theme's purple highlight over the track color.
+	const barClassName = isUnlimited
+		? "bg-[repeating-linear-gradient(-45deg,hsl(var(--highlight-purple)),hsl(var(--highlight-purple))_6px,transparent_6px,transparent_12px)]"
+		: reachedAllocation
+			? "bg-highlight-red"
+			: reachedSoftLimit
+				? "bg-highlight-orange"
+				: "bg-highlight-green";
+
 	let tooltip: string;
 	if (reachedAllocation) {
 		// Flooring cannot understate reaching the allocation because usage
@@ -125,11 +136,7 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 						<div
 							className={cn(
 								"h-full rounded-l transition-[width] duration-300",
-								reachedAllocation
-									? "bg-highlight-red"
-									: reachedSoftLimit
-										? "bg-highlight-orange"
-										: "bg-highlight-green",
+								barClassName,
 							)}
 							style={{ width: `${usagePercentage}%` }}
 						/>

From e350d5acbb3e681ebf3041ae510c0ed9f62fd0f8 Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Thu, 13 Aug 2026 06:32:43 +0000
Subject: [PATCH 05/20] feat(site): fade out unlimited agent hours stripes in
 green

The unlimited allocation bar keeps its diagonal stripes but switches
from purple back to the green highlight, and the right half of the
bar fades out into the track so the pattern reads as an open-ended
allocation rather than a full meter.
---
 .../TotalAgentHoursCard.stories.tsx                |  6 +++---
 .../LicensesSettingsPage/TotalAgentHoursCard.tsx   | 14 +++++++++-----
 2 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index c75cc35273a..8aa4d03361b 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -214,9 +214,9 @@ export const Disabled: Story = {
 };
 
 // An enabled feature with the limit omitted means the license grants
-// unlimited runtime hours: the bar renders as a full track of purple
-// diagonal stripes (an unmetered allocation, not 100% usage) with no
-// threshold copy in the tooltip.
+// unlimited runtime hours: the bar renders as green diagonal stripes
+// fading out over the right half (an unmetered allocation, not 100%
+// usage) with no threshold copy in the tooltip.
 export const Unlimited: Story = {
 	args: {
 		feature: {
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index 90ec6a495f2..31adcebee0a 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -75,12 +75,16 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 			? Math.floor((softLimit / meteredLimit) * 100)
 			: undefined;
 
-	// An unlimited allocation renders as a full bar of purple diagonal
-	// stripes: the hatched pattern reads as an unmetered allocation, so
-	// the full-width bar cannot be mistaken for 100% usage. The stripes
-	// use the theme's purple highlight over the track color.
+	// An unlimited allocation renders as green diagonal stripes whose
+	// right half fades out into the track: the hatched, trailing-off bar
+	// reads as an unmetered allocation rather than 100% usage. The mask
+	// needs the -webkit- prefix for Safari.
 	const barClassName = isUnlimited
-		? "bg-[repeating-linear-gradient(-45deg,hsl(var(--highlight-purple)),hsl(var(--highlight-purple))_6px,transparent_6px,transparent_12px)]"
+		? cn(
+				"bg-[repeating-linear-gradient(-45deg,hsl(var(--highlight-green)),hsl(var(--highlight-green))_6px,transparent_6px,transparent_12px)]",
+				"[mask-image:linear-gradient(to_right,black_50%,transparent_100%)]",
+				"[-webkit-mask-image:linear-gradient(to_right,black_50%,transparent_100%)]",
+			)
 		: reachedAllocation
 			? "bg-highlight-red"
 			: reachedSoftLimit

From 98c5a6c069d28c91f15cfce73bda835311050bd3 Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Thu, 13 Aug 2026 07:02:57 +0000
Subject: [PATCH 06/20] feat(site): mark agent hours hard cap on the usage bar

When a license carries a hard limit, the track scales to the
enforcement range: a solid red line marks the hard cap at the right
edge and a dotted yellow line marks the allocation, whose limit label
follows the marker. If the allocation sits close enough to the hard
cap for the labels to collide, the hard cap label moves above the
bar. Usage at or beyond the hard cap fills the track with red
diagonal stripes and the tooltip names the cap.

Threshold percentages now render with one floored decimal place
(999/1,000 hours shows 99.9% instead of 99%), still never crossing a
boundary the underlying hours have not reached.
---
 .../TotalAgentHoursCard.stories.tsx           |  82 +++++++++-
 .../TotalAgentHoursCard.tsx                   | 143 +++++++++++++++---
 2 files changed, 197 insertions(+), 28 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index 8aa4d03361b..d833e146498 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -136,8 +136,8 @@ export const OverAllocation: Story = {
 	},
 };
 
-// 999 of 1,000 hours is 99.9% used: the tooltip floors to 99% because
-// rounding up would falsely claim the allocation is reached.
+// 999 of 1,000 hours is 99.9% used: the tooltip shows the one-decimal
+// percentage, floored so it never reads as a false 100%.
 export const NearAllocation: Story = {
 	args: {
 		feature: {
@@ -154,7 +154,7 @@ export const NearAllocation: Story = {
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
 			body,
-			/You've used 99% or more of your Total Agent hours for this license\. Agent sessions are still working normally, but you'll want to plan for the 100% limit\./,
+			/You've used 99\.9% or more of your Total Agent hours for this license\. Agent sessions are still working normally, but you'll want to plan for the 100% limit\./,
 		);
 	},
 };
@@ -198,6 +198,82 @@ export const MissingActualZeroSoftLimit: Story = {
 	},
 };
 
+// A hard cap scales the track to the enforcement range: the right edge
+// carries a solid red line with the hard cap label while the allocation
+// keeps a dotted yellow marker with the limit label at its interior
+// position.
+export const HardCap: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 1000,
+			soft_limit: 850,
+			hard_limit: 1500,
+			actual: 400,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("400")).toBeInTheDocument();
+		await expect(canvas.getByText("1,000")).toBeInTheDocument();
+		await expect(canvas.getByText(/Hard cap:/)).toBeInTheDocument();
+		await expect(canvas.getByText("1,500")).toBeInTheDocument();
+		const body = await hoverInfoIcon(canvasElement);
+		await expectTooltipText(
+			body,
+			/^Total time agents have been working across all workspaces this license\. A soft-limit warning appears at 85%$/,
+		);
+	},
+};
+
+// When the allocation sits within the last 15% of the hard-cap track,
+// the limit label under its marker would collide with the hard cap
+// label at the right edge, so the hard cap text renders above the bar.
+export const HardCapNearAllocation: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 1400,
+			soft_limit: 1200,
+			hard_limit: 1500,
+			actual: 400,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("1,400")).toBeInTheDocument();
+		await expect(canvas.getByText(/Hard cap:/)).toBeInTheDocument();
+		await expect(canvas.getByText("1,500")).toBeInTheDocument();
+	},
+};
+
+// Usage at or beyond the hard cap fills the track with red diagonal
+// stripes and the tooltip reports the enforcement ceiling. The usage
+// percentage stays measured against the allocation.
+export const ReachedHardCap: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 1000,
+			soft_limit: 850,
+			hard_limit: 1500,
+			actual: 1600,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("1,600")).toBeInTheDocument();
+		const body = await hoverInfoIcon(canvasElement);
+		await expectTooltipText(
+			body,
+			/You've used 160% of your Total Agent hours for this license and reached the hard cap of 1,500 hours\. Contact sales to receive more Agent hours\./,
+		);
+	},
+};
+
 export const Disabled: Story = {
 	args: {
 		feature: {
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index 31adcebee0a..54c4ec4e8dd 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -22,7 +22,12 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		return null;
 	}
 
-	const { limit, soft_limit: softLimit, actual } = feature;
+	const {
+		limit,
+		soft_limit: softLimit,
+		hard_limit: hardLimit,
+		actual,
+	} = feature;
 
 	// An enabled feature with the limit omitted is the unlimited
 	// allocation: the license grants unlimited runtime hours and carries
@@ -41,11 +46,24 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 
 	const meteredLimit = limit ?? 0;
 	const usedHours = actual ?? 0;
+	// The backend only attaches a hard limit to a positive allocation and
+	// guarantees hard >= allocation, ignoring unusable hard limit claims,
+	// so anything else here comes from a decoding bug and is ignored the
+	// same way.
+	const hardCap =
+		!isUnlimited &&
+		hardLimit !== undefined &&
+		hardLimit > 0 &&
+		hardLimit >= meteredLimit
+			? hardLimit
+			: undefined;
 	// The backend warns with >= for both thresholds, so "reached" (not
 	// "exceeded") flips the bar color. An unlimited allocation has no
 	// thresholds to reach.
 	const reachedAllocation =
 		!isUnlimited && actual !== undefined && usedHours >= meteredLimit;
+	const reachedHardCap =
+		hardCap !== undefined && actual !== undefined && usedHours >= hardCap;
 	// Missing usage data (the usage query failed) must not count as
 	// reaching the soft limit: a soft limit of zero is valid and would
 	// otherwise compare as reached against the defaulted zero usage.
@@ -55,53 +73,78 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		actual !== undefined &&
 		softLimit !== undefined &&
 		usedHours >= softLimit;
+	// With a hard cap the track spans the full enforcement range: its
+	// right edge is the hard cap and the allocation falls at an interior
+	// marker.
+	const barScale = hardCap ?? meteredLimit;
 	const usagePercentage = isUnlimited
 		? 100
-		: meteredLimit > 0
-			? Math.min((usedHours / meteredLimit) * 100, 100)
+		: barScale > 0
+			? Math.min((usedHours / barScale) * 100, 100)
 			: 0;
+	const allocationMarkerPercent =
+		hardCap === undefined
+			? undefined
+			: Math.min((meteredLimit / hardCap) * 100, 100);
+	// When the allocation marker lands near the track's right edge, the
+	// limit label under the marker would collide with the hard cap label,
+	// so the hard cap text moves above the bar.
+	const hardCapLabelAboveBar =
+		allocationMarkerPercent !== undefined && allocationMarkerPercent > 85;
 
 	const usedLabel =
 		actual === undefined ? "\u2014" : usedHours.toLocaleString("en-US");
 	const limitLabel = isUnlimited
 		? "Unlimited"
 		: meteredLimit.toLocaleString("en-US");
+	const hardCapLabel = hardCap?.toLocaleString("en-US");
+
+	// Percentages are floored at one decimal place so the shown value
+	// never crosses a threshold the underlying hours have not reached: a
+	// soft limit of 999/1,000 hours renders as 99.9%, never a false 100%.
+	// Whole values render without a trailing decimal.
+	const formatPercent = (value: number): string =>
+		(Math.floor(value * 10) / 10).toLocaleString("en-US");
 
-	// Floored so the percentage never crosses a boundary the underlying
-	// hours have not reached: a soft limit of 999/1,000 hours displays as
-	// 99%, never rounding up to a false 100%.
 	const softLimitPercent =
 		!isUnlimited && softLimit !== undefined && meteredLimit > 0
-			? Math.floor((softLimit / meteredLimit) * 100)
+			? formatPercent((softLimit / meteredLimit) * 100)
 			: undefined;
 
 	// An unlimited allocation renders as green diagonal stripes whose
 	// right half fades out into the track: the hatched, trailing-off bar
 	// reads as an unmetered allocation rather than 100% usage. The mask
-	// needs the -webkit- prefix for Safari.
+	// needs the -webkit- prefix for Safari. Usage at or beyond the hard
+	// cap swaps the solid red fill for red diagonal stripes.
 	const barClassName = isUnlimited
 		? cn(
 				"bg-[repeating-linear-gradient(-45deg,hsl(var(--highlight-green)),hsl(var(--highlight-green))_6px,transparent_6px,transparent_12px)]",
 				"[mask-image:linear-gradient(to_right,black_50%,transparent_100%)]",
 				"[-webkit-mask-image:linear-gradient(to_right,black_50%,transparent_100%)]",
 			)
-		: reachedAllocation
-			? "bg-highlight-red"
-			: reachedSoftLimit
-				? "bg-highlight-orange"
-				: "bg-highlight-green";
+		: reachedHardCap
+			? "bg-[repeating-linear-gradient(-45deg,hsl(var(--highlight-red)),hsl(var(--highlight-red))_6px,transparent_6px,transparent_12px)]"
+			: reachedAllocation
+				? "bg-highlight-red"
+				: reachedSoftLimit
+					? "bg-highlight-orange"
+					: "bg-highlight-green";
 
 	let tooltip: string;
 	if (reachedAllocation) {
-		// Flooring cannot understate reaching the allocation because usage
-		// is at least the limit here, so the percentage is at least 100 and
-		// reports over-allocation (1,200 of 1,000 hours shows 120%). The
-		// zero-limit fallback is unreachable for well-formed licenses: the
-		// backend reports a zero-hour allocation as a disabled feature,
-		// which hides the card entirely.
+		// The percentage is measured against the allocation even when a
+		// hard cap widens the bar, and flooring cannot understate reaching
+		// the allocation because usage is at least the limit here (1,200 of
+		// 1,000 hours shows 120%). The zero-limit fallback is unreachable
+		// for well-formed licenses: the backend reports a zero-hour
+		// allocation as a disabled feature, which hides the card entirely.
 		const usedPercent =
-			meteredLimit > 0 ? Math.floor((usedHours / meteredLimit) * 100) : 100;
-		tooltip = `You've used ${usedPercent}% of your Total Agent hours for this license. Contact sales to receive more Agent hours.`;
+			meteredLimit > 0
+				? formatPercent((usedHours / meteredLimit) * 100)
+				: "100";
+		tooltip = reachedHardCap
+			? `You've used ${usedPercent}% of your Total Agent hours for this license and reached the hard cap of ${hardCapLabel} hours. Contact sales to receive more Agent hours.`
+			: `You've used ${usedPercent}% of your Total Agent hours for this license. Contact sales to receive more Agent hours.`;
 	} else if (reachedSoftLimit) {
 		tooltip = `You've used ${softLimitPercent}% or more of your Total Agent hours for this license. Agent sessions are still working normally, but you'll want to plan for the 100% limit.`;
 	} else if (softLimitPercent !== undefined) {
@@ -133,6 +176,13 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 						</Tooltip>
 					</div>
 
+					{hardCapLabelAboveBar && (
+						<p className="m-0 self-end text-sm font-medium whitespace-nowrap text-content-secondary">
+							Hard cap:{" "}
+							<span className="text-content-primary">{hardCapLabel}</span>
+						</p>
+					)}
+
 					<div
 						className="relative h-5 w-full overflow-hidden rounded bg-surface-secondary"
 						aria-hidden="true"
@@ -144,9 +194,24 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 							)}
 							style={{ width: `${usagePercentage}%` }}
 						/>
+						{allocationMarkerPercent !== undefined && (
+							// Dotted yellow line marking the allocation on the hard-cap
+							// scaled track. The default palette yellow is used because
+							// the theme has no yellow highlight token and the soft-limit
+							// state already fills the bar with the orange one.
+							<div
+								className="absolute inset-y-0 border-0 border-l-2 border-dotted border-yellow-400"
+								style={{ left: `${allocationMarkerPercent}%` }}
+							/>
+						)}
+						{hardCap !== undefined && (
+							// Solid red line marking the hard cap at the track's right
+							// edge.
+							<div className="absolute inset-y-0 right-0 w-0.5 bg-highlight-red" />
+						)}
 					</div>
 
-					<div className="flex items-start justify-between text-sm font-medium whitespace-nowrap">
+					<div className="relative flex items-start justify-between text-sm font-medium whitespace-nowrap">
 						<p className="m-0 text-content-primary">
 							<span className="text-content-secondary">Used: </span>
 							<span
@@ -157,9 +222,37 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 								{usedLabel}
 							</span>
 						</p>
-						<p className="m-0 text-content-secondary">
-							Limit: <span className="text-content-primary">{limitLabel}</span>
-						</p>
+						{allocationMarkerPercent === undefined ? (
+							<p className="m-0 text-content-secondary">
+								Limit:{" "}
+								<span className="text-content-primary">{limitLabel}</span>
+							</p>
+						) : (
+							<>
+								{/* The limit label follows its marker so the allocation
+								    stays readable on the hard-cap scaled track. Near the
+								    right edge it right-aligns to the marker to stay
+								    inside the card. */}
+								<p
+									className={cn(
+										"absolute m-0 text-content-secondary",
+										hardCapLabelAboveBar
+											? "-translate-x-full"
+											: "-translate-x-1/2",
+									)}
+									style={{ left: `${allocationMarkerPercent}%` }}
+								>
+									Limit:{" "}
+									<span className="text-content-primary">{limitLabel}</span>
+								</p>
+								{!hardCapLabelAboveBar && (
+									<p className="m-0 text-content-secondary">
+										Hard cap:{" "}
+										<span className="text-content-primary">{hardCapLabel}</span>
+									</p>
+								)}
+							</>
+						)}
 					</div>
 				</div>
 			</div>

From 2530d21c54d9e300d356d43afe25bb88f6dbf5c2 Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Thu, 13 Aug 2026 08:57:54 +0000
Subject: [PATCH 07/20] 
 feat(site/src/pages/DeploymentSettingsPage/LicensesSettingsPage): show total
 agent hours with one decimal

Derive the Total agent hours card's usage from the entitlement's new
actual_ms field, floored to tenths of an hour with integer math so the
displayed number and the reached states flip at the same instant as the
backend's whole-hour thresholds. Usage renders with exactly one decimal
(e.g. 435.8, 1,000.0); the limit and hard cap labels stay whole because
the claims are whole hours.
---
 .../LicensesSettingsPageView.stories.tsx      |  4 +-
 .../TotalAgentHoursCard.stories.tsx           | 55 ++++++++++++++++---
 .../TotalAgentHoursCard.tsx                   | 26 +++++++--
 3 files changed, 70 insertions(+), 15 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx
index 9668b06f0b4..2d86da107a6 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx
@@ -85,6 +85,8 @@ export const TotalAgentHoursUsage: Story = {
 			limit: 2000,
 			soft_limit: 1700,
 			actual: 435,
+			// 435 hours and 48 minutes: renders as 435.8.
+			actual_ms: 435 * 3_600_000 + 48 * 60_000,
 		} satisfies Feature,
 	},
 	play: async ({ canvasElement }) => {
@@ -92,7 +94,7 @@ export const TotalAgentHoursUsage: Story = {
 		const agentHoursHeading = canvas.getByRole("heading", {
 			name: "Total agent hours",
 		});
-		await expect(canvas.getByText("435")).toBeInTheDocument();
+		await expect(canvas.getByText("435.8")).toBeInTheDocument();
 		await expect(canvas.getByText("2,000")).toBeInTheDocument();
 		const managedAgentsSection = canvas.getByText(
 			"Agent Workspace Builds Disabled",
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index d833e146498..d04a633ed56 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -14,6 +14,8 @@ const meta: Meta<typeof TotalAgentHoursCard> = {
 			limit: 1000,
 			soft_limit: 850,
 			actual: 400,
+			// 400 hours and 18 minutes: renders as 400.3.
+			actual_ms: 400 * 3_600_000 + 18 * 60_000,
 		} satisfies Feature,
 	},
 };
@@ -44,7 +46,7 @@ const expectTooltipText = async (
 export const Default: Story = {
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
-		await expect(canvas.getByText("400")).toBeInTheDocument();
+		await expect(canvas.getByText("400.3")).toBeInTheDocument();
 		await expect(canvas.getByText("1,000")).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
@@ -61,6 +63,7 @@ export const NoSoftLimit: Story = {
 			entitlement: "entitled",
 			limit: 1000,
 			actual: 400,
+			actual_ms: 400 * 3_600_000,
 		} satisfies Feature,
 	},
 	play: async ({ canvasElement }) => {
@@ -80,11 +83,12 @@ export const ReachedSoftLimit: Story = {
 			limit: 1000,
 			soft_limit: 850,
 			actual: 850,
+			actual_ms: 850 * 3_600_000,
 		} satisfies Feature,
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
-		await expect(canvas.getByText("850")).toBeInTheDocument();
+		await expect(canvas.getByText("850.0")).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
 			body,
@@ -101,11 +105,13 @@ export const ReachedAllocation: Story = {
 			limit: 1000,
 			soft_limit: 850,
 			actual: 1000,
+			actual_ms: 1000 * 3_600_000,
 		} satisfies Feature,
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
-		await expect(canvas.getAllByText("1,000")).toHaveLength(2);
+		await expect(canvas.getByText("1,000.0")).toBeInTheDocument();
+		await expect(canvas.getByText("1,000")).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
 			body,
@@ -122,11 +128,12 @@ export const OverAllocation: Story = {
 			limit: 1000,
 			soft_limit: 850,
 			actual: 1200,
+			actual_ms: 1200 * 3_600_000,
 		} satisfies Feature,
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
-		await expect(canvas.getByText("1,200")).toBeInTheDocument();
+		await expect(canvas.getByText("1,200.0")).toBeInTheDocument();
 		await expect(canvas.getByText("1,000")).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
@@ -136,6 +143,31 @@ export const OverAllocation: Story = {
 	},
 };
 
+// The whole-hour actual sits exactly at the allocation, but the extra
+// 6 minutes push the tenths-precision value past it, so the fraction
+// alone flips the reached state and the red bar.
+export const ReachedAllocationByFraction: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 1000,
+			soft_limit: 850,
+			actual: 1000,
+			actual_ms: 1000 * 3_600_000 + 6 * 60_000,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("1,000.1")).toBeInTheDocument();
+		const body = await hoverInfoIcon(canvasElement);
+		await expectTooltipText(
+			body,
+			/You've used 100% of your Total Agent hours for this license\. Contact sales to receive more Agent hours\./,
+		);
+	},
+};
+
 // 999 of 1,000 hours is 99.9% used: the tooltip shows the one-decimal
 // percentage, floored so it never reads as a false 100%.
 export const NearAllocation: Story = {
@@ -146,11 +178,12 @@ export const NearAllocation: Story = {
 			limit: 1000,
 			soft_limit: 999,
 			actual: 999,
+			actual_ms: 999 * 3_600_000,
 		} satisfies Feature,
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
-		await expect(canvas.getByText("999")).toBeInTheDocument();
+		await expect(canvas.getByText("999.0")).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
 			body,
@@ -211,11 +244,12 @@ export const HardCap: Story = {
 			soft_limit: 850,
 			hard_limit: 1500,
 			actual: 400,
+			actual_ms: 400 * 3_600_000,
 		} satisfies Feature,
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
-		await expect(canvas.getByText("400")).toBeInTheDocument();
+		await expect(canvas.getByText("400.0")).toBeInTheDocument();
 		await expect(canvas.getByText("1,000")).toBeInTheDocument();
 		await expect(canvas.getByText(/Hard cap:/)).toBeInTheDocument();
 		await expect(canvas.getByText("1,500")).toBeInTheDocument();
@@ -239,6 +273,7 @@ export const HardCapNearAllocation: Story = {
 			soft_limit: 1200,
 			hard_limit: 1500,
 			actual: 400,
+			actual_ms: 400 * 3_600_000,
 		} satisfies Feature,
 	},
 	play: async ({ canvasElement }) => {
@@ -261,11 +296,12 @@ export const ReachedHardCap: Story = {
 			soft_limit: 850,
 			hard_limit: 1500,
 			actual: 1600,
+			actual_ms: 1600 * 3_600_000,
 		} satisfies Feature,
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
-		await expect(canvas.getByText("1,600")).toBeInTheDocument();
+		await expect(canvas.getByText("1,600.0")).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
 			body,
@@ -299,11 +335,13 @@ export const Unlimited: Story = {
 			enabled: true,
 			entitlement: "entitled",
 			actual: 1200,
+			// 1,200 hours and 30 minutes: renders as 1,200.5.
+			actual_ms: 1200 * 3_600_000 + 30 * 60_000,
 		} satisfies Feature,
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
-		await expect(canvas.getByText("1,200")).toBeInTheDocument();
+		await expect(canvas.getByText("1,200.5")).toBeInTheDocument();
 		await expect(canvas.getByText("Unlimited")).toBeInTheDocument();
 		await expect(
 			canvas.queryByText("Invalid license usage limits"),
@@ -326,6 +364,7 @@ export const ErrorInvalidLimit: Story = {
 			// never a negative one.
 			limit: -100,
 			actual: 100,
+			actual_ms: 100 * 3_600_000,
 		} satisfies Feature,
 	},
 	play: async ({ canvasElement }) => {
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index 54c4ec4e8dd..780460d922e 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -26,7 +26,7 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		limit,
 		soft_limit: softLimit,
 		hard_limit: hardLimit,
-		actual,
+		actual_ms: actualMs,
 	} = feature;
 
 	// An enabled feature with the limit omitted is the unlimited
@@ -45,7 +45,12 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	}
 
 	const meteredLimit = limit ?? 0;
-	const usedHours = actual ?? 0;
+	// Usage in tenths of hours, floored via integer math from the exact
+	// milliseconds so the displayed number and the reached states below
+	// flip at the same instant as the backend's whole-hour thresholds
+	// (floor_tenths(x) >= N is equivalent to x >= N for integer N).
+	const usedHours =
+		actualMs === undefined ? 0 : Math.floor(actualMs / 360_000) / 10;
 	// The backend only attaches a hard limit to a positive allocation and
 	// guarantees hard >= allocation, ignoring unusable hard limit claims,
 	// so anything else here comes from a decoding bug and is ignored the
@@ -61,16 +66,16 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	// "exceeded") flips the bar color. An unlimited allocation has no
 	// thresholds to reach.
 	const reachedAllocation =
-		!isUnlimited && actual !== undefined && usedHours >= meteredLimit;
+		!isUnlimited && actualMs !== undefined && usedHours >= meteredLimit;
 	const reachedHardCap =
-		hardCap !== undefined && actual !== undefined && usedHours >= hardCap;
+		hardCap !== undefined && actualMs !== undefined && usedHours >= hardCap;
 	// Missing usage data (the usage query failed) must not count as
 	// reaching the soft limit: a soft limit of zero is valid and would
 	// otherwise compare as reached against the defaulted zero usage.
 	const reachedSoftLimit =
 		!isUnlimited &&
 		!reachedAllocation &&
-		actual !== undefined &&
+		actualMs !== undefined &&
 		softLimit !== undefined &&
 		usedHours >= softLimit;
 	// With a hard cap the track spans the full enforcement range: its
@@ -92,8 +97,17 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	const hardCapLabelAboveBar =
 		allocationMarkerPercent !== undefined && allocationMarkerPercent > 85;
 
+	// Usage always renders with exactly one decimal (e.g. 42.0, 10.3). The
+	// value is already floored to tenths, so no rounding happens here. The
+	// limit and hard cap labels stay whole because the claims are whole
+	// hours.
 	const usedLabel =
-		actual === undefined ? "\u2014" : usedHours.toLocaleString("en-US");
+		actualMs === undefined
+			? "\u2014"
+			: usedHours.toLocaleString("en-US", {
+					minimumFractionDigits: 1,
+					maximumFractionDigits: 1,
+				});
 	const limitLabel = isUnlimited
 		? "Unlimited"
 		: meteredLimit.toLocaleString("en-US");

From 007c640d87ad02273d7ada1627c5194acf5956ea Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Thu, 13 Aug 2026 08:59:03 +0000
Subject: [PATCH 08/20] feat(site): segment the agent hours bar by threshold

The fill is now colored by position instead of switching as a whole:
green until the soft limit, yellow from the soft limit to the
allocation, and red from the allocation to the hard cap. Each
threshold carries a marker line extending past the track: dotted
yellow for the soft limit, red for the allocation, and a double-width
primary-color line for the hard cap. Reaching the hard cap shows a
destructive pill above the bar stating that chat concurrency is
enforced.

New stories cover usage between the soft limit and the allocation and
between the allocation and the hard cap.
---
 .../TotalAgentHoursCard.stories.tsx           |  79 ++++++++-
 .../TotalAgentHoursCard.tsx                   | 162 +++++++++++++-----
 2 files changed, 187 insertions(+), 54 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index d04a633ed56..0d2435ff8bf 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -231,10 +231,11 @@ export const MissingActualZeroSoftLimit: Story = {
 	},
 };
 
-// A hard cap scales the track to the enforcement range: the right edge
-// carries a solid red line with the hard cap label while the allocation
-// keeps a dotted yellow marker with the limit label at its interior
-// position.
+// A hard cap scales the track to the enforcement range. Every threshold
+// carries a marker line: dotted yellow for the soft limit, red for the
+// allocation (with the limit label at its interior position), and a
+// double-width primary-color line for the hard cap at the right edge.
+// Usage below the soft limit fills green only.
 export const HardCap: Story = {
 	args: {
 		feature: {
@@ -253,6 +254,9 @@ export const HardCap: Story = {
 		await expect(canvas.getByText("1,000")).toBeInTheDocument();
 		await expect(canvas.getByText(/Hard cap:/)).toBeInTheDocument();
 		await expect(canvas.getByText("1,500")).toBeInTheDocument();
+		await expect(
+			canvas.queryByText(/Hard cap reached/),
+		).not.toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
 			body,
@@ -261,6 +265,63 @@ export const HardCap: Story = {
 	},
 };
 
+// Usage between the soft limit and the allocation fills green up to the
+// soft limit marker and yellow beyond it.
+export const HardCapBetweenSoftLimitAndLimit: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 1000,
+			soft_limit: 850,
+			hard_limit: 1500,
+			actual: 900,
+			actual_ms: 900 * 3_600_000,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("900.0")).toBeInTheDocument();
+		await expect(
+			canvas.queryByText(/Hard cap reached/),
+		).not.toBeInTheDocument();
+		const body = await hoverInfoIcon(canvasElement);
+		await expectTooltipText(
+			body,
+			/You've used 85% or more of your Total Agent hours for this license\. Agent sessions are still working normally, but you'll want to plan for the 100% limit\./,
+		);
+	},
+};
+
+// Usage between the allocation and the hard cap adds the red segment
+// past the limit marker. The enforcement pill only appears once the
+// hard cap itself is reached.
+export const HardCapBetweenLimitAndHardCap: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 1000,
+			soft_limit: 850,
+			hard_limit: 1500,
+			actual: 1200,
+			actual_ms: 1200 * 3_600_000,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("1,200.0")).toBeInTheDocument();
+		await expect(
+			canvas.queryByText(/Hard cap reached/),
+		).not.toBeInTheDocument();
+		const body = await hoverInfoIcon(canvasElement);
+		await expectTooltipText(
+			body,
+			/You've used 120% of your Total Agent hours for this license\. Contact sales to receive more Agent hours\./,
+		);
+	},
+};
+
 // When the allocation sits within the last 15% of the hard-cap track,
 // the limit label under its marker would collide with the hard cap
 // label at the right edge, so the hard cap text renders above the bar.
@@ -284,9 +345,10 @@ export const HardCapNearAllocation: Story = {
 	},
 };
 
-// Usage at or beyond the hard cap fills the track with red diagonal
-// stripes and the tooltip reports the enforcement ceiling. The usage
-// percentage stays measured against the allocation.
+// Usage at or beyond the hard cap fills every segment of the track and
+// shows the enforcement pill above the bar. The tooltip reports the
+// enforcement ceiling while the usage percentage stays measured against
+// the allocation.
 export const ReachedHardCap: Story = {
 	args: {
 		feature: {
@@ -302,6 +364,9 @@ export const ReachedHardCap: Story = {
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
 		await expect(canvas.getByText("1,600.0")).toBeInTheDocument();
+		await expect(
+			canvas.getByText("Hard cap reached - chat concurrency enforced"),
+		).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
 			body,
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index 780460d922e..b236816ca21 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -1,7 +1,8 @@
-import { InfoIcon } from "lucide-react";
+import { BanIcon, InfoIcon } from "lucide-react";
 import type { FC } from "react";
 import type { Feature } from "#/api/typesGenerated";
 import { ErrorAlert } from "#/components/Alert/ErrorAlert";
+import { Badge } from "#/components/Badge/Badge";
 import {
 	Tooltip,
 	TooltipContent,
@@ -63,8 +64,8 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 			? hardLimit
 			: undefined;
 	// The backend warns with >= for both thresholds, so "reached" (not
-	// "exceeded") flips the bar color. An unlimited allocation has no
-	// thresholds to reach.
+	// "exceeded") drives the warning copy and the used-label color. An
+	// unlimited allocation has no thresholds to reach.
 	const reachedAllocation =
 		!isUnlimited && actualMs !== undefined && usedHours >= meteredLimit;
 	const reachedHardCap =
@@ -97,6 +98,30 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	const hardCapLabelAboveBar =
 		allocationMarkerPercent !== undefined && allocationMarkerPercent > 85;
 
+	// The fill is segmented by position instead of switching color as a
+	// whole: green until the soft limit, yellow from the soft limit to the
+	// allocation, and red from the allocation to the hard cap. Each
+	// threshold also carries a marker line on the track at the same
+	// position, so a marker only stands out against fill of a different
+	// color once usage passes it.
+	const softMarkerPercent =
+		!isUnlimited && softLimit !== undefined && barScale > 0
+			? Math.min((softLimit / barScale) * 100, 100)
+			: undefined;
+	const limitBoundaryPercent = allocationMarkerPercent ?? 100;
+	const greenWidth = Math.min(
+		usagePercentage,
+		softMarkerPercent ?? limitBoundaryPercent,
+	);
+	const yellowWidth =
+		softMarkerPercent === undefined
+			? 0
+			: Math.max(
+					0,
+					Math.min(usagePercentage, limitBoundaryPercent) - softMarkerPercent,
+				);
+	const redWidth = Math.max(0, usagePercentage - limitBoundaryPercent);
+
 	// Usage always renders with exactly one decimal (e.g. 42.0, 10.3). The
 	// value is already floored to tenths, so no rounding happens here. The
 	// limit and hard cap labels stay whole because the claims are whole
@@ -128,21 +153,12 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	// An unlimited allocation renders as green diagonal stripes whose
 	// right half fades out into the track: the hatched, trailing-off bar
 	// reads as an unmetered allocation rather than 100% usage. The mask
-	// needs the -webkit- prefix for Safari. Usage at or beyond the hard
-	// cap swaps the solid red fill for red diagonal stripes.
-	const barClassName = isUnlimited
-		? cn(
-				"bg-[repeating-linear-gradient(-45deg,hsl(var(--highlight-green)),hsl(var(--highlight-green))_6px,transparent_6px,transparent_12px)]",
-				"[mask-image:linear-gradient(to_right,black_50%,transparent_100%)]",
-				"[-webkit-mask-image:linear-gradient(to_right,black_50%,transparent_100%)]",
-			)
-		: reachedHardCap
-			? "bg-[repeating-linear-gradient(-45deg,hsl(var(--highlight-red)),hsl(var(--highlight-red))_6px,transparent_6px,transparent_12px)]"
-			: reachedAllocation
-				? "bg-highlight-red"
-				: reachedSoftLimit
-					? "bg-highlight-orange"
-					: "bg-highlight-green";
+	// needs the -webkit- prefix for Safari.
+	const unlimitedBarClassName = cn(
+		"bg-[repeating-linear-gradient(-45deg,hsl(var(--highlight-green)),hsl(var(--highlight-green))_6px,transparent_6px,transparent_12px)]",
+		"[mask-image:linear-gradient(to_right,black_50%,transparent_100%)]",
+		"[-webkit-mask-image:linear-gradient(to_right,black_50%,transparent_100%)]",
+	);
 
 	let tooltip: string;
 	if (reachedAllocation) {
@@ -190,38 +206,90 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 						</Tooltip>
 					</div>
 
-					{hardCapLabelAboveBar && (
-						<p className="m-0 self-end text-sm font-medium whitespace-nowrap text-content-secondary">
-							Hard cap:{" "}
-							<span className="text-content-primary">{hardCapLabel}</span>
-						</p>
+					{(reachedHardCap || hardCapLabelAboveBar) && (
+						<div className="flex items-center justify-end gap-3">
+							{reachedHardCap && (
+								<Badge variant="destructive" size="sm" className="rounded-full">
+									<BanIcon />
+									Hard cap reached - chat concurrency enforced
+								</Badge>
+							)}
+							{hardCapLabelAboveBar && (
+								<p className="m-0 text-sm font-medium whitespace-nowrap text-content-secondary">
+									Hard cap:{" "}
+									<span className="text-content-primary">{hardCapLabel}</span>
+								</p>
+							)}
+						</div>
 					)}
 
-					<div
-						className="relative h-5 w-full overflow-hidden rounded bg-surface-secondary"
-						aria-hidden="true"
-					>
-						<div
-							className={cn(
-								"h-full rounded-l transition-[width] duration-300",
-								barClassName,
+					{/* The marker lines overshoot the track on both sides, so they
+					    live outside the track's overflow clipping. */}
+					<div className="relative" aria-hidden="true">
+						<div className="relative h-5 w-full overflow-hidden rounded bg-surface-secondary">
+							{isUnlimited ? (
+								<div
+									className={cn(
+										"h-full w-full rounded-l",
+										unlimitedBarClassName,
+									)}
+								/>
+							) : (
+								<>
+									<div
+										className="absolute inset-y-0 left-0 rounded-l bg-highlight-green transition-[width] duration-300"
+										style={{ width: `${greenWidth}%` }}
+									/>
+									{softMarkerPercent !== undefined && (
+										<div
+											className="absolute inset-y-0 bg-yellow-400 transition-[width] duration-300"
+											style={{
+												left: `${softMarkerPercent}%`,
+												width: `${yellowWidth}%`,
+											}}
+										/>
+									)}
+									{hardCap !== undefined && (
+										<div
+											className="absolute inset-y-0 bg-highlight-red transition-[width] duration-300"
+											style={{
+												left: `${limitBoundaryPercent}%`,
+												width: `${redWidth}%`,
+											}}
+										/>
+									)}
+								</>
 							)}
-							style={{ width: `${usagePercentage}%` }}
-						/>
-						{allocationMarkerPercent !== undefined && (
-							// Dotted yellow line marking the allocation on the hard-cap
-							// scaled track. The default palette yellow is used because
-							// the theme has no yellow highlight token and the soft-limit
-							// state already fills the bar with the orange one.
-							<div
-								className="absolute inset-y-0 border-0 border-l-2 border-dotted border-yellow-400"
-								style={{ left: `${allocationMarkerPercent}%` }}
-							/>
-						)}
-						{hardCap !== undefined && (
-							// Solid red line marking the hard cap at the track's right
-							// edge.
-							<div className="absolute inset-y-0 right-0 w-0.5 bg-highlight-red" />
+						</div>
+						{!isUnlimited && (
+							<>
+								{softMarkerPercent !== undefined && (
+									// Dotted yellow line marking the soft limit. The default
+									// palette yellow is used because the theme has no yellow
+									// highlight token.
+									<div
+										className="absolute -inset-y-1 border-0 border-l-2 border-dotted border-yellow-400"
+										style={{ left: `${softMarkerPercent}%` }}
+									/>
+								)}
+								{hardCap === undefined ? (
+									// Without a hard cap the allocation is the track's right
+									// edge, where its red marker line sits.
+									<div className="absolute -inset-y-1 right-0 w-0.5 bg-highlight-red" />
+								) : (
+									<>
+										<div
+											className="absolute -inset-y-1 w-0.5 bg-highlight-red"
+											style={{ left: `${allocationMarkerPercent}%` }}
+										/>
+										{/* Double-width line marking the hard cap. It uses the
+										    theme's primary content color (white in the dark
+										    theme) so it stays visible over the light theme's
+										    white card background. */}
+										<div className="absolute -inset-y-1 right-0 w-1 bg-content-primary" />
+									</>
+								)}
+							</>
 						)}
 					</div>
 

From fa4bea9538f173d81484476e7797e1296d4f391b Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Thu, 13 Aug 2026 12:07:49 +0000
Subject: [PATCH 09/20] 
 fix(site/src/pages/DeploymentSettingsPage/LicensesSettingsPage): keep agent
 hours labels inside the card

Replace the emdash fallback for missing usage data with N/A, and move
the limit label above the bar when the allocation marker sits within
the first 15% of a hard-cap scaled track, where the centered label
would spill outside the card and over the Used label.
---
 .../TotalAgentHoursCard.stories.tsx           | 29 +++++++++-
 .../TotalAgentHoursCard.tsx                   | 53 +++++++++++++------
 2 files changed, 64 insertions(+), 18 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index 0d2435ff8bf..765b6223150 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -203,7 +203,7 @@ export const MissingActual: Story = {
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
-		await expect(canvas.getByText("\u2014")).toBeInTheDocument();
+		await expect(canvas.getByText("N/A")).toBeInTheDocument();
 	},
 };
 
@@ -222,7 +222,7 @@ export const MissingActualZeroSoftLimit: Story = {
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
-		await expect(canvas.getByText("\u2014")).toBeInTheDocument();
+		await expect(canvas.getByText("N/A")).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
 			body,
@@ -345,6 +345,31 @@ export const HardCapNearAllocation: Story = {
 	},
 };
 
+// When the allocation sits within the first 15% of the hard-cap track
+// (here 100 of 10,000 hours, a 1% marker), the centered limit label
+// would spill outside the card and over the Used label, so the limit
+// text renders above the bar, left-aligned at its marker.
+export const HardCapFarFromAllocation: Story = {
+	args: {
+		feature: {
+			enabled: true,
+			entitlement: "entitled",
+			limit: 100,
+			soft_limit: 85,
+			hard_limit: 10_000,
+			actual: 40,
+			actual_ms: 40 * 3_600_000,
+		} satisfies Feature,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("40.0")).toBeInTheDocument();
+		await expect(canvas.getByText("100")).toBeInTheDocument();
+		await expect(canvas.getByText(/Hard cap:/)).toBeInTheDocument();
+		await expect(canvas.getByText("10,000")).toBeInTheDocument();
+	},
+};
+
 // Usage at or beyond the hard cap fills every segment of the track and
 // shows the enforcement pill above the bar. The tooltip reports the
 // enforcement ceiling while the usage percentage stays measured against
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index b236816ca21..57ed84faf5d 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -97,6 +97,11 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	// so the hard cap text moves above the bar.
 	const hardCapLabelAboveBar =
 		allocationMarkerPercent !== undefined && allocationMarkerPercent > 85;
+	// Near the left edge the centered limit label would spill outside the
+	// card and over the Used label, so the limit text moves above the bar
+	// instead, left-aligned at its marker.
+	const limitLabelAboveBar =
+		allocationMarkerPercent !== undefined && allocationMarkerPercent < 15;
 
 	// The fill is segmented by position instead of switching color as a
 	// whole: green until the soft limit, yellow from the soft limit to the
@@ -125,10 +130,10 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	// Usage always renders with exactly one decimal (e.g. 42.0, 10.3). The
 	// value is already floored to tenths, so no rounding happens here. The
 	// limit and hard cap labels stay whole because the claims are whole
-	// hours.
+	// hours. Missing usage data falls back to N/A rather than a dash.
 	const usedLabel =
 		actualMs === undefined
-			? "\u2014"
+			? "N/A"
 			: usedHours.toLocaleString("en-US", {
 					minimumFractionDigits: 1,
 					maximumFractionDigits: 1,
@@ -206,8 +211,21 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 						</Tooltip>
 					</div>
 
-					{(reachedHardCap || hardCapLabelAboveBar) && (
+					{(reachedHardCap || hardCapLabelAboveBar || limitLabelAboveBar) && (
 						<div className="flex items-center justify-end gap-3">
+							{limitLabelAboveBar && (
+								// In-flow so the row keeps its height, offset to the
+								// marker by a percentage margin (the row and the track
+								// share a width), with the auto margin keeping the
+								// enforcement pill on the right.
+								<p
+									className="m-0 mr-auto text-sm font-medium whitespace-nowrap text-content-secondary"
+									style={{ marginLeft: `${allocationMarkerPercent}%` }}
+								>
+									Limit:{" "}
+									<span className="text-content-primary">{limitLabel}</span>
+								</p>
+							)}
 							{reachedHardCap && (
 								<Badge variant="destructive" size="sm" className="rounded-full">
 									<BanIcon />
@@ -314,19 +332,22 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 								{/* The limit label follows its marker so the allocation
 								    stays readable on the hard-cap scaled track. Near the
 								    right edge it right-aligns to the marker to stay
-								    inside the card. */}
-								<p
-									className={cn(
-										"absolute m-0 text-content-secondary",
-										hardCapLabelAboveBar
-											? "-translate-x-full"
-											: "-translate-x-1/2",
-									)}
-									style={{ left: `${allocationMarkerPercent}%` }}
-								>
-									Limit:{" "}
-									<span className="text-content-primary">{limitLabel}</span>
-								</p>
+								    inside the card; near the left edge it renders above
+								    the bar instead. */}
+								{!limitLabelAboveBar && (
+									<p
+										className={cn(
+											"absolute m-0 text-content-secondary",
+											hardCapLabelAboveBar
+												? "-translate-x-full"
+												: "-translate-x-1/2",
+										)}
+										style={{ left: `${allocationMarkerPercent}%` }}
+									>
+										Limit:{" "}
+										<span className="text-content-primary">{limitLabel}</span>
+									</p>
+								)}
 								{!hardCapLabelAboveBar && (
 									<p className="m-0 text-content-secondary">
 										Hard cap:{" "}

From e64f4350388497914d91128a9e037b8e82dc8190 Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Thu, 13 Aug 2026 12:35:09 +0000
Subject: [PATCH 10/20] 
 fix(site/src/pages/DeploymentSettingsPage/LicensesSettingsPage): correct
 agent hours reached states

Turn the whole fill red when a metered allocation without a hard cap
is reached: the track ends at the allocation, so there is no position
past the limit where a red segment could render, and the previous
gating on a hard cap left the bar green or yellow in the reached
state. Also drop the concurrency-enforcement claim from the hard-cap
pill because no backend path enforces the hard limit yet.
---
 .../TotalAgentHoursCard.stories.tsx           | 16 ++++----
 .../TotalAgentHoursCard.tsx                   | 37 ++++++++++++-------
 2 files changed, 31 insertions(+), 22 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index 765b6223150..d8705282a89 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -231,7 +231,7 @@ export const MissingActualZeroSoftLimit: Story = {
 	},
 };
 
-// A hard cap scales the track to the enforcement range. Every threshold
+// A hard cap scales the track to the hard-cap range. Every threshold
 // carries a marker line: dotted yellow for the soft limit, red for the
 // allocation (with the limit label at its interior position), and a
 // double-width primary-color line for the hard cap at the right edge.
@@ -294,8 +294,8 @@ export const HardCapBetweenSoftLimitAndLimit: Story = {
 };
 
 // Usage between the allocation and the hard cap adds the red segment
-// past the limit marker. The enforcement pill only appears once the
-// hard cap itself is reached.
+// past the limit marker. The hard-cap pill only appears once the hard
+// cap itself is reached.
 export const HardCapBetweenLimitAndHardCap: Story = {
 	args: {
 		feature: {
@@ -371,9 +371,9 @@ export const HardCapFarFromAllocation: Story = {
 };
 
 // Usage at or beyond the hard cap fills every segment of the track and
-// shows the enforcement pill above the bar. The tooltip reports the
-// enforcement ceiling while the usage percentage stays measured against
-// the allocation.
+// shows the hard-cap pill above the bar. The tooltip reports the hard
+// cap while the usage percentage stays measured against the
+// allocation.
 export const ReachedHardCap: Story = {
 	args: {
 		feature: {
@@ -389,9 +389,7 @@ export const ReachedHardCap: Story = {
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
 		await expect(canvas.getByText("1,600.0")).toBeInTheDocument();
-		await expect(
-			canvas.getByText("Hard cap reached - chat concurrency enforced"),
-		).toBeInTheDocument();
+		await expect(canvas.getByText("Hard cap reached")).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
 			body,
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index 57ed84faf5d..b704a7173ad 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -79,7 +79,7 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		actualMs !== undefined &&
 		softLimit !== undefined &&
 		usedHours >= softLimit;
-	// With a hard cap the track spans the full enforcement range: its
+	// With a hard cap the track spans the full hard-cap range: its
 	// right edge is the hard cap and the allocation falls at an interior
 	// marker.
 	const barScale = hardCap ?? meteredLimit;
@@ -108,24 +108,32 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	// allocation, and red from the allocation to the hard cap. Each
 	// threshold also carries a marker line on the track at the same
 	// position, so a marker only stands out against fill of a different
-	// color once usage passes it.
+	// color once usage passes it. The exception is a metered allocation
+	// without a hard cap, where reaching the allocation turns the whole
+	// fill red (see fullRedFill below).
 	const softMarkerPercent =
 		!isUnlimited && softLimit !== undefined && barScale > 0
 			? Math.min((softLimit / barScale) * 100, 100)
 			: undefined;
 	const limitBoundaryPercent = allocationMarkerPercent ?? 100;
-	const greenWidth = Math.min(
-		usagePercentage,
-		softMarkerPercent ?? limitBoundaryPercent,
-	);
+	// Without a hard cap the track ends at the allocation, so there is no
+	// position past the limit where a red segment could appear: reaching
+	// the allocation turns the whole fill red instead.
+	const fullRedFill = reachedAllocation && hardCap === undefined;
+	const greenWidth = fullRedFill
+		? 0
+		: Math.min(usagePercentage, softMarkerPercent ?? limitBoundaryPercent);
 	const yellowWidth =
-		softMarkerPercent === undefined
+		fullRedFill || softMarkerPercent === undefined
 			? 0
 			: Math.max(
 					0,
 					Math.min(usagePercentage, limitBoundaryPercent) - softMarkerPercent,
 				);
-	const redWidth = Math.max(0, usagePercentage - limitBoundaryPercent);
+	const redLeft = fullRedFill ? 0 : limitBoundaryPercent;
+	const redWidth = fullRedFill
+		? usagePercentage
+		: Math.max(0, usagePercentage - limitBoundaryPercent);
 
 	// Usage always renders with exactly one decimal (e.g. 42.0, 10.3). The
 	// value is already floored to tenths, so no rounding happens here. The
@@ -217,7 +225,7 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 								// In-flow so the row keeps its height, offset to the
 								// marker by a percentage margin (the row and the track
 								// share a width), with the auto margin keeping the
-								// enforcement pill on the right.
+								// hard-cap pill on the right.
 								<p
 									className="m-0 mr-auto text-sm font-medium whitespace-nowrap text-content-secondary"
 									style={{ marginLeft: `${allocationMarkerPercent}%` }}
@@ -229,7 +237,7 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 							{reachedHardCap && (
 								<Badge variant="destructive" size="sm" className="rounded-full">
 									<BanIcon />
-									Hard cap reached - chat concurrency enforced
+									Hard cap reached
 								</Badge>
 							)}
 							{hardCapLabelAboveBar && (
@@ -267,11 +275,14 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 											}}
 										/>
 									)}
-									{hardCap !== undefined && (
+									{(hardCap !== undefined || fullRedFill) && (
 										<div
-											className="absolute inset-y-0 bg-highlight-red transition-[width] duration-300"
+											className={cn(
+												"absolute inset-y-0 bg-highlight-red transition-[width] duration-300",
+												fullRedFill && "rounded-l",
+											)}
 											style={{
-												left: `${limitBoundaryPercent}%`,
+												left: `${redLeft}%`,
 												width: `${redWidth}%`,
 											}}
 										/>

From 513022e32d198221558105d941e32b7e841b4032 Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Thu, 13 Aug 2026 13:43:38 +0000
Subject: [PATCH 11/20] refactor(site/src): share the agent runtime hours story
 fixture

Add MockAgentRuntimeHoursFeature to testHelpers/entities and spread it
in every TotalAgentHoursCard story instead of re-declaring the server
Feature shape per story, so entitlement defaults and the paired
actual/actual_ms fields stay defined in one place.
---
 .../TotalAgentHoursCard.stories.tsx           | 129 ++++++------------
 site/src/testHelpers/entities.ts              |  12 ++
 2 files changed, 56 insertions(+), 85 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index d8705282a89..b8aeeb765ac 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { expect, userEvent, within } from "storybook/test";
-import type { Feature } from "#/api/typesGenerated";
+import { MockAgentRuntimeHoursFeature } from "#/testHelpers/entities";
 import { TotalAgentHoursCard } from "./TotalAgentHoursCard";
 
 const meta: Meta<typeof TotalAgentHoursCard> = {
@@ -9,14 +9,10 @@ const meta: Meta<typeof TotalAgentHoursCard> = {
 	component: TotalAgentHoursCard,
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
-			limit: 1000,
-			soft_limit: 850,
-			actual: 400,
+			...MockAgentRuntimeHoursFeature,
 			// 400 hours and 18 minutes: renders as 400.3.
 			actual_ms: 400 * 3_600_000 + 18 * 60_000,
-		} satisfies Feature,
+		},
 	},
 };
 
@@ -59,12 +55,9 @@ export const Default: Story = {
 export const NoSoftLimit: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
-			limit: 1000,
-			actual: 400,
-			actual_ms: 400 * 3_600_000,
-		} satisfies Feature,
+			...MockAgentRuntimeHoursFeature,
+			soft_limit: undefined,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const body = await hoverInfoIcon(canvasElement);
@@ -78,13 +71,10 @@ export const NoSoftLimit: Story = {
 export const ReachedSoftLimit: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
-			limit: 1000,
-			soft_limit: 850,
+			...MockAgentRuntimeHoursFeature,
 			actual: 850,
 			actual_ms: 850 * 3_600_000,
-		} satisfies Feature,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
@@ -100,13 +90,10 @@ export const ReachedSoftLimit: Story = {
 export const ReachedAllocation: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
-			limit: 1000,
-			soft_limit: 850,
+			...MockAgentRuntimeHoursFeature,
 			actual: 1000,
 			actual_ms: 1000 * 3_600_000,
-		} satisfies Feature,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
@@ -123,13 +110,10 @@ export const ReachedAllocation: Story = {
 export const OverAllocation: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
-			limit: 1000,
-			soft_limit: 850,
+			...MockAgentRuntimeHoursFeature,
 			actual: 1200,
 			actual_ms: 1200 * 3_600_000,
-		} satisfies Feature,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
@@ -149,13 +133,10 @@ export const OverAllocation: Story = {
 export const ReachedAllocationByFraction: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
-			limit: 1000,
-			soft_limit: 850,
+			...MockAgentRuntimeHoursFeature,
 			actual: 1000,
 			actual_ms: 1000 * 3_600_000 + 6 * 60_000,
-		} satisfies Feature,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
@@ -173,13 +154,11 @@ export const ReachedAllocationByFraction: Story = {
 export const NearAllocation: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
-			limit: 1000,
+			...MockAgentRuntimeHoursFeature,
 			soft_limit: 999,
 			actual: 999,
 			actual_ms: 999 * 3_600_000,
-		} satisfies Feature,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
@@ -195,11 +174,10 @@ export const NearAllocation: Story = {
 export const MissingActual: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
-			limit: 1000,
-			soft_limit: 850,
-		} satisfies Feature,
+			...MockAgentRuntimeHoursFeature,
+			actual: undefined,
+			actual_ms: undefined,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
@@ -214,11 +192,11 @@ export const MissingActual: Story = {
 export const MissingActualZeroSoftLimit: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
-			limit: 1000,
+			...MockAgentRuntimeHoursFeature,
 			soft_limit: 0,
-		} satisfies Feature,
+			actual: undefined,
+			actual_ms: undefined,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
@@ -239,14 +217,9 @@ export const MissingActualZeroSoftLimit: Story = {
 export const HardCap: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
-			limit: 1000,
-			soft_limit: 850,
+			...MockAgentRuntimeHoursFeature,
 			hard_limit: 1500,
-			actual: 400,
-			actual_ms: 400 * 3_600_000,
-		} satisfies Feature,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
@@ -270,14 +243,11 @@ export const HardCap: Story = {
 export const HardCapBetweenSoftLimitAndLimit: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
-			limit: 1000,
-			soft_limit: 850,
+			...MockAgentRuntimeHoursFeature,
 			hard_limit: 1500,
 			actual: 900,
 			actual_ms: 900 * 3_600_000,
-		} satisfies Feature,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
@@ -299,14 +269,11 @@ export const HardCapBetweenSoftLimitAndLimit: Story = {
 export const HardCapBetweenLimitAndHardCap: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
-			limit: 1000,
-			soft_limit: 850,
+			...MockAgentRuntimeHoursFeature,
 			hard_limit: 1500,
 			actual: 1200,
 			actual_ms: 1200 * 3_600_000,
-		} satisfies Feature,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
@@ -328,14 +295,11 @@ export const HardCapBetweenLimitAndHardCap: Story = {
 export const HardCapNearAllocation: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
+			...MockAgentRuntimeHoursFeature,
 			limit: 1400,
 			soft_limit: 1200,
 			hard_limit: 1500,
-			actual: 400,
-			actual_ms: 400 * 3_600_000,
-		} satisfies Feature,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
@@ -352,14 +316,13 @@ export const HardCapNearAllocation: Story = {
 export const HardCapFarFromAllocation: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
+			...MockAgentRuntimeHoursFeature,
 			limit: 100,
 			soft_limit: 85,
 			hard_limit: 10_000,
 			actual: 40,
 			actual_ms: 40 * 3_600_000,
-		} satisfies Feature,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
@@ -377,14 +340,11 @@ export const HardCapFarFromAllocation: Story = {
 export const ReachedHardCap: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
-			limit: 1000,
-			soft_limit: 850,
+			...MockAgentRuntimeHoursFeature,
 			hard_limit: 1500,
 			actual: 1600,
 			actual_ms: 1600 * 3_600_000,
-		} satisfies Feature,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
@@ -401,9 +361,10 @@ export const ReachedHardCap: Story = {
 export const Disabled: Story = {
 	args: {
 		feature: {
+			...MockAgentRuntimeHoursFeature,
 			enabled: false,
 			entitlement: "not_entitled",
-		} satisfies Feature,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
@@ -420,12 +381,13 @@ export const Disabled: Story = {
 export const Unlimited: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
+			...MockAgentRuntimeHoursFeature,
+			limit: undefined,
+			soft_limit: undefined,
 			actual: 1200,
 			// 1,200 hours and 30 minutes: renders as 1,200.5.
 			actual_ms: 1200 * 3_600_000 + 30 * 60_000,
-		} satisfies Feature,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
@@ -445,15 +407,12 @@ export const Unlimited: Story = {
 export const ErrorInvalidLimit: Story = {
 	args: {
 		feature: {
-			enabled: true,
-			entitlement: "entitled",
+			...MockAgentRuntimeHoursFeature,
 			// A negative limit can only come from a decoding bug: the
 			// claim-level unlimited sentinel decodes to an omitted limit,
 			// never a negative one.
 			limit: -100,
-			actual: 100,
-			actual_ms: 100 * 3_600_000,
-		} satisfies Feature,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
diff --git a/site/src/testHelpers/entities.ts b/site/src/testHelpers/entities.ts
index bdcd17f4dc2..617102b01fb 100644
--- a/site/src/testHelpers/entities.ts
+++ b/site/src/testHelpers/entities.ts
@@ -2701,6 +2701,18 @@ export const mockApiError = ({
 	},
 });
 
+// A metered agent runtime hours entitlement: a 1,000 hour allocation
+// with an 850 hour soft limit and 400 hours used. Stories spread this
+// base and override the fields that drive the state under test.
+export const MockAgentRuntimeHoursFeature: TypesGen.Feature = {
+	enabled: true,
+	entitlement: "entitled",
+	limit: 1000,
+	soft_limit: 850,
+	actual: 400,
+	actual_ms: 400 * 3_600_000,
+};
+
 export const MockEntitlements: TypesGen.Entitlements = {
 	errors: [],
 	warnings: [],

From d219b14da63e19a3a74e591fede8c828c6d08f20 Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Thu, 13 Aug 2026 14:02:38 +0000
Subject: [PATCH 12/20] 
 refactor(site/src/pages/DeploymentSettingsPage/LicensesSettingsPage): reuse
 the runtime hours fixture in the view story

Spread MockAgentRuntimeHoursFeature in the TotalAgentHoursUsage view
story instead of rebuilding the entity inline, and drop the story
comment that restated the story name and its ordering assertion.
---
 .../LicensesSettingsPageView.stories.tsx              | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx
index 2d86da107a6..c358f73c89e 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx
@@ -1,7 +1,10 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { expect, fn, within } from "storybook/test";
 import type { Feature } from "#/api/typesGenerated";
-import { MockLicenseResponse } from "#/testHelpers/entities";
+import {
+	MockAgentRuntimeHoursFeature,
+	MockLicenseResponse,
+} from "#/testHelpers/entities";
 import LicensesSettingsPageView from "./LicensesSettingsPageView";
 
 const meta: Meta<typeof LicensesSettingsPageView> = {
@@ -76,18 +79,16 @@ export const ActiveAIGovernanceAddOnUsage: Story = {
 	},
 };
 
-/** The Total agent hours panel renders full width, directly above Agent Workspace Builds. */
 export const TotalAgentHoursUsage: Story = {
 	args: {
 		agentRuntimeHoursFeature: {
-			enabled: true,
-			entitlement: "entitled",
+			...MockAgentRuntimeHoursFeature,
 			limit: 2000,
 			soft_limit: 1700,
 			actual: 435,
 			// 435 hours and 48 minutes: renders as 435.8.
 			actual_ms: 435 * 3_600_000 + 48 * 60_000,
-		} satisfies Feature,
+		},
 	},
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);

From 7db6218f005a6b0437feae8c7f5dd9e82de0cbde Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Thu, 13 Aug 2026 14:25:41 +0000
Subject: [PATCH 13/20] fix(site/src): stack the agent hours limit label on
 narrow cards

Below the md breakpoint the centered limit label collides with the
right-aligned hard cap label at interior marker positions, so it moves
above the bar instead, left-aligned in the row shared with the
hard-cap pill. Also drop the fixture comment that restated the
MockAgentRuntimeHoursFeature values.
---
 .../TotalAgentHoursCard.stories.tsx           |  7 ++-
 .../TotalAgentHoursCard.tsx                   | 44 +++++++++++++++----
 site/src/testHelpers/entities.ts              |  3 --
 3 files changed, 42 insertions(+), 12 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index b8aeeb765ac..3ba5fe07b3d 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -224,7 +224,12 @@ export const HardCap: Story = {
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
 		await expect(canvas.getByText("400.0")).toBeInTheDocument();
-		await expect(canvas.getByText("1,000")).toBeInTheDocument();
+		// The limit label renders in both responsive layouts; exactly one
+		// is visible at the test viewport.
+		const limitLabels = canvas
+			.getAllByText("1,000")
+			.filter((label) => label.checkVisibility());
+		await expect(limitLabels).toHaveLength(1);
 		await expect(canvas.getByText(/Hard cap:/)).toBeInTheDocument();
 		await expect(canvas.getByText("1,500")).toBeInTheDocument();
 		await expect(
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index b704a7173ad..849907e9bd6 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -102,6 +102,13 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	// instead, left-aligned at its marker.
 	const limitLabelAboveBar =
 		allocationMarkerPercent !== undefined && allocationMarkerPercent < 15;
+	// At interior marker positions the centered limit label can still
+	// collide with the right-aligned hard cap label when the card is
+	// narrow, so below the md breakpoint it moves above the bar instead.
+	const limitLabelStacksNarrow =
+		allocationMarkerPercent !== undefined &&
+		!limitLabelAboveBar &&
+		!hardCapLabelAboveBar;
 
 	// The fill is segmented by position instead of switching color as a
 	// whole: green until the soft limit, yellow from the soft limit to the
@@ -219,16 +226,35 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 						</Tooltip>
 					</div>
 
-					{(reachedHardCap || hardCapLabelAboveBar || limitLabelAboveBar) && (
-						<div className="flex items-center justify-end gap-3">
-							{limitLabelAboveBar && (
+					{(reachedHardCap ||
+						hardCapLabelAboveBar ||
+						limitLabelAboveBar ||
+						limitLabelStacksNarrow) && (
+						<div
+							className={cn(
+								"flex items-center justify-end gap-3",
+								!reachedHardCap &&
+									!hardCapLabelAboveBar &&
+									!limitLabelAboveBar &&
+									"md:hidden",
+							)}
+						>
+							{(limitLabelAboveBar || limitLabelStacksNarrow) && (
 								// In-flow so the row keeps its height, offset to the
 								// marker by a percentage margin (the row and the track
 								// share a width), with the auto margin keeping the
-								// hard-cap pill on the right.
+								// hard-cap pill on the right. The narrow-only variant
+								// left-aligns instead of following the marker.
 								<p
-									className="m-0 mr-auto text-sm font-medium whitespace-nowrap text-content-secondary"
-									style={{ marginLeft: `${allocationMarkerPercent}%` }}
+									className={cn(
+										"m-0 mr-auto text-sm font-medium whitespace-nowrap text-content-secondary",
+										limitLabelStacksNarrow && "md:hidden",
+									)}
+									style={
+										limitLabelAboveBar
+											? { marginLeft: `${allocationMarkerPercent}%` }
+											: undefined
+									}
 								>
 									Limit:{" "}
 									<span className="text-content-primary">{limitLabel}</span>
@@ -344,14 +370,16 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 								    stays readable on the hard-cap scaled track. Near the
 								    right edge it right-aligns to the marker to stay
 								    inside the card; near the left edge it renders above
-								    the bar instead. */}
+								    the bar instead, as does the centered label on cards
+								    below the md breakpoint, where it would collide with
+								    the hard cap label. */}
 								{!limitLabelAboveBar && (
 									<p
 										className={cn(
 											"absolute m-0 text-content-secondary",
 											hardCapLabelAboveBar
 												? "-translate-x-full"
-												: "-translate-x-1/2",
+												: "hidden -translate-x-1/2 md:block",
 										)}
 										style={{ left: `${allocationMarkerPercent}%` }}
 									>
diff --git a/site/src/testHelpers/entities.ts b/site/src/testHelpers/entities.ts
index 617102b01fb..80882012808 100644
--- a/site/src/testHelpers/entities.ts
+++ b/site/src/testHelpers/entities.ts
@@ -2701,9 +2701,6 @@ export const mockApiError = ({
 	},
 });
 
-// A metered agent runtime hours entitlement: a 1,000 hour allocation
-// with an 850 hour soft limit and 400 hours used. Stories spread this
-// base and override the fields that drive the state under test.
 export const MockAgentRuntimeHoursFeature: TypesGen.Feature = {
 	enabled: true,
 	entitlement: "entitled",

From d9e9d484d90acf5a66dece4a7503dfda89cdb1aa Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Thu, 13 Aug 2026 14:46:29 +0000
Subject: [PATCH 14/20] 
 fix(site/src/pages/DeploymentSettingsPage/LicensesSettingsPage): fill the bar
 red at a coincident hard cap

The backend accepts a hard cap equal to the allocation, which places
the shared threshold at the track's right edge where no red segment
can render past the limit. Key the full-red reached fill on the limit
boundary sitting at the track edge instead of on the absence of a hard
cap, so the coincident case reads as reached like the no-cap case.
---
 .../TotalAgentHoursCard.stories.tsx           | 24 +++++++++++++++++++
 .../TotalAgentHoursCard.tsx                   | 11 +++++----
 2 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index 3ba5fe07b3d..2971051a91b 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -363,6 +363,30 @@ export const ReachedHardCap: Story = {
 	},
 };
 
+// The backend accepts a hard cap equal to the allocation. The shared
+// threshold sits at the track's right edge, so reaching it turns the
+// whole fill red while the pill and hard-cap tooltip still appear.
+export const ReachedCoincidentHardCap: Story = {
+	args: {
+		feature: {
+			...MockAgentRuntimeHoursFeature,
+			hard_limit: 1000,
+			actual: 1000,
+			actual_ms: 1000 * 3_600_000,
+		},
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("1,000.0")).toBeInTheDocument();
+		await expect(canvas.getByText("Hard cap reached")).toBeInTheDocument();
+		const body = await hoverInfoIcon(canvasElement);
+		await expectTooltipText(
+			body,
+			/You've used 100% of your Total Agent hours for this license and reached the hard cap of 1,000 hours\. Contact sales to receive more Agent hours\./,
+		);
+	},
+};
+
 export const Disabled: Story = {
 	args: {
 		feature: {
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index 849907e9bd6..2254526aa0c 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -115,18 +115,19 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	// allocation, and red from the allocation to the hard cap. Each
 	// threshold also carries a marker line on the track at the same
 	// position, so a marker only stands out against fill of a different
-	// color once usage passes it. The exception is a metered allocation
-	// without a hard cap, where reaching the allocation turns the whole
-	// fill red (see fullRedFill below).
+	// color once usage passes it. The exception is an allocation at the
+	// track's right edge, where reaching it turns the whole fill red
+	// (see fullRedFill below).
 	const softMarkerPercent =
 		!isUnlimited && softLimit !== undefined && barScale > 0
 			? Math.min((softLimit / barScale) * 100, 100)
 			: undefined;
 	const limitBoundaryPercent = allocationMarkerPercent ?? 100;
-	// Without a hard cap the track ends at the allocation, so there is no
+	// When the allocation sits at the track's right edge (no hard cap, or
+	// a hard cap that coincides with the allocation), there is no
 	// position past the limit where a red segment could appear: reaching
 	// the allocation turns the whole fill red instead.
-	const fullRedFill = reachedAllocation && hardCap === undefined;
+	const fullRedFill = reachedAllocation && limitBoundaryPercent >= 100;
 	const greenWidth = fullRedFill
 		? 0
 		: Math.min(usagePercentage, softMarkerPercent ?? limitBoundaryPercent);

From ff1028ea8d8d23f7f0a94c3ae19e83995035a0f1 Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Fri, 14 Aug 2026 05:32:35 +0000
Subject: [PATCH 15/20] feat(site/src): show the license usage period on the
 agent hours card

Renders the usage period dates above the bar, matching ManagedAgentsConsumption, so admins can tell which license period the shown consumption covers. A missing or unparsable period omits the dates row; the MissingUsagePeriod story pins that fallback and the shared fixture gains a usage_period.

Also trims the narrated comments in the card and its stories down to the non-obvious invariants, per review.
---
 .../TotalAgentHoursCard.stories.tsx           |  68 ++++-----
 .../TotalAgentHoursCard.tsx                   | 138 ++++++++----------
 site/src/testHelpers/entities.ts              |   5 +
 3 files changed, 91 insertions(+), 120 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index 2971051a91b..5189a8891e1 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -27,10 +27,9 @@ const hoverInfoIcon = async (canvasElement: HTMLElement) => {
 	return within(canvasElement.ownerDocument.body);
 };
 
-// Radix mounts the role="tooltip" node only while the popover is open,
-// so this fails when hovering does not actually open the popover. The
-// role node is the visually hidden accessibility copy of the content,
-// which is intentionally clipped, so there is no visibility to assert.
+// Radix mounts the role="tooltip" node only while the popover is open.
+// The node is the visually hidden copy of the content, so there is no
+// visibility to assert.
 const expectTooltipText = async (
 	body: ReturnType<typeof within>,
 	text: RegExp,
@@ -44,6 +43,8 @@ export const Default: Story = {
 		const canvas = within(canvasElement);
 		await expect(canvas.getByText("400.3")).toBeInTheDocument();
 		await expect(canvas.getByText("1,000")).toBeInTheDocument();
+		await expect(canvas.getByText("June 1, 2026")).toBeInTheDocument();
+		await expect(canvas.getByText("May 31, 2027")).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
 			body,
@@ -127,9 +128,8 @@ export const OverAllocation: Story = {
 	},
 };
 
-// The whole-hour actual sits exactly at the allocation, but the extra
-// 6 minutes push the tenths-precision value past it, so the fraction
-// alone flips the reached state and the red bar.
+// The extra 6 minutes alone push the tenths value past the whole-hour
+// allocation and flip the reached state.
 export const ReachedAllocationByFraction: Story = {
 	args: {
 		feature: {
@@ -149,8 +149,7 @@ export const ReachedAllocationByFraction: Story = {
 	},
 };
 
-// 999 of 1,000 hours is 99.9% used: the tooltip shows the one-decimal
-// percentage, floored so it never reads as a false 100%.
+// 99.9% must never read as a false 100%.
 export const NearAllocation: Story = {
 	args: {
 		feature: {
@@ -185,10 +184,8 @@ export const MissingActual: Story = {
 	},
 };
 
-// A zero soft limit is valid and reached by any usage, but usage data
-// missing because the usage query failed must not count as reaching it:
-// the card keeps the neutral informational tooltip instead of warning
-// about usage it does not know.
+// Missing usage data must not count as reaching a zero soft limit, so
+// the tooltip stays informational.
 export const MissingActualZeroSoftLimit: Story = {
 	args: {
 		feature: {
@@ -209,11 +206,20 @@ export const MissingActualZeroSoftLimit: Story = {
 	},
 };
 
-// A hard cap scales the track to the hard-cap range. Every threshold
-// carries a marker line: dotted yellow for the soft limit, red for the
-// allocation (with the limit label at its interior position), and a
-// double-width primary-color line for the hard cap at the right edge.
-// Usage below the soft limit fills green only.
+export const MissingUsagePeriod: Story = {
+	args: {
+		feature: {
+			...MockAgentRuntimeHoursFeature,
+			usage_period: undefined,
+		},
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("400.0")).toBeInTheDocument();
+		await expect(canvas.queryByText("June 1, 2026")).not.toBeInTheDocument();
+	},
+};
+
 export const HardCap: Story = {
 	args: {
 		feature: {
@@ -243,8 +249,6 @@ export const HardCap: Story = {
 	},
 };
 
-// Usage between the soft limit and the allocation fills green up to the
-// soft limit marker and yellow beyond it.
 export const HardCapBetweenSoftLimitAndLimit: Story = {
 	args: {
 		feature: {
@@ -268,9 +272,6 @@ export const HardCapBetweenSoftLimitAndLimit: Story = {
 	},
 };
 
-// Usage between the allocation and the hard cap adds the red segment
-// past the limit marker. The hard-cap pill only appears once the hard
-// cap itself is reached.
 export const HardCapBetweenLimitAndHardCap: Story = {
 	args: {
 		feature: {
@@ -294,9 +295,7 @@ export const HardCapBetweenLimitAndHardCap: Story = {
 	},
 };
 
-// When the allocation sits within the last 15% of the hard-cap track,
-// the limit label under its marker would collide with the hard cap
-// label at the right edge, so the hard cap text renders above the bar.
+// A marker past 85% moves the hard cap text above the bar.
 export const HardCapNearAllocation: Story = {
 	args: {
 		feature: {
@@ -314,10 +313,7 @@ export const HardCapNearAllocation: Story = {
 	},
 };
 
-// When the allocation sits within the first 15% of the hard-cap track
-// (here 100 of 10,000 hours, a 1% marker), the centered limit label
-// would spill outside the card and over the Used label, so the limit
-// text renders above the bar, left-aligned at its marker.
+// A marker below 15% moves the limit text above the bar.
 export const HardCapFarFromAllocation: Story = {
 	args: {
 		feature: {
@@ -338,10 +334,6 @@ export const HardCapFarFromAllocation: Story = {
 	},
 };
 
-// Usage at or beyond the hard cap fills every segment of the track and
-// shows the hard-cap pill above the bar. The tooltip reports the hard
-// cap while the usage percentage stays measured against the
-// allocation.
 export const ReachedHardCap: Story = {
 	args: {
 		feature: {
@@ -363,9 +355,7 @@ export const ReachedHardCap: Story = {
 	},
 };
 
-// The backend accepts a hard cap equal to the allocation. The shared
-// threshold sits at the track's right edge, so reaching it turns the
-// whole fill red while the pill and hard-cap tooltip still appear.
+// The backend accepts a hard cap equal to the allocation.
 export const ReachedCoincidentHardCap: Story = {
 	args: {
 		feature: {
@@ -403,10 +393,6 @@ export const Disabled: Story = {
 	},
 };
 
-// An enabled feature with the limit omitted means the license grants
-// unlimited runtime hours: the bar renders as green diagonal stripes
-// fading out over the right half (an unmetered allocation, not 100%
-// usage) with no threshold copy in the tooltip.
 export const Unlimited: Story = {
 	args: {
 		feature: {
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index 2254526aa0c..0c9cb52262a 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -1,3 +1,4 @@
+import dayjs from "dayjs";
 import { BanIcon, InfoIcon } from "lucide-react";
 import type { FC } from "react";
 import type { Feature } from "#/api/typesGenerated";
@@ -28,11 +29,10 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		soft_limit: softLimit,
 		hard_limit: hardLimit,
 		actual_ms: actualMs,
+		usage_period: usagePeriod,
 	} = feature;
 
-	// An enabled feature with the limit omitted is the unlimited
-	// allocation: the license grants unlimited runtime hours and carries
-	// no thresholds to warn about.
+	// An omitted limit means the license grants unlimited runtime hours.
 	const isUnlimited = limit === undefined;
 
 	if (!isUnlimited && limit < 0) {
@@ -46,16 +46,12 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	}
 
 	const meteredLimit = limit ?? 0;
-	// Usage in tenths of hours, floored via integer math from the exact
-	// milliseconds so the displayed number and the reached states below
-	// flip at the same instant as the backend's whole-hour thresholds
-	// (floor_tenths(x) >= N is equivalent to x >= N for integer N).
+	// Floored to tenths so the displayed number and the reached states
+	// below flip together at the backend's whole-hour thresholds.
 	const usedHours =
 		actualMs === undefined ? 0 : Math.floor(actualMs / 360_000) / 10;
-	// The backend only attaches a hard limit to a positive allocation and
-	// guarantees hard >= allocation, ignoring unusable hard limit claims,
-	// so anything else here comes from a decoding bug and is ignored the
-	// same way.
+	// The backend guarantees hard >= allocation > 0; anything else comes
+	// from a decoding bug and is ignored the same way.
 	const hardCap =
 		!isUnlimited &&
 		hardLimit !== undefined &&
@@ -63,25 +59,22 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		hardLimit >= meteredLimit
 			? hardLimit
 			: undefined;
-	// The backend warns with >= for both thresholds, so "reached" (not
-	// "exceeded") drives the warning copy and the used-label color. An
-	// unlimited allocation has no thresholds to reach.
+	// The backend warns with >=, so reaching a threshold (not exceeding
+	// it) drives the warning copy and colors.
 	const reachedAllocation =
 		!isUnlimited && actualMs !== undefined && usedHours >= meteredLimit;
 	const reachedHardCap =
 		hardCap !== undefined && actualMs !== undefined && usedHours >= hardCap;
-	// Missing usage data (the usage query failed) must not count as
-	// reaching the soft limit: a soft limit of zero is valid and would
-	// otherwise compare as reached against the defaulted zero usage.
+	// Missing usage data must not count as reaching a zero soft limit,
+	// which is valid and reached by any known usage.
 	const reachedSoftLimit =
 		!isUnlimited &&
 		!reachedAllocation &&
 		actualMs !== undefined &&
 		softLimit !== undefined &&
 		usedHours >= softLimit;
-	// With a hard cap the track spans the full hard-cap range: its
-	// right edge is the hard cap and the allocation falls at an interior
-	// marker.
+	// With a hard cap the track spans the hard-cap range and the
+	// allocation falls at an interior marker.
 	const barScale = hardCap ?? meteredLimit;
 	const usagePercentage = isUnlimited
 		? 100
@@ -92,41 +85,30 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		hardCap === undefined
 			? undefined
 			: Math.min((meteredLimit / hardCap) * 100, 100);
-	// When the allocation marker lands near the track's right edge, the
-	// limit label under the marker would collide with the hard cap label,
-	// so the hard cap text moves above the bar.
+	// Near the right edge the limit label would collide with the hard cap
+	// label, so the hard cap text moves above the bar.
 	const hardCapLabelAboveBar =
 		allocationMarkerPercent !== undefined && allocationMarkerPercent > 85;
 	// Near the left edge the centered limit label would spill outside the
-	// card and over the Used label, so the limit text moves above the bar
-	// instead, left-aligned at its marker.
+	// card, so it moves above the bar instead.
 	const limitLabelAboveBar =
 		allocationMarkerPercent !== undefined && allocationMarkerPercent < 15;
-	// At interior marker positions the centered limit label can still
-	// collide with the right-aligned hard cap label when the card is
-	// narrow, so below the md breakpoint it moves above the bar instead.
+	// On narrow cards an interior-marker limit label can collide with the
+	// hard cap label, so below the md breakpoint it moves above the bar.
 	const limitLabelStacksNarrow =
 		allocationMarkerPercent !== undefined &&
 		!limitLabelAboveBar &&
 		!hardCapLabelAboveBar;
 
-	// The fill is segmented by position instead of switching color as a
-	// whole: green until the soft limit, yellow from the soft limit to the
-	// allocation, and red from the allocation to the hard cap. Each
-	// threshold also carries a marker line on the track at the same
-	// position, so a marker only stands out against fill of a different
-	// color once usage passes it. The exception is an allocation at the
-	// track's right edge, where reaching it turns the whole fill red
-	// (see fullRedFill below).
+	// The fill is segmented by position: green to the soft limit, yellow
+	// to the allocation, and red beyond it.
 	const softMarkerPercent =
 		!isUnlimited && softLimit !== undefined && barScale > 0
 			? Math.min((softLimit / barScale) * 100, 100)
 			: undefined;
 	const limitBoundaryPercent = allocationMarkerPercent ?? 100;
-	// When the allocation sits at the track's right edge (no hard cap, or
-	// a hard cap that coincides with the allocation), there is no
-	// position past the limit where a red segment could appear: reaching
-	// the allocation turns the whole fill red instead.
+	// An allocation at the track's right edge leaves no room for a red
+	// segment past it, so reaching it turns the whole fill red instead.
 	const fullRedFill = reachedAllocation && limitBoundaryPercent >= 100;
 	const greenWidth = fullRedFill
 		? 0
@@ -143,10 +125,7 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		? usagePercentage
 		: Math.max(0, usagePercentage - limitBoundaryPercent);
 
-	// Usage always renders with exactly one decimal (e.g. 42.0, 10.3). The
-	// value is already floored to tenths, so no rounding happens here. The
-	// limit and hard cap labels stay whole because the claims are whole
-	// hours. Missing usage data falls back to N/A rather than a dash.
+	// Already floored to tenths, so rendering one decimal never rounds.
 	const usedLabel =
 		actualMs === undefined
 			? "N/A"
@@ -159,10 +138,20 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		: meteredLimit.toLocaleString("en-US");
 	const hardCapLabel = hardCap?.toLocaleString("en-US");
 
-	// Percentages are floored at one decimal place so the shown value
-	// never crosses a threshold the underlying hours have not reached: a
-	// soft limit of 999/1,000 hours renders as 99.9%, never a false 100%.
-	// Whole values render without a trailing decimal.
+	// The license period the usage covers. A missing or unparsable period
+	// omits the dates rather than replacing meaningful usage with an error.
+	const periodStart = usagePeriod ? dayjs(usagePeriod.start) : undefined;
+	const periodEnd = usagePeriod ? dayjs(usagePeriod.end) : undefined;
+	const usagePeriodLabels =
+		periodStart?.isValid() && periodEnd?.isValid()
+			? {
+					start: periodStart.format("MMMM D, YYYY"),
+					end: periodEnd.format("MMMM D, YYYY"),
+				}
+			: undefined;
+
+	// Floored at one decimal so the shown percentage never crosses a
+	// threshold the underlying hours have not (99.9%, never a false 100%).
 	const formatPercent = (value: number): string =>
 		(Math.floor(value * 10) / 10).toLocaleString("en-US");
 
@@ -171,10 +160,8 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 			? formatPercent((softLimit / meteredLimit) * 100)
 			: undefined;
 
-	// An unlimited allocation renders as green diagonal stripes whose
-	// right half fades out into the track: the hatched, trailing-off bar
-	// reads as an unmetered allocation rather than 100% usage. The mask
-	// needs the -webkit- prefix for Safari.
+	// Fading green stripes read as an unmetered allocation rather than
+	// 100% usage. The mask needs the -webkit- prefix for Safari.
 	const unlimitedBarClassName = cn(
 		"bg-[repeating-linear-gradient(-45deg,hsl(var(--highlight-green)),hsl(var(--highlight-green))_6px,transparent_6px,transparent_12px)]",
 		"[mask-image:linear-gradient(to_right,black_50%,transparent_100%)]",
@@ -183,12 +170,9 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 
 	let tooltip: string;
 	if (reachedAllocation) {
-		// The percentage is measured against the allocation even when a
-		// hard cap widens the bar, and flooring cannot understate reaching
-		// the allocation because usage is at least the limit here (1,200 of
-		// 1,000 hours shows 120%). The zero-limit fallback is unreachable
-		// for well-formed licenses: the backend reports a zero-hour
-		// allocation as a disabled feature, which hides the card entirely.
+		// Measured against the allocation even when a hard cap widens the
+		// bar. The zero-limit fallback is unreachable for well-formed
+		// licenses, which report zero-hour allocations as disabled.
 		const usedPercent =
 			meteredLimit > 0
 				? formatPercent((usedHours / meteredLimit) * 100)
@@ -227,6 +211,13 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 						</Tooltip>
 					</div>
 
+					{usagePeriodLabels && (
+						<div className="flex items-center justify-between text-sm text-content-secondary">
+							<span>{usagePeriodLabels.start}</span>
+							<span>{usagePeriodLabels.end}</span>
+						</div>
+					)}
+
 					{(reachedHardCap ||
 						hardCapLabelAboveBar ||
 						limitLabelAboveBar ||
@@ -241,11 +232,9 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 							)}
 						>
 							{(limitLabelAboveBar || limitLabelStacksNarrow) && (
-								// In-flow so the row keeps its height, offset to the
-								// marker by a percentage margin (the row and the track
-								// share a width), with the auto margin keeping the
-								// hard-cap pill on the right. The narrow-only variant
-								// left-aligns instead of following the marker.
+								// Offset to the marker by a percentage margin (the row
+								// and the track share a width); the narrow-only variant
+								// left-aligns instead.
 								<p
 									className={cn(
 										"m-0 mr-auto text-sm font-medium whitespace-nowrap text-content-secondary",
@@ -320,17 +309,14 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 						{!isUnlimited && (
 							<>
 								{softMarkerPercent !== undefined && (
-									// Dotted yellow line marking the soft limit. The default
-									// palette yellow is used because the theme has no yellow
-									// highlight token.
+									// Palette yellow: the theme has no yellow highlight token.
 									<div
 										className="absolute -inset-y-1 border-0 border-l-2 border-dotted border-yellow-400"
 										style={{ left: `${softMarkerPercent}%` }}
 									/>
 								)}
 								{hardCap === undefined ? (
-									// Without a hard cap the allocation is the track's right
-									// edge, where its red marker line sits.
+									// The allocation marker sits at the track's right edge.
 									<div className="absolute -inset-y-1 right-0 w-0.5 bg-highlight-red" />
 								) : (
 									<>
@@ -338,10 +324,8 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 											className="absolute -inset-y-1 w-0.5 bg-highlight-red"
 											style={{ left: `${allocationMarkerPercent}%` }}
 										/>
-										{/* Double-width line marking the hard cap. It uses the
-										    theme's primary content color (white in the dark
-										    theme) so it stays visible over the light theme's
-										    white card background. */}
+										{/* The primary content color stays visible over both
+										    themes' card backgrounds. */}
 										<div className="absolute -inset-y-1 right-0 w-1 bg-content-primary" />
 									</>
 								)}
@@ -367,13 +351,9 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 							</p>
 						) : (
 							<>
-								{/* The limit label follows its marker so the allocation
-								    stays readable on the hard-cap scaled track. Near the
-								    right edge it right-aligns to the marker to stay
-								    inside the card; near the left edge it renders above
-								    the bar instead, as does the centered label on cards
-								    below the md breakpoint, where it would collide with
-								    the hard cap label. */}
+								{/* The limit label follows its marker: right-aligned
+								    against it near the right edge, otherwise centered
+								    (with the narrow copy rendering above the bar). */}
 								{!limitLabelAboveBar && (
 									<p
 										className={cn(
diff --git a/site/src/testHelpers/entities.ts b/site/src/testHelpers/entities.ts
index 80882012808..a02e82b39b2 100644
--- a/site/src/testHelpers/entities.ts
+++ b/site/src/testHelpers/entities.ts
@@ -2708,6 +2708,11 @@ export const MockAgentRuntimeHoursFeature: TypesGen.Feature = {
 	soft_limit: 850,
 	actual: 400,
 	actual_ms: 400 * 3_600_000,
+	usage_period: {
+		issued_at: "June 1, 2026",
+		start: "June 1, 2026",
+		end: "May 31, 2027",
+	},
 };
 
 export const MockEntitlements: TypesGen.Entitlements = {

From 53ec6351043b8f7067eb847d1f81f6ed5115254b Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Wed, 19 Aug 2026 10:29:21 +0000
Subject: [PATCH 16/20] chore: design updates

---
 .../TotalAgentHoursCard.stories.tsx           |  92 +++---
 .../TotalAgentHoursCard.tsx                   | 296 ++++++------------
 2 files changed, 135 insertions(+), 253 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index 5189a8891e1..bbe7fef50d9 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -42,9 +42,14 @@ export const Default: Story = {
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
 		await expect(canvas.getByText("400.3")).toBeInTheDocument();
+		await expect(canvas.getByText(/Warning:/)).toBeInTheDocument();
+		await expect(canvas.getByText("850")).toBeInTheDocument();
+		await expect(canvas.getByText(/Allocation:/)).toBeInTheDocument();
 		await expect(canvas.getByText("1,000")).toBeInTheDocument();
-		await expect(canvas.getByText("June 1, 2026")).toBeInTheDocument();
-		await expect(canvas.getByText("May 31, 2027")).toBeInTheDocument();
+		await expect(canvas.queryByText(/Limit:/)).not.toBeInTheDocument();
+		await expect(
+			canvas.getByText("(June 1, 2026 – May 31, 2027)"),
+		).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
 			body,
@@ -61,6 +66,8 @@ export const NoSoftLimit: Story = {
 		},
 	},
 	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.queryByText(/Warning:/)).not.toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
 			body,
@@ -216,7 +223,9 @@ export const MissingUsagePeriod: Story = {
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
 		await expect(canvas.getByText("400.0")).toBeInTheDocument();
-		await expect(canvas.queryByText("June 1, 2026")).not.toBeInTheDocument();
+		await expect(
+			canvas.queryByText("(June 1, 2026 – May 31, 2027)"),
+		).not.toBeInTheDocument();
 	},
 };
 
@@ -230,16 +239,16 @@ export const HardCap: Story = {
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
 		await expect(canvas.getByText("400.0")).toBeInTheDocument();
-		// The limit label renders in both responsive layouts; exactly one
-		// is visible at the test viewport.
-		const limitLabels = canvas
-			.getAllByText("1,000")
-			.filter((label) => label.checkVisibility());
-		await expect(limitLabels).toHaveLength(1);
-		await expect(canvas.getByText(/Hard cap:/)).toBeInTheDocument();
+		await expect(canvas.getByText(/Warning:/)).toBeInTheDocument();
+		await expect(canvas.getByText("850")).toBeInTheDocument();
+		await expect(canvas.getByText(/Allocation:/)).toBeInTheDocument();
+		await expect(canvas.getByText("1,000")).toBeInTheDocument();
+		await expect(canvas.getByText(/Limit:/)).toBeInTheDocument();
 		await expect(canvas.getByText("1,500")).toBeInTheDocument();
 		await expect(
-			canvas.queryByText(/Hard cap reached/),
+			canvas.queryByText(
+				"Agent hours exceeded. Concurrent chats are now limited to 5.",
+			),
 		).not.toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
@@ -262,7 +271,9 @@ export const HardCapBetweenSoftLimitAndLimit: Story = {
 		const canvas = within(canvasElement);
 		await expect(canvas.getByText("900.0")).toBeInTheDocument();
 		await expect(
-			canvas.queryByText(/Hard cap reached/),
+			canvas.queryByText(
+				"Agent hours exceeded. Concurrent chats are now limited to 5.",
+			),
 		).not.toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
@@ -285,7 +296,9 @@ export const HardCapBetweenLimitAndHardCap: Story = {
 		const canvas = within(canvasElement);
 		await expect(canvas.getByText("1,200.0")).toBeInTheDocument();
 		await expect(
-			canvas.queryByText(/Hard cap reached/),
+			canvas.queryByText(
+				"Agent hours exceeded. Concurrent chats are now limited to 5.",
+			),
 		).not.toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
@@ -295,45 +308,6 @@ export const HardCapBetweenLimitAndHardCap: Story = {
 	},
 };
 
-// A marker past 85% moves the hard cap text above the bar.
-export const HardCapNearAllocation: Story = {
-	args: {
-		feature: {
-			...MockAgentRuntimeHoursFeature,
-			limit: 1400,
-			soft_limit: 1200,
-			hard_limit: 1500,
-		},
-	},
-	play: async ({ canvasElement }) => {
-		const canvas = within(canvasElement);
-		await expect(canvas.getByText("1,400")).toBeInTheDocument();
-		await expect(canvas.getByText(/Hard cap:/)).toBeInTheDocument();
-		await expect(canvas.getByText("1,500")).toBeInTheDocument();
-	},
-};
-
-// A marker below 15% moves the limit text above the bar.
-export const HardCapFarFromAllocation: Story = {
-	args: {
-		feature: {
-			...MockAgentRuntimeHoursFeature,
-			limit: 100,
-			soft_limit: 85,
-			hard_limit: 10_000,
-			actual: 40,
-			actual_ms: 40 * 3_600_000,
-		},
-	},
-	play: async ({ canvasElement }) => {
-		const canvas = within(canvasElement);
-		await expect(canvas.getByText("40.0")).toBeInTheDocument();
-		await expect(canvas.getByText("100")).toBeInTheDocument();
-		await expect(canvas.getByText(/Hard cap:/)).toBeInTheDocument();
-		await expect(canvas.getByText("10,000")).toBeInTheDocument();
-	},
-};
-
 export const ReachedHardCap: Story = {
 	args: {
 		feature: {
@@ -346,7 +320,11 @@ export const ReachedHardCap: Story = {
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
 		await expect(canvas.getByText("1,600.0")).toBeInTheDocument();
-		await expect(canvas.getByText("Hard cap reached")).toBeInTheDocument();
+		await expect(
+			canvas.getByText(
+				"Agent hours exceeded. Concurrent chats are now limited to 5.",
+			),
+		).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
 			body,
@@ -368,7 +346,11 @@ export const ReachedCoincidentHardCap: Story = {
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
 		await expect(canvas.getByText("1,000.0")).toBeInTheDocument();
-		await expect(canvas.getByText("Hard cap reached")).toBeInTheDocument();
+		await expect(
+			canvas.getByText(
+				"Agent hours exceeded. Concurrent chats are now limited to 5.",
+			),
+		).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
 			body,
@@ -407,6 +389,8 @@ export const Unlimited: Story = {
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
 		await expect(canvas.getByText("1,200.5")).toBeInTheDocument();
+		await expect(canvas.queryByText(/Warning:/)).not.toBeInTheDocument();
+		await expect(canvas.getByText(/Allocation:/)).toBeInTheDocument();
 		await expect(canvas.getByText("Unlimited")).toBeInTheDocument();
 		await expect(
 			canvas.queryByText("Invalid license usage limits"),
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index 0c9cb52262a..78e7929e7cd 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -85,45 +85,19 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		hardCap === undefined
 			? undefined
 			: Math.min((meteredLimit / hardCap) * 100, 100);
-	// Near the right edge the limit label would collide with the hard cap
-	// label, so the hard cap text moves above the bar.
-	const hardCapLabelAboveBar =
-		allocationMarkerPercent !== undefined && allocationMarkerPercent > 85;
-	// Near the left edge the centered limit label would spill outside the
-	// card, so it moves above the bar instead.
-	const limitLabelAboveBar =
-		allocationMarkerPercent !== undefined && allocationMarkerPercent < 15;
-	// On narrow cards an interior-marker limit label can collide with the
-	// hard cap label, so below the md breakpoint it moves above the bar.
-	const limitLabelStacksNarrow =
-		allocationMarkerPercent !== undefined &&
-		!limitLabelAboveBar &&
-		!hardCapLabelAboveBar;
 
-	// The fill is segmented by position: green to the soft limit, yellow
-	// to the allocation, and red beyond it.
 	const softMarkerPercent =
 		!isUnlimited && softLimit !== undefined && barScale > 0
 			? Math.min((softLimit / barScale) * 100, 100)
 			: undefined;
-	const limitBoundaryPercent = allocationMarkerPercent ?? 100;
-	// An allocation at the track's right edge leaves no room for a red
-	// segment past it, so reaching it turns the whole fill red instead.
-	const fullRedFill = reachedAllocation && limitBoundaryPercent >= 100;
-	const greenWidth = fullRedFill
-		? 0
-		: Math.min(usagePercentage, softMarkerPercent ?? limitBoundaryPercent);
-	const yellowWidth =
-		fullRedFill || softMarkerPercent === undefined
-			? 0
-			: Math.max(
-					0,
-					Math.min(usagePercentage, limitBoundaryPercent) - softMarkerPercent,
-				);
-	const redLeft = fullRedFill ? 0 : limitBoundaryPercent;
-	const redWidth = fullRedFill
-		? usagePercentage
-		: Math.max(0, usagePercentage - limitBoundaryPercent);
+	// The fill is a single color for the used range: green below the
+	// soft limit, warning once the soft limit is reached, and red at or
+	// past the allocation.
+	const fillClassName = reachedAllocation
+		? "bg-highlight-red"
+		: reachedSoftLimit
+			? "bg-border-warning"
+			: "bg-highlight-green";
 
 	// Already floored to tenths, so rendering one decimal never rounds.
 	const usedLabel =
@@ -133,21 +107,23 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 					minimumFractionDigits: 1,
 					maximumFractionDigits: 1,
 				});
-	const limitLabel = isUnlimited
+	const warningLabel =
+		!isUnlimited && softLimit !== undefined
+			? softLimit.toLocaleString("en-US")
+			: undefined;
+	const allocationLabel = isUnlimited
 		? "Unlimited"
 		: meteredLimit.toLocaleString("en-US");
-	const hardCapLabel = hardCap?.toLocaleString("en-US");
+	const limitLabel = hardCap?.toLocaleString("en-US");
 
-	// The license period the usage covers. A missing or unparsable period
-	// omits the dates rather than replacing meaningful usage with an error.
+	// The license period the usage covers. Shown under the heading so the
+	// bar is not read as a timeline. A missing or unparsable period omits
+	// the dates rather than replacing meaningful usage with an error.
 	const periodStart = usagePeriod ? dayjs(usagePeriod.start) : undefined;
 	const periodEnd = usagePeriod ? dayjs(usagePeriod.end) : undefined;
-	const usagePeriodLabels =
+	const usagePeriodLabel =
 		periodStart?.isValid() && periodEnd?.isValid()
-			? {
-					start: periodStart.format("MMMM D, YYYY"),
-					end: periodEnd.format("MMMM D, YYYY"),
-				}
+			? `(${periodStart.format("MMMM D, YYYY")} – ${periodEnd.format("MMMM D, YYYY")})`
 			: undefined;
 
 	// Floored at one decimal so the shown percentage never crosses a
@@ -160,10 +136,10 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 			? formatPercent((softLimit / meteredLimit) * 100)
 			: undefined;
 
-	// Fading green stripes read as an unmetered allocation rather than
+	// A fading green fill reads as an unmetered allocation rather than
 	// 100% usage. The mask needs the -webkit- prefix for Safari.
 	const unlimitedBarClassName = cn(
-		"bg-[repeating-linear-gradient(-45deg,hsl(var(--highlight-green)),hsl(var(--highlight-green))_6px,transparent_6px,transparent_12px)]",
+		"bg-highlight-green",
 		"[mask-image:linear-gradient(to_right,black_50%,transparent_100%)]",
 		"[-webkit-mask-image:linear-gradient(to_right,black_50%,transparent_100%)]",
 	);
@@ -178,7 +154,7 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 				? formatPercent((usedHours / meteredLimit) * 100)
 				: "100";
 		tooltip = reachedHardCap
-			? `You've used ${usedPercent}% of your Total Agent hours for this license and reached the hard cap of ${hardCapLabel} hours. Contact sales to receive more Agent hours.`
+			? `You've used ${usedPercent}% of your Total Agent hours for this license and reached the hard cap of ${limitLabel} hours. Contact sales to receive more Agent hours.`
 			: `You've used ${usedPercent}% of your Total Agent hours for this license. Contact sales to receive more Agent hours.`;
 	} else if (reachedSoftLimit) {
 		tooltip = `You've used ${softLimitPercent}% or more of your Total Agent hours for this license. Agent sessions are still working normally, but you'll want to plan for the 100% limit.`;
@@ -193,189 +169,111 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		<section className="border border-solid rounded">
 			<div className="p-4">
 				<div className="flex flex-col gap-2">
-					<div className="flex items-center gap-1">
-						<h3 className="text-md m-0 font-medium">Total agent hours</h3>
-						<Tooltip>
-							<TooltipTrigger asChild>
-								<button
-									type="button"
-									aria-label="Total agent hours information"
-									className="m-0 inline-flex appearance-none border-0 bg-transparent p-0 text-content-secondary"
-								>
-									<InfoIcon className="size-3" />
-								</button>
-							</TooltipTrigger>
-							<TooltipContent side="top" className="max-w-xs">
-								{tooltip}
-							</TooltipContent>
-						</Tooltip>
+					<div className="flex flex-col gap-0.5">
+						<div className="flex items-center gap-1">
+							<h3 className="text-md m-0 font-medium">Total agent hours</h3>
+							<Tooltip>
+								<TooltipTrigger asChild>
+									<button
+										type="button"
+										aria-label="Total agent hours information"
+										className="m-0 inline-flex appearance-none border-0 bg-transparent p-0 text-content-secondary"
+									>
+										<InfoIcon className="size-3" />
+									</button>
+								</TooltipTrigger>
+								<TooltipContent side="top" className="max-w-xs">
+									{tooltip}
+								</TooltipContent>
+							</Tooltip>
+						</div>
+						{usagePeriodLabel && (
+							<p className="m-0 text-xs text-content-secondary">
+								{usagePeriodLabel}
+							</p>
+						)}
 					</div>
 
-					{usagePeriodLabels && (
-						<div className="flex items-center justify-between text-sm text-content-secondary">
-							<span>{usagePeriodLabels.start}</span>
-							<span>{usagePeriodLabels.end}</span>
+					{reachedHardCap && (
+						<div className="flex items-center justify-end">
+							<Badge variant="destructive" size="sm" className="rounded-full">
+								<BanIcon />
+								Agent hours exceeded. Concurrent chats are now limited to 5.
+							</Badge>
 						</div>
 					)}
 
-					{(reachedHardCap ||
-						hardCapLabelAboveBar ||
-						limitLabelAboveBar ||
-						limitLabelStacksNarrow) && (
-						<div
-							className={cn(
-								"flex items-center justify-end gap-3",
-								!reachedHardCap &&
-									!hardCapLabelAboveBar &&
-									!limitLabelAboveBar &&
-									"md:hidden",
-							)}
-						>
-							{(limitLabelAboveBar || limitLabelStacksNarrow) && (
-								// Offset to the marker by a percentage margin (the row
-								// and the track share a width); the narrow-only variant
-								// left-aligns instead.
-								<p
-									className={cn(
-										"m-0 mr-auto text-sm font-medium whitespace-nowrap text-content-secondary",
-										limitLabelStacksNarrow && "md:hidden",
-									)}
-									style={
-										limitLabelAboveBar
-											? { marginLeft: `${allocationMarkerPercent}%` }
-											: undefined
-									}
-								>
-									Limit:{" "}
-									<span className="text-content-primary">{limitLabel}</span>
-								</p>
-							)}
-							{reachedHardCap && (
-								<Badge variant="destructive" size="sm" className="rounded-full">
-									<BanIcon />
-									Hard cap reached
-								</Badge>
-							)}
-							{hardCapLabelAboveBar && (
-								<p className="m-0 text-sm font-medium whitespace-nowrap text-content-secondary">
-									Hard cap:{" "}
-									<span className="text-content-primary">{hardCapLabel}</span>
-								</p>
-							)}
-						</div>
-					)}
-
-					{/* The marker lines overshoot the track on both sides, so they
-					    live outside the track's overflow clipping. */}
-					<div className="relative" aria-hidden="true">
-						<div className="relative h-5 w-full overflow-hidden rounded bg-surface-secondary">
-							{isUnlimited ? (
-								<div
-									className={cn(
-										"h-full w-full rounded-l",
-										unlimitedBarClassName,
-									)}
-								/>
-							) : (
-								<>
-									<div
-										className="absolute inset-y-0 left-0 rounded-l bg-highlight-green transition-[width] duration-300"
-										style={{ width: `${greenWidth}%` }}
-									/>
-									{softMarkerPercent !== undefined && (
-										<div
-											className="absolute inset-y-0 bg-yellow-400 transition-[width] duration-300"
-											style={{
-												left: `${softMarkerPercent}%`,
-												width: `${yellowWidth}%`,
-											}}
-										/>
-									)}
-									{(hardCap !== undefined || fullRedFill) && (
-										<div
-											className={cn(
-												"absolute inset-y-0 bg-highlight-red transition-[width] duration-300",
-												fullRedFill && "rounded-l",
-											)}
-											style={{
-												left: `${redLeft}%`,
-												width: `${redWidth}%`,
-											}}
-										/>
-									)}
-								</>
-							)}
-						</div>
+					<div
+						className="relative h-5 w-full overflow-hidden bg-surface-secondary"
+						aria-hidden="true"
+					>
 						{!isUnlimited && (
 							<>
 								{softMarkerPercent !== undefined && (
-									// Palette yellow: the theme has no yellow highlight token.
 									<div
-										className="absolute -inset-y-1 border-0 border-l-2 border-dotted border-yellow-400"
+										className="absolute inset-y-0 z-0 border-0 border-l-2 border-dotted border-border-warning"
 										style={{ left: `${softMarkerPercent}%` }}
 									/>
 								)}
 								{hardCap === undefined ? (
 									// The allocation marker sits at the track's right edge.
-									<div className="absolute -inset-y-1 right-0 w-0.5 bg-highlight-red" />
+									<div className="absolute inset-y-0 right-0 z-0 w-0.5 bg-highlight-red" />
 								) : (
-									<>
-										<div
-											className="absolute -inset-y-1 w-0.5 bg-highlight-red"
-											style={{ left: `${allocationMarkerPercent}%` }}
-										/>
-										{/* The primary content color stays visible over both
-										    themes' card backgrounds. */}
-										<div className="absolute -inset-y-1 right-0 w-1 bg-content-primary" />
-									</>
+									<div
+										className="absolute inset-y-0 z-0 w-0.5 bg-highlight-red"
+										style={{ left: `${allocationMarkerPercent}%` }}
+									/>
 								)}
 							</>
 						)}
+						{isUnlimited ? (
+							<div
+								className={cn(
+									"relative z-10 h-full w-full",
+									unlimitedBarClassName,
+								)}
+							/>
+						) : (
+							<div
+								className={cn(
+									"relative z-10 h-full transition-[width] duration-300",
+									fillClassName,
+								)}
+								style={{ width: `${usagePercentage}%` }}
+							/>
+						)}
 					</div>
 
-					<div className="relative flex items-start justify-between text-sm font-medium whitespace-nowrap">
-						<p className="m-0 text-content-primary">
+					<div className="flex items-start justify-between gap-3 text-sm font-medium">
+						<p className="m-0 whitespace-nowrap text-content-primary">
 							<span className="text-content-secondary">Used: </span>
 							<span
 								className={cn({
 									"text-content-destructive": reachedAllocation,
+									"text-border-warning": reachedSoftLimit,
 								})}
 							>
 								{usedLabel}
 							</span>
 						</p>
-						{allocationMarkerPercent === undefined ? (
-							<p className="m-0 text-content-secondary">
-								Limit:{" "}
-								<span className="text-content-primary">{limitLabel}</span>
+						<div className="flex flex-wrap items-start justify-end gap-x-3 gap-y-1 whitespace-nowrap text-content-secondary">
+							{warningLabel !== undefined && (
+								<p className="m-0">
+									Warning:{" "}
+									<span className="text-content-primary">{warningLabel}</span>
+								</p>
+							)}
+							<p className="m-0">
+								Allocation:{" "}
+								<span className="text-content-primary">{allocationLabel}</span>
 							</p>
-						) : (
-							<>
-								{/* The limit label follows its marker: right-aligned
-								    against it near the right edge, otherwise centered
-								    (with the narrow copy rendering above the bar). */}
-								{!limitLabelAboveBar && (
-									<p
-										className={cn(
-											"absolute m-0 text-content-secondary",
-											hardCapLabelAboveBar
-												? "-translate-x-full"
-												: "hidden -translate-x-1/2 md:block",
-										)}
-										style={{ left: `${allocationMarkerPercent}%` }}
-									>
-										Limit:{" "}
-										<span className="text-content-primary">{limitLabel}</span>
-									</p>
-								)}
-								{!hardCapLabelAboveBar && (
-									<p className="m-0 text-content-secondary">
-										Hard cap:{" "}
-										<span className="text-content-primary">{hardCapLabel}</span>
-									</p>
-								)}
-							</>
-						)}
+							{limitLabel !== undefined && (
+								<p className="m-0">
+									Limit:{" "}
+									<span className="text-content-primary">{limitLabel}</span>
+								</p>
+							)}
+						</div>
 					</div>
 				</div>
 			</div>

From 19c01e7022206c31461fde04c2ae383331819a1f Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Wed, 19 Aug 2026 12:59:52 +0000
Subject: [PATCH 17/20] fix: fix test

---
 .../LicensesSettingsPageView.stories.tsx                     | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx
index c358f73c89e..4f038717cbc 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicensesSettingsPageView.stories.tsx
@@ -95,8 +95,9 @@ export const TotalAgentHoursUsage: Story = {
 		const agentHoursHeading = canvas.getByRole("heading", {
 			name: "Total agent hours",
 		});
-		await expect(canvas.getByText("435.8")).toBeInTheDocument();
-		await expect(canvas.getByText("2,000")).toBeInTheDocument();
+		const agentHoursCard = within(agentHoursHeading.closest("section")!);
+		await expect(agentHoursCard.getByText("435.8")).toBeInTheDocument();
+		await expect(agentHoursCard.getByText("2,000")).toBeInTheDocument();
 		const managedAgentsSection = canvas.getByText(
 			"Agent Workspace Builds Disabled",
 		);

From ec78225aced43c36b897608ed88135a4d226b712 Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Wed, 19 Aug 2026 12:55:28 +0000
Subject: [PATCH 18/20] 
 fix(site/src/pages/DeploymentSettingsPage/LicensesSettingsPage): wrap the
 hard cap badge and use reached wording

The shared Badge applies text-nowrap, so the full-sentence hard cap
badge overflowed narrow cards; this instance wraps instead. The badge
shows at usage equal to the hard cap (the boundary where the
concurrency cap re-engages), so it now reads "limit reached" rather
than "exceeded", which is false at equality.

Also replaces the en dash in the usage period label with a hyphen,
which broke CI at lint/emdash.
---
 .../TotalAgentHoursCard.stories.tsx             | 14 +++++++-------
 .../TotalAgentHoursCard.tsx                     | 17 ++++++++++++++---
 2 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index bbe7fef50d9..f87b1b4ff05 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -48,7 +48,7 @@ export const Default: Story = {
 		await expect(canvas.getByText("1,000")).toBeInTheDocument();
 		await expect(canvas.queryByText(/Limit:/)).not.toBeInTheDocument();
 		await expect(
-			canvas.getByText("(June 1, 2026 – May 31, 2027)"),
+			canvas.getByText("(June 1, 2026 - May 31, 2027)"),
 		).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
 		await expectTooltipText(
@@ -224,7 +224,7 @@ export const MissingUsagePeriod: Story = {
 		const canvas = within(canvasElement);
 		await expect(canvas.getByText("400.0")).toBeInTheDocument();
 		await expect(
-			canvas.queryByText("(June 1, 2026 – May 31, 2027)"),
+			canvas.queryByText("(June 1, 2026 - May 31, 2027)"),
 		).not.toBeInTheDocument();
 	},
 };
@@ -247,7 +247,7 @@ export const HardCap: Story = {
 		await expect(canvas.getByText("1,500")).toBeInTheDocument();
 		await expect(
 			canvas.queryByText(
-				"Agent hours exceeded. Concurrent chats are now limited to 5.",
+				"Agent hours limit reached. Concurrent chats are now limited to 5.",
 			),
 		).not.toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
@@ -272,7 +272,7 @@ export const HardCapBetweenSoftLimitAndLimit: Story = {
 		await expect(canvas.getByText("900.0")).toBeInTheDocument();
 		await expect(
 			canvas.queryByText(
-				"Agent hours exceeded. Concurrent chats are now limited to 5.",
+				"Agent hours limit reached. Concurrent chats are now limited to 5.",
 			),
 		).not.toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
@@ -297,7 +297,7 @@ export const HardCapBetweenLimitAndHardCap: Story = {
 		await expect(canvas.getByText("1,200.0")).toBeInTheDocument();
 		await expect(
 			canvas.queryByText(
-				"Agent hours exceeded. Concurrent chats are now limited to 5.",
+				"Agent hours limit reached. Concurrent chats are now limited to 5.",
 			),
 		).not.toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
@@ -322,7 +322,7 @@ export const ReachedHardCap: Story = {
 		await expect(canvas.getByText("1,600.0")).toBeInTheDocument();
 		await expect(
 			canvas.getByText(
-				"Agent hours exceeded. Concurrent chats are now limited to 5.",
+				"Agent hours limit reached. Concurrent chats are now limited to 5.",
 			),
 		).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
@@ -348,7 +348,7 @@ export const ReachedCoincidentHardCap: Story = {
 		await expect(canvas.getByText("1,000.0")).toBeInTheDocument();
 		await expect(
 			canvas.getByText(
-				"Agent hours exceeded. Concurrent chats are now limited to 5.",
+				"Agent hours limit reached. Concurrent chats are now limited to 5.",
 			),
 		).toBeInTheDocument();
 		const body = await hoverInfoIcon(canvasElement);
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index 78e7929e7cd..12bda78b993 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -123,7 +123,7 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	const periodEnd = usagePeriod ? dayjs(usagePeriod.end) : undefined;
 	const usagePeriodLabel =
 		periodStart?.isValid() && periodEnd?.isValid()
-			? `(${periodStart.format("MMMM D, YYYY")} – ${periodEnd.format("MMMM D, YYYY")})`
+			? `(${periodStart.format("MMMM D, YYYY")} - ${periodEnd.format("MMMM D, YYYY")})`
 			: undefined;
 
 	// Floored at one decimal so the shown percentage never crosses a
@@ -196,9 +196,20 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 
 					{reachedHardCap && (
 						<div className="flex items-center justify-end">
-							<Badge variant="destructive" size="sm" className="rounded-full">
+							{/* The concurrency cap re-engages at usage equal to the
+							    hard cap, so the badge shows at the inclusive boundary
+							    and reads "reached" (still true above it) rather than
+							    "exceeded" (false at equality). The sentence outgrows
+							    narrow cards, so this instance wraps instead of
+							    keeping the shared Badge's single-line layout. */}
+							<Badge
+								variant="destructive"
+								size="sm"
+								className="h-auto rounded-full text-wrap"
+							>
 								<BanIcon />
-								Agent hours exceeded. Concurrent chats are now limited to 5.
+								Agent hours limit reached. Concurrent chats are now limited to
+								5.
 							</Badge>
 						</div>
 					)}

From 7234162c5a2b48a2a022cea4b0005a8f02c55f11 Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Wed, 19 Aug 2026 13:13:26 +0000
Subject: [PATCH 19/20] chore: Avoid floating-point underflow in displayed
 percentages

---
 .../TotalAgentHoursCard.stories.tsx           | 25 +++++++++++++++++++
 .../TotalAgentHoursCard.tsx                   | 18 +++++++------
 2 files changed, 35 insertions(+), 8 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
index f87b1b4ff05..53e25559b45 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.stories.tsx
@@ -156,6 +156,31 @@ export const ReachedAllocationByFraction: Story = {
 	},
 };
 
+// Integer claims such as 29/100 must not underflow to 28.9% after
+// flooring a binary ratio ((29 / 100) * 100 === 28.999...).
+export const SoftLimitExactPercent: Story = {
+	args: {
+		feature: {
+			...MockAgentRuntimeHoursFeature,
+			limit: 100,
+			soft_limit: 29,
+			actual: 10,
+			actual_ms: 10 * 3_600_000,
+		},
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.getByText("10.0")).toBeInTheDocument();
+		await expect(canvas.getByText("29")).toBeInTheDocument();
+		await expect(canvas.getByText("100")).toBeInTheDocument();
+		const body = await hoverInfoIcon(canvasElement);
+		await expectTooltipText(
+			body,
+			/Total time agents have been working across all workspaces this license\. A soft-limit warning appears at 29%/,
+		);
+	},
+};
+
 // 99.9% must never read as a false 100%.
 export const NearAllocation: Story = {
 	args: {
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index 12bda78b993..3aed1f55a0e 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -48,8 +48,9 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	const meteredLimit = limit ?? 0;
 	// Floored to tenths so the displayed number and the reached states
 	// below flip together at the backend's whole-hour thresholds.
-	const usedHours =
-		actualMs === undefined ? 0 : Math.floor(actualMs / 360_000) / 10;
+	const usedTenths =
+		actualMs === undefined ? 0 : Math.floor(actualMs / 360_000);
+	const usedHours = usedTenths / 10;
 	// The backend guarantees hard >= allocation > 0; anything else comes
 	// from a decoding bug and is ignored the same way.
 	const hardCap =
@@ -128,12 +129,15 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 
 	// Floored at one decimal so the shown percentage never crosses a
 	// threshold the underlying hours have not (99.9%, never a false 100%).
-	const formatPercent = (value: number): string =>
-		(Math.floor(value * 10) / 10).toLocaleString("en-US");
+	// Tenths are computed from integer hour (or tenths-of-hour) inputs so
+	// IEEE-754 ratios such as (29 / 100) * 100 === 28.999... are not
+	// floored to 28.9%.
+	const formatPercent = (numerator: number, denominator: number): string =>
+		(Math.floor((numerator * 1000) / denominator) / 10).toLocaleString("en-US");
 
 	const softLimitPercent =
 		!isUnlimited && softLimit !== undefined && meteredLimit > 0
-			? formatPercent((softLimit / meteredLimit) * 100)
+			? formatPercent(softLimit, meteredLimit)
 			: undefined;
 
 	// A fading green fill reads as an unmetered allocation rather than
@@ -150,9 +154,7 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		// bar. The zero-limit fallback is unreachable for well-formed
 		// licenses, which report zero-hour allocations as disabled.
 		const usedPercent =
-			meteredLimit > 0
-				? formatPercent((usedHours / meteredLimit) * 100)
-				: "100";
+			meteredLimit > 0 ? formatPercent(usedTenths, meteredLimit * 10) : "100";
 		tooltip = reachedHardCap
 			? `You've used ${usedPercent}% of your Total Agent hours for this license and reached the hard cap of ${limitLabel} hours. Contact sales to receive more Agent hours.`
 			: `You've used ${usedPercent}% of your Total Agent hours for this license. Contact sales to receive more Agent hours.`;

From 1e010df5f620ce50d296f8d320d18fac97ac093d Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Wed, 19 Aug 2026 13:15:31 +0000
Subject: [PATCH 20/20] chore: cleanup

---
 .../TotalAgentHoursCard.tsx                   | 24 -------------------
 1 file changed, 24 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
index 3aed1f55a0e..4a1a6fd982f 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/TotalAgentHoursCard.tsx
@@ -46,13 +46,9 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 	}
 
 	const meteredLimit = limit ?? 0;
-	// Floored to tenths so the displayed number and the reached states
-	// below flip together at the backend's whole-hour thresholds.
 	const usedTenths =
 		actualMs === undefined ? 0 : Math.floor(actualMs / 360_000);
 	const usedHours = usedTenths / 10;
-	// The backend guarantees hard >= allocation > 0; anything else comes
-	// from a decoding bug and is ignored the same way.
 	const hardCap =
 		!isUnlimited &&
 		hardLimit !== undefined &&
@@ -60,22 +56,16 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		hardLimit >= meteredLimit
 			? hardLimit
 			: undefined;
-	// The backend warns with >=, so reaching a threshold (not exceeding
-	// it) drives the warning copy and colors.
 	const reachedAllocation =
 		!isUnlimited && actualMs !== undefined && usedHours >= meteredLimit;
 	const reachedHardCap =
 		hardCap !== undefined && actualMs !== undefined && usedHours >= hardCap;
-	// Missing usage data must not count as reaching a zero soft limit,
-	// which is valid and reached by any known usage.
 	const reachedSoftLimit =
 		!isUnlimited &&
 		!reachedAllocation &&
 		actualMs !== undefined &&
 		softLimit !== undefined &&
 		usedHours >= softLimit;
-	// With a hard cap the track spans the hard-cap range and the
-	// allocation falls at an interior marker.
 	const barScale = hardCap ?? meteredLimit;
 	const usagePercentage = isUnlimited
 		? 100
@@ -91,9 +81,6 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		!isUnlimited && softLimit !== undefined && barScale > 0
 			? Math.min((softLimit / barScale) * 100, 100)
 			: undefined;
-	// The fill is a single color for the used range: green below the
-	// soft limit, warning once the soft limit is reached, and red at or
-	// past the allocation.
 	const fillClassName = reachedAllocation
 		? "bg-highlight-red"
 		: reachedSoftLimit
@@ -117,9 +104,6 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 		: meteredLimit.toLocaleString("en-US");
 	const limitLabel = hardCap?.toLocaleString("en-US");
 
-	// The license period the usage covers. Shown under the heading so the
-	// bar is not read as a timeline. A missing or unparsable period omits
-	// the dates rather than replacing meaningful usage with an error.
 	const periodStart = usagePeriod ? dayjs(usagePeriod.start) : undefined;
 	const periodEnd = usagePeriod ? dayjs(usagePeriod.end) : undefined;
 	const usagePeriodLabel =
@@ -127,11 +111,6 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 			? `(${periodStart.format("MMMM D, YYYY")} - ${periodEnd.format("MMMM D, YYYY")})`
 			: undefined;
 
-	// Floored at one decimal so the shown percentage never crosses a
-	// threshold the underlying hours have not (99.9%, never a false 100%).
-	// Tenths are computed from integer hour (or tenths-of-hour) inputs so
-	// IEEE-754 ratios such as (29 / 100) * 100 === 28.999... are not
-	// floored to 28.9%.
 	const formatPercent = (numerator: number, denominator: number): string =>
 		(Math.floor((numerator * 1000) / denominator) / 10).toLocaleString("en-US");
 
@@ -150,9 +129,6 @@ export const TotalAgentHoursCard: FC<TotalAgentHoursCardProps> = ({
 
 	let tooltip: string;
 	if (reachedAllocation) {
-		// Measured against the allocation even when a hard cap widens the
-		// bar. The zero-limit fallback is unreachable for well-formed
-		// licenses, which report zero-hour allocations as disabled.
 		const usedPercent =
 			meteredLimit > 0 ? formatPercent(usedTenths, meteredLimit * 10) : "100";
 		tooltip = reachedHardCap