feat(webapp): query boundary pinned end-to-end and a capped query retry (#4549)

## What & why

The agent's query tool is read-only, but that was true by three separate
facts and only one of them had a test. This proves the boundary holds by
contract rather than by prompt, and stops a broken query from burning a
whole agent turn.

Two small guards, the rest is tests.
[TRI-11165](https://linear.app/triggerdotdev/issue/TRI-11165).

## Stack

Stacked on **#4548** (watch-mode keepalive). Merge that first.

## What's inside

- **A route-level read-only test**
(`apps/webapp/test/queryRouteReadOnly.test.ts`) that drives
`api.v1.query` with a real signed environment JWT: a multi-statement
write and a mutating statement are both refused before anything reaches
ClickHouse, and a plain read passes so the seam stays live.
- **`readonly=1` made non-overridable** in `queryService.server.ts` —
caller `clickhouseSettings` were spread after the defaults and could
clear it.
- **A per-turn query-retry cap** in the agent's `run_query` tool
(`internal-packages/dashboard-agent/src/tool-api.ts`): three consecutive
failures returns a terminal "stop and answer with what you have".

## Key decisions

- **The read-only guarantee is grammar-level, not filtered.** TRQL has
no write statements — they don't parse — ClickHouse runs with
`readonly=1`, and the org/project/env scoping is injected server-side
from the credential. The request body can't widen scope or turn a read
into a write.
- **The deny test runs through the route, not the parser.** A
parser-only test would stay green if a refactor routed agent SQL around
the compiler; driving the real route with a signed JWT pins the boundary
end-to-end, and the deliberate positive read keeps the assertion honest.
- **The retry cap lives per turn, not in the prompt.** A failed query
hands the model the database error to fix, and usually it does — but the
only other limit was the turn's 10 steps, so one query the model
couldn't fix could eat the whole turn and leave the user with no answer.
The tool set is built per turn, so the counter caps consecutive
failures; a success resets it. The retry instruction rides the error
text, so the prompt prefix is unchanged.

## Testing

- `queryRouteReadOnly.test.ts` — write statements → 400, ClickHouse
never called; a read passes.
- `tool-query-retry-cap.test.ts` — terminal at the third consecutive
failure, counter resets on a success.
- The load-bearing guards were control-broken first (readonly override
re-enabled; cap removed) and the tests went red.

Author: kathiekiwi

.server-changes/agent-message-quota.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+The dashboard agent now comes with a monthly message allowance. A message that fails to send doesn't count against it.

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

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+Watches now respect your plan's limits: free plans can run a limited number of watches at once and for a shorter window, with a prompt to upgrade for more.

.server-changes/query-boundary-and-retry-cap.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: improvement
+---
+
+Queries stay read-only, and the agent now stops after a few failed queries in a row and answers with what it found instead of spending the whole reply retrying.

.server-changes/query-busy-retry.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+When queries are queued up and one is turned away, you now get a clear "try again shortly" instead of an error that looks like a problem with the query itself.

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

@@ -1,9 +1,10 @@
 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";
@@ -22,14 +23,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)}</p>
         <LinkButton variant="primary/small" to={v3BillingPath(organization)} fullWidth>
           Upgrade
         </LinkButton>

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

@@ -17,6 +17,7 @@ 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, parseQuotaReachedResponse } from "./message-quota";
 import { createTranscriptOrder, orderTranscript } from "./message-order";
 import { navigateDestination } from "./navigate-target";
 import { pendingNavigateIntents, pendingWatchIntents } from "./pending-intents";
@@ -102,6 +103,9 @@ export function DashboardAgentChat({
   onActivityChange?: (chatId: string, activity: TurnActivity | null) => 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 } | null>(null);
   const navigate = useNavigate();
   const location = useLocation();
   const toast = useToast();
@@ -128,6 +132,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 +201,12 @@ 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 });
+  // 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 === "reached" ? quota.limit : FREE_PLAN_MESSAGE_LIMIT);
 
   const isStreaming = status === "streaming";
   // From status, not the last part: the indicator must stay up through silent tool calls.
@@ -252,6 +271,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 +285,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);
 
@@ -414,9 +435,9 @@ export function DashboardAgentChat({
         />
       )}
       {watchCard ? <div className="px-3 pb-2">{watchCard}</div> : null}
