From 3b853be8d46237138ac283a9ac6c7ebc046727b1 Mon Sep 17 00:00:00 2001
From: Taki Koutsomitis <koutst@protonmail.com>
Date: Fri, 4 Sep 2026 09:03:56 -0400
Subject: [PATCH] Add notebook AI access, model eligibility, and usage limits

---
 .../Notebook/AgentChat/AgentChatPanel.tsx     | 261 ++++++++++++++----
 .../Notebook/AgentChat/ChatComposer.tsx       |   2 +
 .../Notebook/AgentChat/ChatTranscript.tsx     |   4 +-
 .../Notebook/AgentChat/ExecutionProgress.tsx  |  11 +-
 .../Notebook/AgentChat/ModelControls.tsx      |  11 +-
 components/Notebook/AgentChat/UsageMeter.tsx  |  75 +++++
 components/Notebook/NoteEditorLayout.tsx      |   8 +-
 hooks/useAgentModelSelection.ts               |  58 ++--
 hooks/useAgentModels.ts                       |  85 +++---
 hooks/useNotebookChat.ts                      |  47 +++-
 hooks/useNotebookChatSocket.ts                |   2 +-
 hooks/useResearchAiUsage.ts                   | 107 +++++++
 services/agentModel.service.ts                |   5 +-
 services/notebookChat.service.ts              |  10 +-
 store/researchAiJobs.ts                       |  79 ++++++
 types/notebookChat.ts                         |   1 +
 types/notebookModels.ts                       |   6 +-
 types/researchAiUsage.ts                      |  39 +++
 18 files changed, 666 insertions(+), 145 deletions(-)
 create mode 100644 components/Notebook/AgentChat/UsageMeter.tsx
 create mode 100644 hooks/useResearchAiUsage.ts
 create mode 100644 store/researchAiJobs.ts
 create mode 100644 types/researchAiUsage.ts

diff --git a/components/Notebook/AgentChat/AgentChatPanel.tsx b/components/Notebook/AgentChat/AgentChatPanel.tsx
index 5d5f6c7d4..c1cd92a47 100644
--- a/components/Notebook/AgentChat/AgentChatPanel.tsx
+++ b/components/Notebook/AgentChat/AgentChatPanel.tsx
@@ -9,6 +9,9 @@ import { Loader } from '@/components/ui/Loader';
 import { cn } from '@/utils/styles';
 import { useNotebookContext } from '@/contexts/NotebookContext';
 import { useNotebookChat, useNotebookChatList, type SendOutcome } from '@/hooks/useNotebookChat';
+import { useResearchAiUsage } from '@/hooks/useResearchAiUsage';
+import { AI_BUSY_MESSAGE, isUsageExhausted, usageLimitMessage } from '@/types/researchAiUsage';
+import { UsageMeter } from './UsageMeter';
 import { useAgentModelSelection } from '@/hooks/useAgentModelSelection';
 import { MAX_AGENT_CHAT_WIDTH, MIN_AGENT_CHAT_WIDTH } from '@/hooks/useAgentChatWidth';
 import { useNoteVersionSocket } from '@/hooks/useNoteVersionSocket';
@@ -57,7 +60,14 @@ function noticeFromOutcome(outcome: SendOutcome & { ok: false }): ComposerNotice
     case 'busy':
       return {
         tone: 'warning',
-        text: outcome.detail ?? 'The assistant is still working on a previous message.',
+        text: AI_BUSY_MESSAGE,
+      };
+    case 'limit':
+      return { tone: 'warning', kind: 'limit', text: usageLimitMessage(null) };
+    case 'model_not_allowed':
+      return {
+        tone: 'warning',
+        text: 'Your available models or settings have changed. Choose an allowed option before sending again. Start a new chat to change a locked model.',
       };
     case 'invalid':
       return { tone: 'error', text: outcome.detail ?? 'That message can’t be sent.' };
