@@ -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>
 
@@ -17,7 +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 } from "./message-quota";
+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";
@@ -138,8 +138,9 @@ export function DashboardAgentChat({
           .clone()
           .json()
           .catch(() => null)) as { error?: string; limit?: number } | null;
-        if (data?.error === "message_quota_reached") {
-          setQuotaReached({ limit: data.limit ?? FREE_PLAN_MESSAGE_LIMIT });
+        const reached = parseQuotaReachedResponse(res.status, data);
+        if (reached) {
+          setQuotaReached(reached);
           throw new Error("You've reached your message limit.");
         }
       }
 
@@ -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("");
 
@@ -57,16 +60,9 @@ 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}
+        capReached ? (
+          <AgentUpgradeBlock
+            limit={capReached.limit}
             context={
               <DashboardAgentContextBanner
                 projectSlug={projectSlug}
@@ -75,7 +71,27 @@ export function DashboardAgentDraft({
               />
             }
           />
-        </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>
+        )
       }
     />
   );
 
@@ -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";
@@ -108,6 +109,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
@@ -238,14 +241,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,
@@ -287,6 +298,7 @@ export function DashboardAgentPanel({
     panelOrg.current = organization.id;
     claimChatSlot();
     setActive(null);
+    setCapReached(null);
     setLoading(false);
     setChats([]);
     setChatsLoaded(false);
@@ -614,6 +626,7 @@ export function DashboardAgentPanel({
             pageContext={pageContext}
             promotedPrompt={promotedPrompt}
             watchCard={watchCardElement}
+            capReached={capReached}
           />
         )}
       </AgentPanelColumn>
 
@@ -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(
 
@@ -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 {