-      {quota.kind === "reached" ? (
+      {atMessageCap ? (
         <AgentUpgradeBlock
-          limit={quota.limit}
+          limit={messageCapLimit}
           context={
             <DashboardAgentContextBanner
               projectSlug={projectSlug}

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

@@ -1,5 +1,6 @@
 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";
@@ -16,6 +17,7 @@ export function DashboardAgentDraft({
   pageContext,
   promotedPrompt,
   watchCard,
+  capReached,
 }: {
   onSubmit: (text: string) => void;
   projectSlug: string;
@@ -24,6 +26,7 @@ export function DashboardAgentDraft({
   pageContext?: AgentPageContext;
   promotedPrompt?: SuggestedPrompt;
   watchCard?: React.ReactNode;
+  capReached?: { limit: number } | null;
 }) {
   const [input, setInput] = useState("");
 
@@ -43,12 +46,14 @@ 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 (
@@ -57,25 +62,41 @@ export function DashboardAgentDraft({
       pageContext={pageContext}
       promoted={promotedPrompt}
       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}
+              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/DashboardAgentPanel.tsx

@@ -24,6 +24,7 @@ import {
   writeLastChat,
 } from "./last-chat-storage";
 import { DashboardAgentDraft } from "./DashboardAgentDraft";
+import { parseQuotaReachedResponse } from "./message-quota";
 import { WatchCard } from "./WatchCard";
 import { watchDraftFor } from "./watch-card";
 import { NO_WATCH_CARD, watchCardReducer } from "./watch-card-state";
@@ -114,6 +115,8 @@ export function DashboardAgentPanel({
   // Until the list has arrived, the page load's server count is the better answer.
   const [chatsLoaded, setChatsLoaded] = useState(false);
   const [active, setActive] = useState<ActiveChat | null>(null);
+  // A refused `create` over the cap: the draft shows the upgrade block instead of a raw toast.
+  const [capReached, setCapReached] = useState<{ limit: number } | null>(null);
   // Starts true so an `openWith` request waits for the restore instead of racing it.
   const [loading, setLoading] = useState(
     () => readLastChat(storageKey)?.path === location.pathname
@@ -260,14 +263,22 @@ export function DashboardAgentPanel({
           publicAccessToken?: string;
           headStarted?: boolean;
           error?: string;
+          limit?: number;
         };
         if (seq !== openChatRequestSeq.current) return;
         if (!res.ok || !data.chatId || !data.publicAccessToken) {
+          const reached = parseQuotaReachedResponse(res.status, data);
+          if (reached) {
+            setCapReached(reached);
+            setActive(null);
+            return;
+          }
           console.error(`Dashboard agent: failed to create chat (${res.status})`, data.error);
           toast.error(data.error ?? "We couldn't start that chat. Try again in a moment.");
           setActive(null);
           return;
         }
+        setCapReached(null);
         setActive({
           chatId: data.chatId,
           organizationId: organization.id,
@@ -309,6 +320,7 @@ export function DashboardAgentPanel({
     panelOrg.current = organization.id;
     claimChatSlot();
     setActive(null);
+    setCapReached(null);
     setLoading(false);
     setChats([]);
     setChatsLoaded(false);
@@ -634,6 +646,7 @@ export function DashboardAgentPanel({
             pageContext={pageContext}
             promotedPrompt={promotedPrompt}
             watchCard={watchCardElement}
+            capReached={capReached}
           />
         )}
       </AgentPanelColumn>

apps/webapp/app/components/dashboard-agent/message-quota.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, it } from "vitest";
-import { countUserMessages, FREE_PLAN_MESSAGE_LIMIT, resolveMessageQuota } from "./message-quota";
+import {
+  countUserMessages,
+  FREE_PLAN_MESSAGE_LIMIT,
+  MESSAGE_QUOTA_REACHED_ERROR,
+  messageQuotaReachedCopy,
+  parseQuotaReachedResponse,
+  resolveMessageQuota,
+} from "./message-quota";
 
 describe("resolveMessageQuota", () => {
   it("caps a Free plan at the limit", () => {
@@ -42,6 +49,37 @@ describe("resolveMessageQuota", () => {
   });
 });
 
+describe("parseQuotaReachedResponse", () => {
+  it("maps a create/in 403 cap body to the limit", () => {
+    // Both the create path and the `in` transport refuse with this exact body.
+    expect(
+      parseQuotaReachedResponse(403, { error: MESSAGE_QUOTA_REACHED_ERROR, limit: 20 })
+    ).toEqual({ limit: 20 });
+  });
+
+  it("falls back to the free limit when the body omits it", () => {
+    expect(parseQuotaReachedResponse(403, { error: MESSAGE_QUOTA_REACHED_ERROR })).toEqual({
+      limit: FREE_PLAN_MESSAGE_LIMIT,
+    });
+  });
+
+  it("ignores other errors and non-403 statuses so they surface normally", () => {
+    expect(parseQuotaReachedResponse(403, { error: "something_else" })).toBeNull();
+    expect(parseQuotaReachedResponse(500, { error: MESSAGE_QUOTA_REACHED_ERROR })).toBeNull();
+    expect(parseQuotaReachedResponse(403, null)).toBeNull();
+  });
+});
+
+describe("messageQuotaReachedCopy", () => {
+  it("is a friendly sentence naming the limit, never the raw code", () => {
+    const copy = messageQuotaReachedCopy(20);
+    expect(copy).toContain("all 20 messages");
+    expect(copy).toContain("Free plan");
+    // Control break: if the mapping leaked the server code, this fails.
+    expect(copy).not.toContain(MESSAGE_QUOTA_REACHED_ERROR);
+  });
+});
+
 describe("countUserMessages", () => {
   it("counts only what the user sent", () => {
     expect(

apps/webapp/app/components/dashboard-agent/message-quota.ts

@@ -27,6 +27,28 @@ export function resolveMessageQuota({
     : { kind: "within", used, limit, remaining };
 }
 
+// The server code both the create and `in` paths refuse with. The client owns the copy,
+// so this code must never reach the UI as text.
+export const MESSAGE_QUOTA_REACHED_ERROR = "message_quota_reached";
+
+// Maps a 403 refusal body to the cap signal, or null for any other error. Both paths use
+// this so a `message_quota_reached` code routes to the upgrade block, never a raw toast.
+export function parseQuotaReachedResponse(
+  status: number,
+  data: { error?: string; limit?: number } | null | undefined
+): { limit: number } | null {
+  if (status === 403 && data?.error === MESSAGE_QUOTA_REACHED_ERROR) {
+    return { limit: data.limit ?? FREE_PLAN_MESSAGE_LIMIT };
+  }
+  return null;
+}
+
+// The upgrade block's sentence. Pure so the copy is asserted directly, and so the raw
+// server code can never be what the user reads.
+export function messageQuotaReachedCopy(limit: number): string {
+  return `You've used all ${limit} messages included on the Free plan. Your chats stay here to read.`;
+}
+
 // A watch's consent record is a user message the person never typed, so it is
 // excluded here exactly as the stored count excludes it.
 export function countUserMessages(messages: { role: string; id?: string }[]): number {