@@ -250,6 +260,8 @@ export function AgentChatPanel({
   const promoBannerVisible = promoStatus === 'checked' && !promoDismissed;
 
   const list = useNotebookChatList(noteId, open);
+  const usage = useResearchAiUsage(open);
+  const usageExhausted = isUsageExhausted(usage.budget);
   // Null is the new-chat screen, and it is where a page visit starts: the
   // assistant opens on its own opening moves rather than dropping the reader
   // into the middle of whatever they last asked. Earlier chats stay one click
@@ -281,6 +293,7 @@ export function AgentChatPanel({
   const modelSelection = useAgentModelSelection({
     enabled: open,
     pinnedRef: chatState.pinnedModelRef,
+    started: (chatState.chat?.executions.length ?? 0) > 0 || chatState.pendingSend != null,
   });
 
   // ---- drafts (per chat, surviving switches and failed sends) ----
@@ -293,6 +306,8 @@ export function AgentChatPanel({
   const [creatingChat, setCreatingChat] = useState(false);
   /** Identity of the latest creation, so a stale settle can't clear its flag. */
   const creationSeqRef = useRef(0);
+  const sendingRef = useRef(false);
+  const dispatchedFirstMessage = useRef<QueuedMessage | null>(null);
 
   /** Draft writes go through here so the per-chat map stays in sync. */
   const updateDraft = useCallback(
@@ -344,10 +359,14 @@ export function AgentChatPanel({
 
   // ---- server-side access gate ----
   useEffect(() => {
-    if (list.access === 'hidden' || chatState.access === 'unauthorized') {
+    if (
+      list.access === 'hidden' ||
+      chatState.access === 'unauthorized' ||
+      modelSelection.status === 'unauthorized'
+    ) {
       onUnavailable();
     }
-  }, [list.access, chatState.access, onUnavailable]);
+  }, [list.access, chatState.access, modelSelection.status, onUnavailable]);
 
   // ---- keep the listing fresh as the open chat evolves ----
   // Derived titles land after the first turn, previews/spinners change as
@@ -366,6 +385,49 @@ export function AgentChatPanel({
     if (open && changed) refreshList();
   }, [open, latestStatus, chatTitle, refreshList]);
 
+  const refreshUsage = usage.refresh;
+  const refreshModels = modelSelection.refresh;
+  const failureNotice = useCallback(
+    async (outcome: SendOutcome & { ok: false }): Promise<ComposerNotice> => {
+      if (outcome.reason === 'limit') {
+        const budget = await refreshUsage();
+        return {
+          tone: 'warning',
+          kind: 'limit',
+          resetsAt: budget?.resets_at,
+          text: usageLimitMessage(budget),
+        };
+      }
+      if (outcome.reason === 'model_not_allowed') await refreshModels();
+      if (outcome.reason === 'busy') void refreshList();
+      return noticeFromOutcome(outcome);
+    },
+    [refreshUsage, refreshModels, refreshList]
+  );
+
+  const terminalExecution = chatState.latestExecution;
+  const terminalSignal =
+    terminalExecution && !isActiveExecutionStatus(terminalExecution.status)
+      ? `${selectedChatId}:${terminalExecution.id}:${terminalExecution.status}`
+      : null;
+  const limitDuringRun = terminalExecution?.error?.code === 'usage_limit_exceeded';
+  useEffect(() => {
+    if (!open || !terminalSignal) return;
+    let cancelled = false;
+    refreshUsage().then((budget) => {
+      if (!cancelled && limitDuringRun)
+        setNotice({
+          tone: 'warning',
+          kind: 'limit',
+          resetsAt: budget?.resets_at,
+          text: usageLimitMessage(budget),
+        });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [open, terminalSignal, limitDuringRun, refreshUsage]);
+
   // ---- sending ----
   // Live mirror of the panel's target. Async continuations compare against it
   // and discard results that raced a chat or note switch instead of applying
@@ -376,6 +438,13 @@ export function AgentChatPanel({
     chatId: selectedChatId,
   });
   targetRef.current = { noteId, chatId: selectedChatId };
+  useEffect(() => {
+    targetRef.current = { noteId, chatId: selectedChatId };
+    return () => {
+      // A pending note fetch must not apply content after this panel unmounts.
+      targetRef.current = { noteId: '', chatId: null };
+    };
+  }, []);
   const isCurrentTarget = useCallback(
     (target: { noteId: string; chatId: number | null }) =>
       targetRef.current.noteId === target.noteId && targetRef.current.chatId === target.chatId,
@@ -384,48 +453,68 @@ export function AgentChatPanel({
 
   const handleSend = useCallback(async () => {
     const text = draft.trim();
-    if (!text) return;
+    if (
+      !text ||
+      sendingRef.current ||
+      usage.busy ||
+      usageExhausted ||
+      chatState.isBusy ||
+      chatState.isFinishing ||
+      creatingChat ||
+      queuedMessage ||
+      modelSelection.status !== 'ok' ||
+      (!modelSelection.pinned && !modelSelection.model)
+    )
+      return;
+    if (selectedChatId == null ? list.access !== 'ok' : chatState.access !== 'ok') return;
+    sendingRef.current = true;
     setNotice(null);
-    const target = targetRef.current;
-    // Captured before the awaits: the turn runs on what was selected when the
-    // user pressed send, not on whatever the picker says by the time it lands.
-    const generation = modelSelection.request;
-
-    if (selectedChatId == null) {
-      // Default flow: create untitled, send the first message; the refetch
-      // after the turn brings the derived title.
-      const creationSeq = ++creationSeqRef.current;
-      setCreatingChat(true);
-      const created = await list.createChat();
-      // A newer creation may own the flag by now (the user moved to another
-      // note and started a chat there) — a stale settle must not unblock its
-      // composer while that creation is still in flight.
-      if (creationSeqRef.current === creationSeq) setCreatingChat(false);
-      // Switched note or picked an existing chat meanwhile — abandon the
-      // creation instead of yanking the selection to a stale chat.
-      if (!isCurrentTarget(target)) return;
-      if (!created) {
-        setNotice({ tone: 'error', text: 'Couldn’t start a chat. Please try again.' });
+    try {
+      const target = targetRef.current;
+      // Captured before the awaits: the turn runs on what was selected when the
+      // user pressed send, not on whatever the picker says by the time it lands.
+      const generation = modelSelection.request;
+
+      if (selectedChatId == null) {
+        // Default flow: create untitled, send the first message; the refetch
+        // after the turn brings the derived title.
+        const creationSeq = ++creationSeqRef.current;
+        setCreatingChat(true);
+        const created = await list.createChat();
+        // A newer creation may own the flag by now (the user moved to another
+        // note and started a chat there) — a stale settle must not unblock its
+        // composer while that creation is still in flight.
+        if (creationSeqRef.current === creationSeq) setCreatingChat(false);
+        // Switched note or picked an existing chat meanwhile — abandon the
+        // creation instead of yanking the selection to a stale chat.
+        if (!isCurrentTarget(target)) return;
+        if (!created) {
+          setNotice({ tone: 'error', text: 'Couldn’t start a chat. Please try again.' });
+          return;
+        }
+        draftsRef.current.delete('new');
+        draftsRef.current.set(String(created.conversation_id), text);
+        setInitialChat(created);
+        setSelectedChatId(created.conversation_id);
+        setQueuedMessage({ text, generation });
         return;
       }
-      draftsRef.current.delete('new');
-      setInitialChat(created);
-      setSelectedChatId(created.conversation_id);
-      setQueuedMessage({ text, generation });
-      return;
-    }
 
-    const outcome = await chatState.send(text, generation);
-    if (outcome.ok) {
-      if (isCurrentTarget(target)) {
-        updateDraft('');
+      const outcome = await chatState.send(text, generation);
+      if (outcome.ok) {
+        if (isCurrentTarget(target)) {
+          if (draftsRef.current.get(String(target.chatId))?.trim() === text) updateDraft('');
+        } else {
+          // Sent fine, but the user moved on — just retire the sent draft.
+          if (draftsRef.current.get(String(target.chatId))?.trim() === text)
+            draftsRef.current.delete(String(target.chatId));
+        }
       } else {
-        // Sent fine, but the user moved on — just retire the sent draft.
-        draftsRef.current.delete(String(target.chatId));
+        const nextNotice = await failureNotice(outcome);
+        if (isCurrentTarget(target)) setNotice(nextNotice);
       }
-    } else if (isCurrentTarget(target)) {
-      // Keep the draft on any failure.
-      setNotice(noticeFromOutcome(outcome));
+    } finally {
+      sendingRef.current = false;
     }
   }, [
     draft,
@@ -435,26 +524,46 @@ export function AgentChatPanel({
     modelSelection.request,
     updateDraft,
     isCurrentTarget,
+    usage.busy,
+    usageExhausted,
+    creatingChat,
+    queuedMessage,
+    modelSelection.status,
+    modelSelection.pinned,
+    modelSelection.model,
+    failureNotice,
   ]);
 
-  // Fire the queued first message once the freshly created chat is live.
+  // Dispatch the first message once the newly created chat is ready. Rejections
+  // stay drafts; this handoff never retries a refused POST.
   const sendToChat = chatState.send;
   useEffect(() => {
     if (queuedMessage == null || selectedChatId == null || chatState.access !== 'ok') return;
+    if (dispatchedFirstMessage.current === queuedMessage) return;
+    dispatchedFirstMessage.current = queuedMessage;
     const { text, generation } = queuedMessage;
     const target = targetRef.current;
     setQueuedMessage(null);
-    sendToChat(text, generation).then((outcome) => {
-      if (outcome.ok) return;
-      if (isCurrentTarget(target)) {
-        setNotice(noticeFromOutcome(outcome));
-        updateDraft(text);
-      } else {
-        // Failed after a switch — keep the unsent text under its own chat.
-        draftsRef.current.set(String(target.chatId), text);
+    sendToChat(text, generation).then(async (outcome) => {
+      if (outcome.ok) {
+        if (draftsRef.current.get(String(target.chatId))?.trim() === text) {
+          if (isCurrentTarget(target)) updateDraft('');
+          else draftsRef.current.delete(String(target.chatId));
+        }
+        return;
       }
+      const nextNotice = await failureNotice(outcome);
+      if (isCurrentTarget(target)) setNotice(nextNotice);
     });
-  }, [queuedMessage, selectedChatId, chatState.access, sendToChat, updateDraft, isCurrentTarget]);
+  }, [
+    queuedMessage,
+    selectedChatId,
+    chatState.access,
+    sendToChat,
+    updateDraft,
+    isCurrentTarget,
+    failureNotice,
+  ]);
 
   // ---- rename ----
   const [renaming, setRenaming] = useState(false);
@@ -924,18 +1033,26 @@ export function AgentChatPanel({
     }
   }, [chatState.chat, chatState.pendingSend, activeTab]);
 
+  // A limit notice expires with the budget window it described.
+  const currentNotice =
+    notice?.kind === 'limit' && notice.resetsAt && new Date(notice.resetsAt).getTime() <= Date.now()
+      ? null
+      : notice;
+
   // ---- derived composer state ----
   // Sending before the catalog lands would run the turn on the server default
   // and pin the conversation to it, silently losing the user's chosen model
   // with no way back. Busy rather than disabled: the draft stays editable, only
-  // send waits. A catalog that fails resolves to `unavailable`, which sends on
-  // the server default by design.
+  // send waits. A catalog failure offers a refresh before submitting.
   const composerBusy =
     chatState.isBusy ||
     chatState.isFinishing ||
     creatingChat ||
     queuedMessage != null ||
-    modelSelection.status === 'loading';
+    usage.busy ||
+    usageExhausted ||
+    modelSelection.status !== 'ok' ||
+    (!modelSelection.pinned && !modelSelection.model);
   // Stop is only offered once something cancellable exists server-side. While
   // the message POST is still in flight or the chat is being created, cancel
   // would no-op and the turn would start anyway.
@@ -1197,6 +1314,32 @@ export function AgentChatPanel({
         </div>
       )}
 
+      <UsageMeter
+        budget={usage.budget}
+        failed={usage.failed}
+        onRefresh={() => {
+          void usage.refresh();
+        }}
+      />
+      {modelSelection.status === 'unavailable' && (
+        <div className="flex items-center justify-between gap-2 px-3 py-1 text-xs text-gray-500">
+          <span>Couldn’t load available models.</span>
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={() => {
+              void modelSelection.refresh();
+            }}
+          >
+            Try again
+          </Button>
+        </div>
+      )}
+      {modelSelection.status === 'ok' && !modelSelection.model && (
+        <p className="px-3 py-1 text-xs text-gray-500">
+          No models are currently available for your account.
+        </p>
+      )}
       <ChatComposer
         textareaRef={composerRef}
         value={draft}
@@ -1206,7 +1349,12 @@ export function AgentChatPanel({
         busy={composerBusy}
         canStop={canStop}
         disabled={composerDisabled}
-        notice={notice}
+        notice={
+          (currentNotice?.kind === 'limit' || usageExhausted
+            ? { tone: 'warning', text: usageLimitMessage(usage.budget) }
+            : currentNotice) ??
+          (usage.busy && !chatState.isBusy ? { tone: 'warning', text: AI_BUSY_MESSAGE } : null)
+        }
         toolbar={
           <ModelControls
             models={modelSelection.models}
@@ -1215,7 +1363,12 @@ export function AgentChatPanel({
             options={modelSelection.options}
             onSelectModel={modelSelection.selectModel}
             onChangeOptions={modelSelection.setOptions}
-            disabled={composerDisabled}
+            disabled={
+              composerDisabled ||
+              chatState.pendingSend != null ||
+              creatingChat ||
+              queuedMessage != null
+            }
           />
         }
       />
diff --git a/components/Notebook/AgentChat/ChatComposer.tsx b/components/Notebook/AgentChat/ChatComposer.tsx
index c4bf4a799..1ace72557 100644
--- a/components/Notebook/AgentChat/ChatComposer.tsx
+++ b/components/Notebook/AgentChat/ChatComposer.tsx
@@ -7,6 +7,8 @@ import { MAX_CHAT_MESSAGE_LENGTH } from '@/types/notebookChat';
 
 export interface ComposerNotice {
   tone: 'warning' | 'error';
+  kind?: 'limit';
+  resetsAt?: string;
   text: string;
 }
 
diff --git a/components/Notebook/AgentChat/ChatTranscript.tsx b/components/Notebook/AgentChat/ChatTranscript.tsx
index 8c02df0e7..859d2229f 100644
--- a/components/Notebook/AgentChat/ChatTranscript.tsx
+++ b/components/Notebook/AgentChat/ChatTranscript.tsx
@@ -117,13 +117,13 @@ function buildTranscript(chat: NotebookChat, pendingSend: PendingSend | null): T
     }
   }
 
-  // Optimistic echo of a just-sent message until its execution shows up in a
+  // Echo only accepted (202) messages until their execution shows up in a
   // refetch (the hook retires it at that point).
   const pendingExecutionId = pendingSend?.executionId ?? null;
   const echoRetired =
     pendingExecutionId != null &&
     chat.executions.some((execution) => execution.id === pendingExecutionId);
-  if (pendingSend && !echoRetired) {
+  if (pendingSend && pendingExecutionId != null && !echoRetired) {
     build.entries.push({ key: 'pending-user', kind: 'pending-user', text: pendingSend.text });
   }
 
diff --git a/components/Notebook/AgentChat/ExecutionProgress.tsx b/components/Notebook/AgentChat/ExecutionProgress.tsx
index 7bb09fc48..3f15185de 100644
--- a/components/Notebook/AgentChat/ExecutionProgress.tsx
+++ b/components/Notebook/AgentChat/ExecutionProgress.tsx
@@ -101,7 +101,8 @@ export function ExecutionProgress({ execution }: ExecutionProgressProps) {
   // so the turn reads the same before and after it finishes.
   const expanded = userExpanded ?? true;
 
-  const failed = execution.status === 'FAILED' || execution.status === 'INTERRUPTED';
+  const limited = execution.error?.code === 'usage_limit_exceeded';
+  const failed = limited || execution.status === 'FAILED' || execution.status === 'INTERRUPTED';
   const cancelled = execution.status === 'CANCELLED';
 
   const summary = summarizeActivity(activity);
@@ -192,7 +193,11 @@ export function ExecutionProgress({ execution }: ExecutionProgressProps) {
           )}
         >
           <AlertCircle className="mt-0.5 h-3.5 w-3.5 shrink-0" aria-hidden="true" />
-          <span>{execution.error?.message ?? 'Something went wrong.'}</span>
+          <span>
+            {limited
+              ? 'Daily AI usage limit reached. This run has stopped. Check the usage meter for the reset time.'
+              : (execution.error?.message ?? 'Something went wrong.')}
+          </span>
         </div>
       )}
 
@@ -204,7 +209,7 @@ export function ExecutionProgress({ execution }: ExecutionProgressProps) {
           )}
         >
           <Ban className="h-3.5 w-3.5" aria-hidden="true" />
-          Stopped
+          Stopped. Another request may be unavailable briefly while cancellation finishes.
         </div>
       )}
     </div>
diff --git a/components/Notebook/AgentChat/ModelControls.tsx b/components/Notebook/AgentChat/ModelControls.tsx
index 8876efeb0..863db14b0 100644
--- a/components/Notebook/AgentChat/ModelControls.tsx
+++ b/components/Notebook/AgentChat/ModelControls.tsx
@@ -133,7 +133,7 @@ export function ModelControls({
         </ControlButton>
       )}
 
-      {openMenu === 'model' && (
+      {openMenu === 'model' && !disabled && !pinned && (
         <Menu label="Assistant model">
           <div className="max-h-64 overflow-y-auto p-1">
             {models.map((option) => (
@@ -154,7 +154,7 @@ export function ModelControls({
         </Menu>
       )}
 
-      {openMenu === 'effort' && (
+      {openMenu === 'effort' && !disabled && (
         <Menu label="Effort">
           <div className="space-y-3 px-3 py-3">
             {effortLevels.length > 0 && (
@@ -300,11 +300,13 @@ function ModelRow({
     <button
       type="button"
       onClick={onSelect}
+      disabled={!model.allowed}
       aria-current={selected}
       className={cn(
         'flex w-full items-start gap-2 rounded-lg px-2 py-2 text-left transition-colors',
         'hover:bg-gray-50 focus:outline-none focus-visible:bg-gray-50',
-        selected && 'bg-primary-50/60 hover:bg-primary-50/60'
+        selected && 'bg-primary-50/60 hover:bg-primary-50/60',
+        !model.allowed && 'cursor-not-allowed opacity-50'
       )}
     >
       <Check
@@ -316,6 +318,9 @@ function ModelRow({
       />
       <span className="min-w-0 flex-1">
         <span className="block truncate text-sm font-medium text-gray-800">{model.label}</span>
+        {!model.allowed && (
+          <span className="text-[11px] text-gray-500">Unavailable for your account</span>
+        )}
         {model.description && (
           <span className="mt-0.5 block text-[11px] leading-snug text-gray-500">
             {model.description}
diff --git a/components/Notebook/AgentChat/UsageMeter.tsx b/components/Notebook/AgentChat/UsageMeter.tsx
new file mode 100644
index 000000000..01a2695f5
--- /dev/null
+++ b/components/Notebook/AgentChat/UsageMeter.tsx
@@ -0,0 +1,75 @@
+'use client';
+
+import { Button } from '@/components/ui/Button';
+import { formatUsageReset, type ResearchAiUsageBudget } from '@/types/researchAiUsage';
+
+const dollars = (value: string) =>
+  new Intl.NumberFormat(undefined, {
+    style: 'currency',
+    currency: 'USD',
+    maximumFractionDigits: 4,
+  }).format(Number(value));
+
+export function UsageMeter({
+  budget,
+  failed,
+  onRefresh,
+}: {
+  readonly budget: ResearchAiUsageBudget | null;
+  readonly failed: boolean;
+  readonly onRefresh: () => void;
+}) {
+  const daily = budget?.daily_budget == null ? null : Number(budget.daily_budget);
+  const remaining = budget?.remaining == null ? null : Number(budget.remaining);
+  const percent =
+    daily != null && remaining != null && daily > 0
+      ? Math.max(0, Math.min(100, (remaining / daily) * 100))
+      : 0;
+  return (
+    <div className="border-t border-gray-100 px-3 py-2 text-[11px] text-gray-500">
+      {budget ? (
+        <>
+          <div className="flex flex-wrap justify-between gap-x-2 gap-y-1">
+            <span>
+              {budget.remaining == null
+                ? 'No daily spending limit'
+                : `${dollars(budget.remaining)} of ${dollars(budget.daily_budget ?? '0')} remaining`}
+            </span>
+            <span>
+              {budget.turn_cap == null
+                ? `${budget.turns_used} model calls today`
+                : `${budget.turns_used} / ${budget.turn_cap} model calls`}
+            </span>
+          </div>
+          {daily != null && (
+            <div
+              role="meter"
+              aria-label="Daily AI budget remaining"
+              aria-valuemin={0}
+              aria-valuemax={100}
+              aria-valuenow={percent}
+              aria-valuetext={`${dollars(budget.remaining ?? '0')} remaining`}
+              className="my-1.5 h-1 rounded-full bg-gray-100"
+            >
+              <div
+                className="h-full rounded-full bg-primary-500"
+                style={{ width: `${percent}%` }}
+              />
+            </div>
+          )}
+          <p>Resets {formatUsageReset(budget.resets_at)}</p>
+        </>
+      ) : (
+        !failed && <p>Loading AI usage…</p>
+      )}
+      {failed && (
+        <div className="flex items-center justify-between gap-2">
+          <span>{budget ? 'Usage may be out of date.' : 'Couldn’t load AI usage.'}</span>
+          <Button variant="ghost" size="sm" onClick={onRefresh}>
+            Refresh
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/components/Notebook/NoteEditorLayout.tsx b/components/Notebook/NoteEditorLayout.tsx
index fad9b7625..5cf8390ad 100644
--- a/components/Notebook/NoteEditorLayout.tsx
+++ b/components/Notebook/NoteEditorLayout.tsx
@@ -110,7 +110,7 @@ export function NoteEditorLayout({ onAgentChatDockedChange }: NoteEditorLayoutPr
     searchParams?.get('tab') === 'details' ? 'details' : 'document'
   );
 
-  // ---- AI assistant chat (gated to hub editors and moderators) ----
+  // ---- AI assistant chat (authenticated users with note access) ----
   const [isAgentChatOpen, setIsAgentChatOpen] = useState(false);
   // Flipped when the server denies access (the gate can change server-side);
   // hides the entry point while this note is open.
@@ -129,7 +129,7 @@ export function NoteEditorLayout({ onAgentChatDockedChange }: NoteEditorLayoutPr
   // hub doesn't permanently hide the assistant in hubs the user does edit.
   useEffect(() => {
     setAgentChatUnavailable(false);
-  }, [activeNoteId]);
+  }, [activeNoteId, user?.id]);
 
   const {
     width: agentChatWidth,
@@ -141,9 +141,8 @@ export function NoteEditorLayout({ onAgentChatDockedChange }: NoteEditorLayoutPr
   const isChangelog = isChangelogNote(note);
   const isChangelogAccessDenied = isChangelog && !user?.isModerator;
 
-  const isHubEditorOrModerator = Boolean(user?.moderator) || (user?.editorOfHubs?.length ?? 0) > 0;
   const showAgentChat =
-    isHubEditorOrModerator &&
+    Boolean(user) &&
     !agentChatUnavailable &&
     // Changelogs are moderator-only: the page renders Note Not Found in place
     // of the document, so the assistant must not mount over it.
@@ -409,6 +408,7 @@ export function NoteEditorLayout({ onAgentChatDockedChange }: NoteEditorLayoutPr
 
       {showAgentChat && activeNoteId && (
         <AgentChatPanel
+          key={`${user?.id}:${activeNoteId}`}
           noteId={activeNoteId}
           open={isAgentChatOpen}
           onClose={() => setIsAgentChatOpen(false)}
diff --git a/hooks/useAgentModelSelection.ts b/hooks/useAgentModelSelection.ts
index 46acf98c8..be020c218 100644
--- a/hooks/useAgentModelSelection.ts
+++ b/hooks/useAgentModelSelection.ts
@@ -1,6 +1,7 @@
 'use client';
 
 import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useUser } from '@/contexts/UserContext';
 import { useAgentModels, type AgentModelsStatus } from '@/hooks/useAgentModels';
 import {
   findModel,
@@ -25,9 +26,9 @@ interface StoredPreference extends GenerationOptions {
   ref?: string;
 }
 
-function readPreference(): StoredPreference {
+function readPreference(storageKey: string): StoredPreference {
   try {
-    const raw = window.localStorage.getItem(STORAGE_KEY);
+    const raw = window.localStorage.getItem(storageKey);
     if (!raw) return {};
     const parsed: unknown = JSON.parse(raw);
     return parsed != null && typeof parsed === 'object' ? (parsed as StoredPreference) : {};
@@ -44,10 +45,12 @@ export interface UseAgentModelSelectionOptions {
    * model for life, so this — when set — outranks the user's standing choice.
    */
   readonly pinnedRef: string | null;
+  readonly started?: boolean;
 }
 
 export interface AgentModelSelection {
   readonly status: AgentModelsStatus;
+  readonly refresh: () => Promise<void>;
   readonly models: AgentModel[];
   /** The model the next turn runs on, or null while there is no catalog. */
   readonly model: AgentModel | null;
@@ -74,26 +77,30 @@ export interface AgentModelSelection {
 export function useAgentModelSelection({
   enabled,
   pinnedRef,
+  started = false,
 }: UseAgentModelSelectionOptions): AgentModelSelection {
-  const { status, catalog } = useAgentModels(enabled);
+  const { status, catalog, refresh } = useAgentModels(enabled);
+  const { user } = useUser();
+  const storageKey = `${STORAGE_KEY}:${user?.id ?? 'anonymous'}`;
+  const pinned = started || pinnedRef != null;
   const [preference, setPreference] = useState<StoredPreference>({});
-  const [hydrated, setHydrated] = useState(false);
+  const [hydratedKey, setHydratedKey] = useState<string | null>(null);
 
   // Read after mount, never during initialization: localStorage is unavailable
   // on the server and a differing first client render would hydrate-mismatch.
   useEffect(() => {
-    setPreference(readPreference());
-    setHydrated(true);
-  }, []);
+    setPreference(readPreference(storageKey));
+    setHydratedKey(storageKey);
+  }, [storageKey]);
 
   useEffect(() => {
-    if (!hydrated) return;
+    if (hydratedKey !== storageKey) return;
     try {
-      window.localStorage.setItem(STORAGE_KEY, JSON.stringify(preference));
+      window.localStorage.setItem(storageKey, JSON.stringify(preference));
     } catch {
       // A blocked or full store just means the choice lasts this session.
     }
-  }, [hydrated, preference]);
+  }, [hydratedKey, storageKey, preference]);
 
   const models = catalog?.models ?? NO_MODELS;
 
@@ -102,22 +109,28 @@ export function useAgentModelSelection({
     // A pinned ref is named even when the catalog no longer carries it, so a
     // chat on a retired model still says what it is running.
     if (pinnedRef) return findModel(models, pinnedRef) ?? unknownModel(pinnedRef);
+    const allowedModels = models.filter((option) => option.allowed);
     return (
-      findModel(models, preference.ref ?? null) ??
-      findModel(models, catalog.default) ??
-      models[0] ??
+      findModel(allowedModels, hydratedKey === storageKey ? (preference.ref ?? null) : null) ??
+      findModel(allowedModels, catalog.default) ??
+      allowedModels[0] ??
       null
     );
-  }, [catalog, models, pinnedRef, preference.ref]);
+  }, [catalog, models, pinnedRef, preference.ref, hydratedKey, storageKey]);
 
   const options = useMemo(
-    () => (model ? normalizeGenerationOptions(model, preference) : {}),
-    [model, preference]
+    () =>
+      model && hydratedKey === storageKey ? normalizeGenerationOptions(model, preference) : {},
+    [model, preference, hydratedKey, storageKey]
   );
 
-  const selectModel = useCallback((ref: string) => {
-    setPreference((current) => ({ ...current, ref }));
-  }, []);
+  const selectModel = useCallback(
+    (ref: string) => {
+      if (pinned || !findModel(models, ref)?.allowed) return;
+      setPreference((current) => ({ ...current, ref }));
+    },
+    [models, pinned]
+  );
 
   const setOptions = useCallback((next: GenerationOptions) => {
     setPreference((current) => ({ ...current, ...next }));
@@ -127,14 +140,15 @@ export function useAgentModelSelection({
     if (model == null) return {};
     // Naming the pinned model again would be accepted, but only while nothing
     // raced us. Leaving it out lets the server answer from its own record.
-    return { ...(pinnedRef == null && { model: model.ref }), ...options };
-  }, [model, options, pinnedRef]);
+    return { ...(!pinned && model.allowed && { model: model.ref }), ...options };
+  }, [model, options, pinned]);
 
   return {
     status,
+    refresh,
     models,
     model,
-    pinned: pinnedRef != null,
+    pinned,
     options,
     selectModel,
     setOptions,
diff --git a/hooks/useAgentModels.ts b/hooks/useAgentModels.ts
index ed4d376bc..c40ba6a1c 100644
--- a/hooks/useAgentModels.ts
+++ b/hooks/useAgentModels.ts
@@ -1,64 +1,57 @@
 'use client';
 
-import { useEffect, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useUser } from '@/contexts/UserContext';
 import { AgentModelService } from '@/services/agentModel.service';
+import { chatErrorStatus } from '@/services/notebookChat.service';
 import type { AgentModelCatalog } from '@/types/notebookModels';
 
-/**
- * `loading` until the first fetch settles; `unavailable` for every failure —
- * the gate, a network blip, a backend without the endpoint. All of them mean
- * the same thing to the UI: no picker, and turns run on the server's default.
- */
-export type AgentModelsStatus = 'loading' | 'ok' | 'unavailable';
+export type AgentModelsStatus = 'loading' | 'ok' | 'unavailable' | 'unauthorized';
 
 export interface UseAgentModelsResult {
   readonly status: AgentModelsStatus;
   readonly catalog: AgentModelCatalog | null;
+  readonly refresh: () => Promise<void>;
 }
 
-// The catalog is per-deployment, not per-note or per-user-action: one fetch
-// serves every panel this session. Only successes are cached, so a transient
-// failure is retried by the next mount rather than disabling the picker for
-// the rest of the session.
-let cachedCatalog: AgentModelCatalog | null = null;
-let inFlight: Promise<AgentModelCatalog> | null = null;
-
-function loadCatalog(): Promise<AgentModelCatalog> {
-  if (cachedCatalog) return Promise.resolve(cachedCatalog);
-  inFlight ??= AgentModelService.listModels()
-    .then((catalog) => {
-      cachedCatalog = catalog;
-      return catalog;
-    })
-    .finally(() => {
-      inFlight = null;
-    });
-  return inFlight;
-}
-
-/** The models this user may select. Fetched once, when something needs it. */
+/** Eligibility is user-specific and can change. Revalidate on every panel open. */
 export function useAgentModels(enabled: boolean): UseAgentModelsResult {
-  const [result, setResult] = useState<UseAgentModelsResult>(() =>
-    cachedCatalog ? { status: 'ok', catalog: cachedCatalog } : { status: 'loading', catalog: null }
-  );
+  const { user } = useUser();
+  const userId = user?.id;
+  const sequence = useRef(0);
+  const [result, setResult] = useState<{
+    userId: typeof userId;
+    status: AgentModelsStatus;
+    catalog: AgentModelCatalog | null;
+  }>({ userId, status: 'loading', catalog: null });
+
+  const refresh = useCallback(async () => {
+    const seq = ++sequence.current;
+    setResult({ userId, status: 'loading', catalog: null });
+    if (userId == null) return;
+    try {
+      const catalog = await AgentModelService.listModels();
+      if (seq === sequence.current) setResult({ userId, status: 'ok', catalog });
+    } catch (error) {
+      if (seq !== sequence.current) return;
+      const status = chatErrorStatus(error);
+      setResult({
+        userId,
+        status: status === 401 || status === 403 ? 'unauthorized' : 'unavailable',
+        catalog: null,
+      });
+    }
+  }, [userId]);
 
   useEffect(() => {
-    if (!enabled || result.catalog != null) return;
-    let cancelled = false;
-    loadCatalog().then(
-      (catalog) => {
-        if (!cancelled) setResult({ status: 'ok', catalog });
-      },
-      () => {
-        // Deliberately terminal for this mount: the deps can't change back, so
-        // a failing endpoint is asked once, not once per render.
-        if (!cancelled) setResult({ status: 'unavailable', catalog: null });
-      }
-    );
+    if (enabled) void refresh();
     return () => {
-      cancelled = true;
+      sequence.current += 1;
     };
-  }, [enabled, result.catalog]);
+  }, [enabled, refresh]);
 
-  return result;
+  return {
+    ...(result.userId === userId ? result : { status: 'loading' as const, catalog: null }),
+    refresh,
+  };
 }
diff --git a/hooks/useNotebookChat.ts b/hooks/useNotebookChat.ts
index e6fd132f4..96dfcc19f 100644
--- a/hooks/useNotebookChat.ts
+++ b/hooks/useNotebookChat.ts
@@ -1,10 +1,13 @@
 'use client';
 
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useUser } from '@/contexts/UserContext';
+import { researchAiJobs } from '@/store/researchAiJobs';
 import { debounce, type DebouncedFunc } from 'lodash-es';
 import {
   NotebookChatService,
   chatErrorDetail,
+  chatErrorCode,
   chatErrorStatus,
 } from '@/services/notebookChat.service';
 import { useNotebookChatSocket, type ChatSocketStatus } from '@/hooks/useNotebookChatSocket';
@@ -44,18 +47,32 @@ export type SendOutcome =
   | { ok: true }
   | {
       ok: false;
-      reason: 'busy' | 'invalid' | 'not_found' | 'unauthorized' | 'error';
+      reason:
+        | 'busy'
+        | 'limit'
+        | 'model_not_allowed'
+        | 'invalid'
+        | 'not_found'
+        | 'unauthorized'
+        | 'error';
       detail?: string;
     };
 
 /** Maps a failed send POST to its outcome; the state side-effects stay in `send`. */
 function sendFailureOutcome(err: unknown): Extract<SendOutcome, { ok: false }> {
   const detail = chatErrorDetail(err);
+  const code = chatErrorCode(err);
   switch (chatErrorStatus(err)) {
     case 409:
       return { ok: false, reason: 'busy', detail };
+    case 429:
+      return { ok: false, reason: code === 'usage_limit_exceeded' ? 'limit' : 'error', detail };
     case 400:
-      return { ok: false, reason: 'invalid', detail };
+      return {
+        ok: false,
+        reason: code === 'model_not_allowed' ? 'model_not_allowed' : 'invalid',
+        detail,
+      };
     case 401:
     case 403:
       return { ok: false, reason: 'unauthorized', detail };
@@ -281,6 +298,8 @@ export function useNotebookChat({
   enabled,
   initialChat = null,
 }: UseNotebookChatOptions): UseNotebookChatResult {
+  const { user } = useUser();
+  const userId = String(user?.id ?? '');
   const [chat, setChat] = useState<NotebookChat | null>(null);
   const [access, setAccess] = useState<ChatAccess>('loading');
   const [pendingSend, setPendingSend] = useState<PendingSend | null>(null);
@@ -298,6 +317,13 @@ export function useNotebookChat({
   // (panel reopen, switch-back) must fetch, or the transcript would silently
   // revert to the empty creation state with no poll/socket path to recover.
   const seededChatIdRef = useRef<number | null>(null);
+  useEffect(
+    () => () => {
+      seqRef.current += 1;
+      epochRef.current += 1;
+    },
+    []
+  );
   // Mirror of `chat` for non-reactive reads inside fetchChat.
   const chatRef = useRef<NotebookChat | null>(null);
   // A sequence gap can produce more gap frames while its recovery GET runs.
@@ -316,6 +342,7 @@ export function useNotebookChat({
       try {
         const data = await NotebookChatService.getChat(noteId, chatId, { live });
         if (seq !== seqRef.current) return;
+        researchAiJobs.observe(userId, noteId, data);
         setChat((prev) => {
           const merged = mergeLiveChat(live ? prev : null, data);
           chatRef.current = merged;
@@ -337,7 +364,7 @@ export function useNotebookChat({
         }
       }
     },
-    [noteId, chatId]
+    [noteId, chatId, userId]
   );
 
   // Reset + initial load whenever the target chat changes or the panel opens.
@@ -482,10 +509,12 @@ export function useNotebookChat({
   const send = useCallback(
     async (text: string, generation?: GenerationRequest): Promise<SendOutcome> => {
       if (noteId == null || chatId == null) return { ok: false, reason: 'error' };
+      if (!researchAiJobs.reserve(userId)) return { ok: false, reason: 'busy' };
       const epoch = epochRef.current;
       setPendingSend({ text, executionId: null });
       try {
         const response = await NotebookChatService.sendMessage(noteId, chatId, text, generation);
+        researchAiJobs.track(userId, { noteId, chatId, executionId: response.execution_id });
         if (epoch === epochRef.current) {
           setPendingSend({ text, executionId: response.execution_id });
           fetchChat('live');
@@ -509,9 +538,11 @@ export function useNotebookChat({
           }
         }
         return outcome;
+      } finally {
+        researchAiJobs.release(userId);
       }
     },
-    [noteId, chatId, fetchChat]
+    [noteId, chatId, fetchChat, userId]
   );
 
   const cancel = useCallback(async () => {
@@ -581,6 +612,8 @@ export function useNotebookChatList(
   noteId: string | number | null,
   enabled: boolean
 ): UseNotebookChatListResult {
+  const { user } = useUser();
+  const userId = String(user?.id ?? '');
   const [chats, setChats] = useState<NotebookChatListItem[]>([]);
   const [access, setAccess] = useState<ChatListAccess>('loading');
   const seqRef = useRef(0);
@@ -594,6 +627,10 @@ export function useNotebookChatList(
     try {
       const items = await NotebookChatService.listChats(noteId);
       if (seq !== seqRef.current) return;
+      for (const item of items) {
+        if (item.has_active_turn)
+          researchAiJobs.track(userId, { noteId, chatId: item.id, executionId: null });
+      }
       setChats(items);
       setAccess('ok');
     } catch (err) {
@@ -605,7 +642,7 @@ export function useNotebookChatList(
         setAccess((prev) => (prev === 'ok' ? 'ok' : 'error'));
       }
     }
-  }, [noteId]);
+  }, [noteId, userId]);
 
   useEffect(() => {
     seqRef.current += 1;
diff --git a/hooks/useNotebookChatSocket.ts b/hooks/useNotebookChatSocket.ts
index fa2f12f6d..490182f47 100644
--- a/hooks/useNotebookChatSocket.ts
+++ b/hooks/useNotebookChatSocket.ts
@@ -7,7 +7,7 @@ import { useReconnectingSocket, type SocketStatus } from './useReconnectingSocke
 
 /**
  * Server-defined close codes that mean reconnecting is pointless for this
- * chat: unauthenticated (4401), not editor/moderator (4403), chat/note not
+ * chat: unauthenticated (4401), access denied (4403), chat/note not
  * found or not yours (4404). REST polling remains the fallback, and the REST
  * layer surfaces the matching access error to the UI.
  */
diff --git a/hooks/useResearchAiUsage.ts b/hooks/useResearchAiUsage.ts
new file mode 100644
index 000000000..651ad36be
--- /dev/null
+++ b/hooks/useResearchAiUsage.ts
@@ -0,0 +1,107 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { useUser } from '@/contexts/UserContext';
+import { ApiClient } from '@/services/client';
+import { NotebookChatService, chatErrorStatus } from '@/services/notebookChat.service';
+import { researchAiJobs } from '@/store/researchAiJobs';
+import type { ResearchAiUsageBudget } from '@/types/researchAiUsage';
+
+/** Account-wide usage and known executions survive chat/note switches. */
+export function useResearchAiUsage(enabled: boolean) {
+  const { user } = useUser();
+  const userId = String(user?.id ?? '');
+  const snapshot = useSyncExternalStore(
+    researchAiJobs.subscribe,
+    () => researchAiJobs.getSnapshot(userId),
+    researchAiJobs.getServerSnapshot
+  );
+  const [state, setState] = useState<{
+    userId: string;
+    budget: ResearchAiUsageBudget | null;
+    failed: boolean;
+  }>({ userId, budget: null, failed: false });
+  const sequence = useRef(0);
+  const refresh = useCallback(async (): Promise<ResearchAiUsageBudget | null> => {
+    if (!userId) return null;
+    const seq = ++sequence.current;
+    try {
+      const budget = await ApiClient.get<ResearchAiUsageBudget>('/api/research_ai/usage-budget/');
+      if (seq !== sequence.current) return null;
+      setState({ userId, budget, failed: false });
+      return budget;
+    } catch {
+      if (seq === sequence.current) {
+        setState((current) => ({
+          userId,
+          budget: current.userId === userId ? current.budget : null,
+          failed: true,
+        }));
+      }
+      return null;
+    }
+  }, [userId]);
+
+  useEffect(() => {
+    if (enabled) void refresh();
+    return () => {
+      sequence.current += 1;
+    };
+  }, [enabled, refresh, snapshot.completed]);
+
+  const budget = state.userId === userId ? state.budget : null;
+  // Refresh when today's window expires, including after a background-tab sleep.
+  useEffect(() => {
+    if (!enabled) return;
+    const onFocus = () => {
+      void refresh();
+    };
+    window.addEventListener('focus', onFocus);
+    const delay = budget ? new Date(budget.resets_at).getTime() - Date.now() : NaN;
+    const timer =
+      Number.isFinite(delay) && delay > 0
+        ? setTimeout(onFocus, Math.min(delay + 1000, 2_147_483_647))
+        : undefined;
+    return () => {
+      window.removeEventListener('focus', onFocus);
+      clearTimeout(timer);
+    };
+  }, [enabled, budget?.resets_at, refresh]);
+
+  useEffect(() => {
+    if (!enabled || snapshot.jobs.length === 0) return;
+    let cancelled = false;
+    let inFlight = false;
+    const poll = async () => {
+      if (inFlight) return;
+      inFlight = true;
+      await Promise.all(
+        snapshot.jobs.map(async (job) => {
+          try {
+            const chat = await NotebookChatService.getChat(job.noteId, job.chatId, { live: true });
+            if (!cancelled) researchAiJobs.observe(userId, job.noteId, chat);
+          } catch (error) {
+            // Lost note access must not leave a permanent local lock.
+            if (!cancelled && [401, 403, 404].includes(chatErrorStatus(error) ?? 0)) {
+              researchAiJobs.forget(userId, job.chatId);
+            }
+          }
+        })
+      );
+      inFlight = false;
+    };
+    void poll();
+    const timer = setInterval(poll, 5000);
+    return () => {
+      cancelled = true;
+      clearInterval(timer);
+    };
+  }, [enabled, userId, snapshot.jobs]);
+
+  return {
+    budget,
+    failed: state.userId === userId && state.failed,
+    busy: snapshot.submitting || snapshot.jobs.length > 0,
+    refresh,
+  };
+}
diff --git a/services/agentModel.service.ts b/services/agentModel.service.ts
index d8ef1e798..de7ee6827 100644
--- a/services/agentModel.service.ts
+++ b/services/agentModel.service.ts
@@ -9,9 +9,8 @@ import {
  * The user-selectable model catalog, shared by every agent workflow that
  * takes a model (the notebook assistant today, proposal drafting next).
  *
- * Gated exactly like those workflows, so a 401/403 here means the same thing
- * as one on the chat itself: this user has no assistant, and the picker
- * simply isn't there.
+ * Eligibility and generation capabilities are specific to the authenticated
+ * user. Callers revalidate on opening and after a model_not_allowed response.
  */
 export class AgentModelService {
   static async listModels(): Promise<AgentModelCatalog> {
diff --git a/services/notebookChat.service.ts b/services/notebookChat.service.ts
index 36bf24a64..7212e86af 100644
--- a/services/notebookChat.service.ts
+++ b/services/notebookChat.service.ts
@@ -46,7 +46,8 @@ export class NotebookChatService {
   /**
    * Starts an asynchronous turn. 202 means the user message is already recorded
    * server-side. Throws ApiError with status 409 while a previous turn is still
-   * running (one turn per chat), 400 for empty/oversized messages.
+   * running (including another Research AI workflow), 429 for usage limits,
+   * and 400 for invalid messages or disallowed models/settings.
    *
    * `generation` carries the model and its controls; every field is optional
    * and an omitted one runs the server's configured default. `model` is only
@@ -99,3 +100,10 @@ export function chatErrorDetail(error: unknown): string | undefined {
   }
   return error instanceof Error ? error.message : undefined;
 }
+
+/** Structured admission error code; status alone cannot identify model/usage errors. */
+export function chatErrorCode(error: unknown): string | undefined {
+  if (!(error instanceof ApiError)) return undefined;
+  const code = (error.errors as Record<string, unknown> | undefined)?.code;
+  return typeof code === 'string' ? code : undefined;
+}
diff --git a/store/researchAiJobs.ts b/store/researchAiJobs.ts
new file mode 100644
index 000000000..f33250f4c
--- /dev/null
+++ b/store/researchAiJobs.ts
@@ -0,0 +1,79 @@
+import { isActiveExecutionStatus, type NotebookChat } from '@/types/notebookChat';
+
+interface KnownJob {
+  noteId: string | number;
+  chatId: number;
+  executionId: number | null;
+}
+interface JobSnapshot {
+  jobs: readonly KnownJob[];
+  submitting: boolean;
+  completed: number;
+}
+const EMPTY: JobSnapshot = { jobs: [], submitting: false, completed: 0 };
+const accounts = new Map<string, JobSnapshot>();
+const listeners = new Set<() => void>();
+
+function publish(userId: string, snapshot: JobSnapshot): void {
+  accounts.set(userId, snapshot);
+  listeners.forEach((listener) => listener());
+}
+
+/** Only jobs observed in this session are known; server 409s remain authoritative. */
+export const researchAiJobs = {
+  subscribe(listener: () => void) {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  },
+  getSnapshot(userId: string): JobSnapshot {
+    return accounts.get(userId) ?? EMPTY;
+  },
+  getServerSnapshot(): JobSnapshot {
+    return EMPTY;
+  },
+  reserve(userId: string): boolean {
+    const current = this.getSnapshot(userId);
+    if (current.submitting || current.jobs.length > 0) return false;
+    publish(userId, { ...current, submitting: true });
+    return true;
+  },
+  release(userId: string): void {
+    publish(userId, { ...this.getSnapshot(userId), submitting: false });
+  },
+  track(userId: string, job: KnownJob): void {
+    const current = this.getSnapshot(userId);
+    const existing = current.jobs.find((item) => item.chatId === job.chatId);
+    if (existing && (job.executionId == null || existing.executionId === job.executionId)) return;
+    publish(userId, {
+      ...current,
+      jobs: [...current.jobs.filter((item) => item.chatId !== job.chatId), job],
+    });
+  },
+  observe(userId: string, noteId: string | number, chat: NotebookChat): void {
+    const active = chat.executions.find((execution) => isActiveExecutionStatus(execution.status));
+    if (active) {
+      this.track(userId, { noteId, chatId: chat.conversation_id, executionId: active.id });
+      return;
+    }
+    const current = this.getSnapshot(userId);
+    const known = current.jobs.find((item) => item.chatId === chat.conversation_id);
+    // A GET that raced a 202 may not contain the accepted execution yet.
+    if (
+      !known ||
+      (known.executionId != null && !chat.executions.some((item) => item.id === known.executionId))
+    )
+      return;
+    this.forget(userId, chat.conversation_id);
+  },
+  forget(userId: string, chatId: number): void {
+    const current = this.getSnapshot(userId);
+    if (!current.jobs.some((job) => job.chatId === chatId)) return;
+    publish(userId, {
+      ...current,
+      jobs: current.jobs.filter((job) => job.chatId !== chatId),
+      completed: current.completed + 1,
+    });
+  },
+};
diff --git a/types/notebookChat.ts b/types/notebookChat.ts
index 87ec89fde..a272bfe8a 100644
--- a/types/notebookChat.ts
+++ b/types/notebookChat.ts
@@ -126,6 +126,7 @@ export interface ExecutionPhase {
 
 export interface ChatExecutionError {
   code: string;
+  retryable?: boolean;
   /** User-safe copy — render verbatim, never invent detail. */
   message: string;
 }
diff --git a/types/notebookModels.ts b/types/notebookModels.ts
index f4656be06..0d4babbe9 100644
--- a/types/notebookModels.ts
+++ b/types/notebookModels.ts
@@ -57,6 +57,7 @@ export interface AgentModel {
   readonly label: string;
   readonly description: string;
   readonly provider: string;
+  readonly allowed: boolean;
   readonly capabilities: AgentModelCapabilities;
 }
 
@@ -89,12 +90,13 @@ export interface GenerationRequest extends GenerationOptions {
 
 /** Raw catalog response — `capabilities` arrives as open-ended strings. */
 export interface AgentModelCatalogResponse {
-  default?: string;
+  default?: string | null;
   models?: Array<{
     ref?: string;
     label?: string;
     description?: string;
     provider?: string;
+    allowed?: boolean;
     capabilities?: {
       effort?: string[];
       thinking?: string[];
@@ -137,6 +139,7 @@ export function toAgentModelCatalog(response: AgentModelCatalogResponse): AgentM
       label: model.label?.trim() || modelIdOf(model.ref),
       description: model.description ?? '',
       provider: model.provider || providerOf(model.ref),
+      allowed: model.allowed === true,
       capabilities: {
         effort: (model.capabilities?.effort ?? []).filter(isEffortLevel),
         thinking: (model.capabilities?.thinking ?? []).filter(isThinkingMode),
@@ -163,6 +166,7 @@ export function unknownModel(ref: string): AgentModel {
     label: modelIdOf(ref) || ref,
     description: '',
     provider: providerOf(ref),
+    allowed: false,
     capabilities: { effort: [], thinking: [], temperature: false },
   };
 }
diff --git a/types/researchAiUsage.ts b/types/researchAiUsage.ts
new file mode 100644
index 000000000..56913c79b
--- /dev/null
+++ b/types/researchAiUsage.ts
@@ -0,0 +1,39 @@
+/** Dollar values stay in their wire format; null means unlimited. */
+export interface ResearchAiUsageBudget {
+  tier: string;
+  daily_budget: string | null;
+  spent_today: string;
+  remaining: string | null;
+  turns_used: number;
+  turn_cap: number | null;
+  resets_at: string;
+}
+
+export const AI_BUSY_MESSAGE = 'Another AI request is still running. Try again when it finishes.';
+
+export function formatUsageReset(resetsAt: string): string {
+  const date = new Date(resetsAt);
+  if (!Number.isFinite(date.getTime())) return 'the next daily reset';
+  return new Intl.DateTimeFormat(undefined, {
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+    timeZoneName: 'short',
+  }).format(date);
+}
+
+export function usageLimitMessage(budget: ResearchAiUsageBudget | null): string {
+  return budget
+    ? `Daily AI usage limit reached. Access resets ${formatUsageReset(budget.resets_at)}.`
+    : 'Daily AI usage limit reached. Check the usage meter for the reset time.';
+}
+
+/** An expired snapshot must not keep the composer locked after the reset. */
+export function isUsageExhausted(budget: ResearchAiUsageBudget | null, now = Date.now()): boolean {
+  if (!budget || new Date(budget.resets_at).getTime() <= now) return false;
+  return (
+    (budget.remaining != null && Number(budget.remaining) <= 0) ||
+    (budget.turn_cap != null && budget.turns_used >= budget.turn_cap)
+  );
+}