feat(webapp,sdk): dashboard agent plan enforcement, component gallery — and fixes (#4516)

Plan enforcement for the dashboard agent — message quota and watch
limits — plus the component gallery, fixes and test hardening from the
same stack (#4548, #4549, #4550, #4552, #4556 merged here).

## Plan enforcement
([TRI-12863](https://linear.app/triggerdotdev/issue/TRI-12863))

**Agent message quota.** The Free-plan allowance becomes a real
server-side limit with a durable counter. New `agent_message_usage`
table keyed `(organization_id, period)` — deliberately not joined to
chats, so deleting a chat can't free quota within the period. Both send
paths count one user message (wakes never count) and refuse at the cap
with `403 message_quota_reached`, which the client renders as an upgrade
panel, never a silent drop. The refusal code is a single shared constant
on both sides.

**Watch limits.** A watch whose window exceeds the plan's
`agentWatchMaxHours`, or that would push the org past its
`agentWatchers` count, is refused with `watch_limit_reached` (409 on the
API, an upgrade hint on the card). Plan limits only tighten the existing
code ceilings (`min(plan, 24h)`, per-chat cap of 3 still applies). A
plan limit of zero means zero, not unlimited. Questions answerable
instantly are answered before any plan refusal — a one-shot consumes no
slot and never sees an upgrade nag.

**Fails open by design.** Cloud ships the actual per-plan numbers
separately (TRI-12863 P0). Until then absent limits resolve to the
unlimited sentinel and the upgrade UI is gated on billing presence —
self-hosted sees no cap, no upsell, with tests proving the fallback.
Both quotas are nudges, not security boundaries: a failing limit read
never blocks a send.

## Component gallery

An admin-only gallery of every agent card state: five
`storybook.agent-*` pages (chat UI, view blocks, report, investigation,
watch) with their shared shell and manifest, demo fixtures, two
demo-only cards, toast examples, and the screenshot script. No LLM and
no data — every state renders from fixtures under
`dashboard-agent/demo/`, never reachable from a production path.
Designers and reviewers can look at every state, including the report
states, without seeding anything.

## And fixes

**SDK: watch-mode chat subscriptions survive quiet windows** (TRI-13065,
TRI-13070) — watch mode keeps reconnecting across empty long-poll
windows and only stops on abort or a settled session; a passive
subscriber can no longer stop a turn it doesn't own (`stopOnAbort` is
explicit, default off). Review findings fixed alongside: a superseded
stream's async teardown no longer removes the live successor's abort
controller or multi-tab claim, and stopping a generation hands the chat
back to the user's other tabs.

**Query boundary pinned end-to-end**
([TRI-11165](https://linear.app/triggerdotdev/issue/TRI-11165)) — a
route-level test drives `api.v1.query` with a real signed environment
JWT (writes refused before ClickHouse, a read passes); `readonly=1` made
non-overridable; a per-turn cap stops the model burning a turn rewriting
a query it can't fix (deterministic SQL errors only — busy/transport
rejections don't count).

**chat.agent durability regression suite**
([TRI-11166](https://linear.app/triggerdotdev/issue/TRI-11166)) —
testcontainers-backed coverage of the two audit criticals (cross-tenant
isolation, no duplicate mid-stream turn, both control-broken) plus
crash-resume, cursor-based refresh, clean rollback of a mid-write turn
failure (torn by a real constraint violation), and OOM-restart replay.

**Investigation sweep backoff** — stale investigations get an attempt
counter and backoff so a poison row can't pin the sweep queue head
(migration `0005`: `sweep_attempts`, `last_sweep_attempt_at`).

## Screenshots

<img width="1440" height="791" alt="Screenshot 2026-08-06 at 00 36 19"
src="https://github.com/user-attachments/assets/6a68cd42-8580-469d-afe7-e28d1eef18e1"
/>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: kathiekiwi

.changeset/dashboard-agent-chat-streams.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Watch-mode chat streams now survive quiet windows and page reloads, and a reply cut off by a lost connection shows an error instead of appearing finished. Aborting a resumed subscription only closes your local stream — call `stopGeneration(chatId)` or pass `stopOnAbort: true` to stop the run. Also fixed a race where quickly restarting a stream could break stop and reconnect, and stopping a chat now hands it back to your other tabs instead of leaving them read-only.

.server-changes/agent-plan-limits.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+The dashboard agent now has a monthly message allowance and plan-based limits on watches. Queries stay read-only with clearer errors when busy, and messages with unusual characters no longer fail to send.

apps/webapp/app/components/dashboard-agent/AgentUpgradeGate.tsx

@@ -1,18 +1,21 @@
 import { Link } from "@remix-run/react";
+import { AgentMonoLogo } from "~/components/primitives/AgentDotMatrix";
 import { LinkButton } from "~/components/primitives/Buttons";
 import { useOrganization } from "~/hooks/useOrganizations";
-import { cn } from "~/utils/cn";
 import { v3BillingPath } from "~/utils/pathBuilder";
-import { AgentIcon, AGENT_ICON_ACCENT_CLASS, ASK_AGENT_LABEL } from "./agent-identity";
+import { ASK_AGENT_LABEL } from "./agent-identity";
+import { messageQuotaReachedCopy } from "./message-quota";
 
 // Matches the composer's outer geometry so the replacement lands in the same place.
 const SLOT = "flex shrink-0 flex-col bg-background-bright px-3 pb-3 pt-1";
 
 export function AgentUpgradeBlock({
   limit,
+  planResolved,
   context,
 }: {
   limit: number;
+  planResolved: boolean;
   context?: React.ReactNode;
 }) {
   const organization = useOrganization();
@@ -22,14 +25,12 @@ export function AgentUpgradeBlock({
       {context}
       <div className="mt-1.5 flex flex-col gap-2 rounded-md border border-border-bright bg-background-dimmed p-3">
         <div className="flex items-center gap-1.5">
-          <AgentIcon className={cn("size-4 shrink-0", AGENT_ICON_ACCENT_CLASS)} />
+          <AgentMonoLogo size={16} decorative className="shrink-0" />
           <span className="text-sm font-medium text-text-bright">
             Upgrade to unlock {ASK_AGENT_LABEL}
           </span>
         </div>
-        <p className="text-xs text-text-dimmed">
-          You've used all {limit} messages included on the Free plan. Your chats stay here to read.
-        </p>
+        <p className="text-xs text-text-dimmed">{messageQuotaReachedCopy(limit, planResolved)}</p>
         <LinkButton variant="primary/small" to={v3BillingPath(organization)} fullWidth>
           Upgrade
         </LinkButton>

apps/webapp/app/components/dashboard-agent/DashboardAgentChat.tsx

@@ -17,6 +17,12 @@ import { DashboardAgentContextBanner } from "./DashboardAgentContextBanner";
 import { DashboardAgentHero } from "./DashboardAgentHero";
 import { DashboardAgentMessages, type TurnActivity } from "./DashboardAgentMessages";
 import { MESSAGE_TOO_LARGE_ERROR } from "./message-limits";
+import {
+  FREE_PLAN_MESSAGE_LIMIT,
+  MESSAGE_QUOTA_REACHED_REASON,
+  parseQuotaReachedResponse,
+  type MessageQuota,
+} from "./message-quota";
 import { createTranscriptOrder, orderTranscript } from "./message-order";
 import { navigateDestination } from "./navigate-target";
 import { pendingNavigateIntents, pendingWatchIntents } from "./pending-intents";
@@ -73,6 +79,7 @@ export function DashboardAgentChat({
   onCancelWatch,
   onTurnSettled,
   onActivityChange,
+  onQuotaChange,
 }: {
   chatId: string;
   initialMessages: UIMessage[];
@@ -100,8 +107,15 @@ export function DashboardAgentChat({
   onCancelWatch: (watchId: string) => void;
   onTurnSettled: () => void;
   onActivityChange?: (chatId: string, activity: TurnActivity | null) => void;
+  /** The poll lives here, so this is where the panel learns the cap has lifted. */
+  onQuotaChange?: (quota: MessageQuota) => void;
 }) {
   const [input, setInput] = useState("");
+  // Set when the server refuses a send over the cap, so the block shows at once rather than
+  // waiting for the next quota poll.
+  const [quotaReached, setQuotaReached] = useState<{ limit: number; planResolved: boolean } | null>(
+    null
+  );
   const navigate = useNavigate();
   const location = useLocation();
   const toast = useToast();
@@ -128,6 +142,18 @@ export function DashboardAgentChat({
           .catch(() => null)) as { error?: string } | null;
         throw new Error(data?.error ?? MESSAGE_TOO_LARGE_ERROR);
       }
+      // Over the message cap: show the upgrade block instead of a generic turn error.
+      if (res.status === 403) {
+        const data = (await res
+          .clone()
+          .json()
+          .catch(() => null)) as { error?: string; limit?: number } | null;
+        const reached = parseQuotaReachedResponse(res.status, data);
+        if (reached) {
+          setQuotaReached(reached);
+          throw new Error("You've reached your message limit.");
+        }
+      }
       return res;
     },
     clientData,
@@ -185,9 +211,20 @@ export function DashboardAgentChat({
   const orderRef = useRef(createTranscriptOrder(initialMessages));
   const messages = orderTranscript(rawMessages, orderRef.current);
 
-  // Counted here, not in the panel, so it includes the turn just sent.
-  const quota = useAgentMessageQuota({ actionPath, chatId, messages });
-  const atMessageCap = quota.kind === "reached";
+  // Read here, not in the panel, so it re-reads as each turn settles.
+  const quota = useAgentMessageQuota({ actionPath, chatId, status });
+  useEffect(() => {
+    onQuotaChange?.(quota);
+    // The quota object is rebuilt every render; only its kind is acted on.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [quota.kind, onQuotaChange]);
+  // Either the poll saw the cap, or a send was just refused over it.
+  const atMessageCap = quota.kind === "reached" || quotaReached !== null;
+  const messageCapLimit =
+    quotaReached?.limit ?? (quota.kind === "unlimited" ? FREE_PLAN_MESSAGE_LIMIT : quota.limit);
+  // The poll only runs on the free plan, so its cap is the free-plan nudge; a refusal
+  // carries the plan limit the server resolved.
+  const messageCapPlanResolved = quotaReached?.planResolved ?? false;
 
   const isStreaming = status === "streaming";
   // From status, not the last part: the indicator must stay up through silent tool calls.
@@ -252,6 +289,8 @@ export function DashboardAgentChat({
   }, [sendRequest, submit, canSend]);
 
   const retry = useCallback(() => {
+    // Over the cap, a retry only earns another 403 — same guard as `submit`.
+    if (atMessageCap) return;
     // A watch's consent record is a user message nobody typed, so retry never treats it as one.
     const action = retryAction(
       messages.filter((m) => !(m.role === "user" && isWatchRequestMessageId(m.id)))
@@ -264,7 +303,7 @@ export function DashboardAgentChat({
       return;
     }
     void sendMessage({ text: action.text, messageId: action.messageId });
-  }, [messages, sendMessage, regenerate, clearError]);
+  }, [messages, sendMessage, regenerate, clearError, atMessageCap]);
 
   const resolveUri = useTriggerUriResolver(actionPath);
 
@@ -399,13 +438,15 @@ export function DashboardAgentChat({
           onSelect={submit}
           pageContext={clientData.pageContext}
           promoted={promotedPrompt}
+          promptsDisabledReason={atMessageCap ? MESSAGE_QUOTA_REACHED_REASON : undefined}
         />
       ) : (
         <DashboardAgentMessages
           messages={messages}
           activity={activity}
           error={error}
           onRetry={retry}
+          retryDisabledReason={atMessageCap ? MESSAGE_QUOTA_REACHED_REASON : undefined}
           onDismissError={clearError}
           onIntent={handleIntent}
           pagePaths={pagePaths}
@@ -414,9 +455,10 @@ export function DashboardAgentChat({
         />
       )}
       {watchCard ? <div className="px-3 pb-2">{watchCard}</div> : null}
-      {quota.kind === "reached" ? (
+      {atMessageCap ? (
         <AgentUpgradeBlock
-          limit={quota.limit}
+          limit={messageCapLimit}
+          planResolved={messageCapPlanResolved}
           context={
             <DashboardAgentContextBanner
               projectSlug={projectSlug}

apps/webapp/app/components/dashboard-agent/DashboardAgentComposer.tsx

@@ -1,4 +1,5 @@
 import { ArrowUpIcon, StopIcon } from "@heroicons/react/20/solid";
+import { sliceWellFormed } from "@internal/dashboard-agent-contracts";
 import { useEffect, useRef } from "react";
 import { Button } from "~/components/primitives/Buttons";
 import { cn } from "~/utils/cn";
@@ -94,7 +95,7 @@ export function DashboardAgentComposer({
             maxLength={MAX_MESSAGE_CHARS}
             onChange={(e) => {
               escapeGuardArmed.current = true;
-              onChange(e.target.value.slice(0, MAX_MESSAGE_CHARS));
+              onChange(sliceWellFormed(e.target.value, MAX_MESSAGE_CHARS));
             }}
             onBlur={() => {
               escapeGuardArmed.current = true;

apps/webapp/app/components/dashboard-agent/DashboardAgentDraft.tsx

@@ -1,8 +1,10 @@
 import type { SuggestedPrompt } from "@internal/dashboard-agent-contracts";
 import { useCallback, useMemo, useState } from "react";
+import { AgentUpgradeBlock } from "./AgentUpgradeGate";
 import { DashboardAgentComposer } from "./DashboardAgentComposer";
 import { DashboardAgentContextBanner } from "./DashboardAgentContextBanner";
 import { DashboardAgentHero } from "./DashboardAgentHero";
+import { MESSAGE_QUOTA_REACHED_REASON } from "./message-quota";
 import type { AgentPageContext } from "./page-context-types";
 import { readDismissedPromptIds, resolveSuggestedPromptsBySlot } from "./suggested-prompts";
 
@@ -16,6 +18,7 @@ export function DashboardAgentDraft({
   pageContext,
   promotedPrompt,
   watchCard,
+  capReached,
 }: {
   onSubmit: (text: string) => void;
   projectSlug: string;
@@ -24,6 +27,7 @@ export function DashboardAgentDraft({
   pageContext?: AgentPageContext;
   promotedPrompt?: SuggestedPrompt;
   watchCard?: React.ReactNode;
+  capReached?: { limit: number; planResolved: boolean } | null;
 }) {
   const [input, setInput] = useState("");
 
@@ -43,39 +47,59 @@ export function DashboardAgentDraft({
 
   const submit = useCallback(
     (text: string) => {
+      // Suggested prompts reach here via the hero, bypassing the composer's cap guard.
+      if (capReached) return;
       const trimmed = text.trim();
       if (!trimmed) return;
       setInput("");
       onSubmit(trimmed);
     },
-    [onSubmit]
+    [onSubmit, capReached]
   );
 
   return (
     <DashboardAgentHero
       onSelect={submit}
       pageContext={pageContext}
       promoted={promotedPrompt}
+      promptsDisabledReason={capReached ? MESSAGE_QUOTA_REACHED_REASON : undefined}
       composer={
-        <div className="flex w-full flex-col gap-3">
-          {watchCard}
-          <DashboardAgentComposer
-            layout="hero"
-            value={input}
-            onChange={setInput}
-            onSubmit={() => submit(input)}
-            onStop={() => {}}
-            isStreaming={false}
-            placeholderSuggestion={watchCard ? undefined : placeholderSuggestion}
-            context={
-              <DashboardAgentContextBanner
-                projectSlug={projectSlug}
-                environmentSlug={environmentSlug}
-                currentPage={currentPage}
-              />
-            }
-          />
-        </div>
+        capReached ? (
+          <div className="flex w-full flex-col gap-3">
+            {watchCard}
+            <AgentUpgradeBlock
+              limit={capReached.limit}
+              planResolved={capReached.planResolved}
+              context={
+                <DashboardAgentContextBanner
+                  projectSlug={projectSlug}
+                  environmentSlug={environmentSlug}
+                  currentPage={currentPage}
+                />
+              }
+            />
+          </div>
+        ) : (
+          <div className="flex w-full flex-col gap-3">
+            {watchCard}
+            <DashboardAgentComposer
+              layout="hero"
+              value={input}
+              onChange={setInput}
+              onSubmit={() => submit(input)}
+              onStop={() => {}}
+              isStreaming={false}
+              placeholderSuggestion={watchCard ? undefined : placeholderSuggestion}
+              context={
+                <DashboardAgentContextBanner
+                  projectSlug={projectSlug}
+                  environmentSlug={environmentSlug}
+                  currentPage={currentPage}
+                />
+              }
+            />
+          </div>
+        )
       }
     />
   );

apps/webapp/app/components/dashboard-agent/DashboardAgentHero.tsx

@@ -11,13 +11,16 @@ export function DashboardAgentHero({
   promoted,
   dismissedIds,
   composer,
+  promptsDisabledReason,
 }: {
   /** Receives the prompt text to send, not the button label. */
   onSelect: (prompt: string) => void;
   pageContext?: AgentPageContext;
   promoted?: SuggestedPrompt;
   dismissedIds?: string[];
   composer?: React.ReactNode;
+  /** Set to disable the suggestion chips and say why. */
+  promptsDisabledReason?: string;
 }) {
   // Centred by the child's `m-auto`, not by `justify-center`: auto margins give up their space
   // once the content outgrows the panel, so the heading stays scrollable to.
@@ -40,6 +43,7 @@ export function DashboardAgentHero({
           pageContext={pageContext}
           promoted={promoted}
           dismissedIds={dismissedIds}
+          disabledReason={promptsDisabledReason}
         />
       </div>
     </div>

apps/webapp/app/components/dashboard-agent/DashboardAgentMessages.tsx

@@ -35,6 +35,8 @@ export type DashboardAgentMessagesProps = {
   activity: TurnActivity | null;
   error?: Error;
   onRetry?: () => void;
+  /** Set to disable the retry button and say why, e.g. over the message cap. */
+  retryDisabledReason?: string;
   onDismissError?: () => void;
   onIntent?: (intent: AgentIntent) => void;
   resolveUri?: (uri: string) => ResolvedUri | null;
@@ -356,6 +358,7 @@ export function DashboardAgentTurns({
   activity,
   error,
   onRetry,
+  retryDisabledReason,
   onDismissError,
   onIntent,
   resolveUri,
@@ -402,7 +405,16 @@ export function DashboardAgentTurns({
                 (onRetry || onDismissError) && (
                   <ChatActionsRow>
                     {onRetry && (
-                      <Button variant="primary/small" LeadingIcon={ArrowPathIcon} onClick={onRetry}>
+                      <Button
+                        variant="primary/small"
+                        LeadingIcon={ArrowPathIcon}
+                        onClick={onRetry}
+                        disabled={!!retryDisabledReason}
+                        tooltip={retryDisabledReason}
+                        aria-label={
+                          retryDisabledReason ? `Try again — ${retryDisabledReason}` : undefined
+                        }
+                      >
                         Try again
                       </Button>
                     )}