@plannotator/ui 0.49.0 → 0.51.0

package/components/html-viewer/useHtmlAnnotation.ts

@@ -477,8 +477,8 @@ export function useHtmlAnnotation({
   flashDraftTarget: (key: string) => void;
   /** Bumped after every target add/remove so the composer can refocus its textarea. */
   composerFocusToken: number;
-  /** Composer one-click "Looks good": submits the hardcoded positive label
-   *  with the same anchor and multi-select targets a typed comment would carry. */
+  /** Composer one-click 👍: submits the hardcoded positive label with the
+   *  same anchor and multi-select targets a typed comment would carry. */
   handleCommentLooksGood: () => void;
   /** Ids this module minted for locally created annotations (create-mark),
    *  for the unanchored union: a minted id the host never listed is a
@@ -910,8 +910,14 @@ export function useHtmlAnnotation({
     [getOrCreateAnchor],
   );
 
-  const handleCommentSubmit = useCallback(
-    (comment: string, images?: ImageAttachment[], mentions?: readonly string[]) => {
+  // One commit path for everything the pinpoint composer submits (a typed
+  // comment or the one-click 👍), so both carry the same anchor, element
+  // context and multi-select targets.
+  const commitComposerDraft = useCallback(
+    (
+      body: Pick<Annotation, "text"> &
+        Partial<Pick<Annotation, "images" | "mentions" | "isQuickLabel" | "quickLabelTip">>,
+    ) => {
       if (!enabledRef.current) return;
       // Prefer the text captured when the popover opened — it can't be clobbered by
       // a later selection change or clear while the user is composing the comment.
@@ -939,14 +945,10 @@ export function useHtmlAnnotation({
         startOffset: 0,
         endOffset: 0,
         type: AnnotationType.COMMENT,
-        text: comment,
         originalText: text,
         author: getIdentity(),
         createdA: Date.now(),
-        images,
-        // Host capability: present only when a mentionSource was supplied AND
-        // a token survived, so a comment without one is unchanged.
-        ...(mentions && mentions.length > 0 ? { mentions } : {}),
+        ...body,
         htmlAnchor: pendingAnchorRef.current ?? undefined,
         elementContext: pendingContextRef.current ?? undefined,
         htmlAdditionalTargets: additionalTargets,
@@ -961,53 +963,32 @@ export function useHtmlAnnotation({
     [post],
   );
 
-  // The composer's one-click "Looks good" (the restored thumbs-up for
-  // comment-only surfaces, where pinpoint clicks land straight in the
-  // composer and never see the selection toolbar). Mirrors
-  // handleCommentSubmit — same anchor, same multi-select targets — but
-  // emits the hardcoded positive label instead of typed prose.
-  const handleCommentLooksGood = useCallback(() => {
-    if (!enabledRef.current) return;
-    const text = commentPopoverRef.current?.selectedText || pendingTextRef.current;
-    if (!text) return;
-
-    const targets = draftTargetsRef.current;
-    const additionalTargets: HtmlAnnotationTarget[] | undefined =
-      targets.length > 1
-        ? targets.slice(1, 1 + maxTargetsRef.current).map((t) => ({
-            label: t.label,
-            text: t.text,
-            anchor: t.anchor ?? undefined,
-            ...(t.context ? { context: t.context } : {}),
-          }))
-        : undefined;
-
-    const id = nextHtmlAnnId();
-    mintedIdsRef.current.add(id);
-    post({ type: `${PREFIX}create-mark`, id, annotationType: "comment" });
-    onAddRef.current?.({
-      id,
-      blockId: "",
-      startOffset: 0,
-      endOffset: 0,
-      type: AnnotationType.COMMENT,
-      text: THUMBS_UP_LABEL.text,
-      originalText: text,
-      isQuickLabel: true,
-      quickLabelTip: THUMBS_UP_LABEL.tip,
-      author: getIdentity(),
-      createdA: Date.now(),
-      htmlAnchor: pendingAnchorRef.current ?? undefined,
-      elementContext: pendingContextRef.current ?? undefined,
-      htmlAdditionalTargets: additionalTargets,
-    });
+  const handleCommentSubmit = useCallback(
+    (comment: string, images?: ImageAttachment[], mentions?: readonly string[]) =>
+      commitComposerDraft({
+        text: comment,
+        images,
+        // Host capability: present only when a mentionSource was supplied AND
+        // a token survived, so a comment without one is unchanged.
+        ...(mentions && mentions.length > 0 ? { mentions } : {}),
+      }),
+    [commitComposerDraft],
+  );
 
-    setCommentPopover(null);
-    setDraftTargets([]);
-    pendingTextRef.current = "";
-    pendingAnchorRef.current = null;
-    pendingContextRef.current = null;
-  }, [post]);
+  // The composer's one-click 👍. A pinpoint click opens this composer
+  // directly and never shows the selection toolbar, so without it a reviewer
+  // could not mark an element "looks good" in one click. Emits the same
+  // hardcoded positive label as the toolbar's 👍 (the only label comment-only
+  // surfaces may create), on the pinned element(s).
+  const handleCommentLooksGood = useCallback(
+    () =>
+      commitComposerDraft({
+        text: THUMBS_UP_LABEL.text,
+        isQuickLabel: true,
+        quickLabelTip: THUMBS_UP_LABEL.tip,
+      }),
+    [commitComposerDraft],
+  );
 
   const handleCommentClose = useCallback(() => {
     post({ type: `${PREFIX}cancel-selection` });

package/configure.ts

@@ -12,6 +12,7 @@ import { setWebMcpPolicy, type WebMcpPolicy } from './webmcp/policy';
 import { setMathRendererLoader, type MathRenderer, type MathRendererLoader } from './utils/math';
 import { setIdentityGenerator, type IdentityGenerator } from './utils/generateIdentity';
 import { setAlertIconRenderer, type AlertIconRenderer } from './components/blocks/AlertBlock';
+import { setFenceThemeResolver, type FenceThemeResolver } from './utils/syntaxTheme';
 import { configStore } from './config';
 import type { ServerSyncFn } from './config/configStore';
 import type { ExternalAnnotationEvent, VaultNode } from './types';
@@ -40,6 +41,7 @@ export type {
   MathRendererLoader,
   IdentityGenerator,
   AlertIconRenderer,
+  FenceThemeResolver,
 };
 
 type ExternalAnnotationBase = { id: string; source?: string };
@@ -93,6 +95,15 @@ export interface PlannotatorUIConfig {
    * today; the package bundles no icon set. A host with one registers a renderer.
    */
   alertIconRenderer?: AlertIconRenderer;
+  /**
+   * Pick the Shiki theme code fences render in, per (palette id, resolved
+   * mode). Return `undefined` to keep the default resolution (the palette's
+   * `SHIKI_THEME_MAP` entry, else `pierre-dark` / `pierre-light`). Applies to
+   * every fence-style surface (Viewer fences, the code-file hover preview, the
+   * plan diff view, code review suggestion snippets); the code-review diff
+   * pane keeps its own pair. An unknown theme name renders plain text.
+   */
+  fenceTheme?: FenceThemeResolver;
   /** Re-hydrate settings from the installed (SYNCHRONOUS) storageBackend after install. */
   loadSettingsFromBackend?: boolean;
 }
@@ -114,6 +125,7 @@ export function configurePlannotatorUI(config: PlannotatorUIConfig): void {
   if (config.mathRendererLoader) setMathRendererLoader(config.mathRendererLoader);
   if (config.identityGenerator) setIdentityGenerator(config.identityGenerator);
   if (config.alertIconRenderer) setAlertIconRenderer(config.alertIconRenderer);
+  if (config.fenceTheme) setFenceThemeResolver(config.fenceTheme);
   // Re-hydrate AFTER storageBackend is installed (load-bearing order — gated last).
   if (config.loadSettingsFromBackend) configStore.loadFromBackend();
 }

package/hooks/useAIChat.ts

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import type { AIContext } from '@plannotator/core';
 import type { AIQuestion, AIResponse } from '../types';
 import { generateId } from '../utils/generateId';
+import { SESSION_ASK_ERROR_CODES } from '../utils/aiProvider';
 
 export interface AIChatEntry {
   question: AIQuestion;
@@ -42,6 +43,18 @@ export interface AskAIParams {
   /** Context block prepended to the message (e.g. the "changes under review"
    *  description). Rides with each question so it reflects the live view. */
   contextPreamble?: string;
+  /** "Ask this session" only: what to do when the host session is busy
+   *  ("wait" = ask when it finishes, "interrupt" = stop its turn and ask now). */
+  busyPolicy?: 'wait' | 'interrupt';
+}
+
+/** Overrides for re-asking a question that ended in a busy/gone/blocked answer. */
+export interface AIRetryOptions {
+  busyPolicy?: 'wait' | 'interrupt';
+  /** Ask a different provider instead (a fresh session is created for it). */
+  providerId?: string;
+  /** Replace parts of the original question (e.g. a provider-specific preamble). */
+  params?: Partial<AskAIParams>;
 }
 
 interface UseAIChatOptions {
@@ -79,7 +92,8 @@ export function buildDefaultPrompt(params: AskAIParams): string {
       const label = params.scope.label ? `Re: ${params.scope.label}` : 'Re: selected text';
       const source = params.scope.sourcePath ? `\nSource: ${params.scope.sourcePath}` : '';
       const selection = params.scope.text ? `\n\nSelected text:\n\`\`\`\n${params.scope.text}\n\`\`\`` : '';
-      return `${label}${source}${selection}\n\n${params.prompt}`;
+      const detail = params.scope.detail?.trim() ? `\n\nSelected element:\n${params.scope.detail.trim()}` : '';
+      return `${label}${source}${selection}${detail}\n\n${params.prompt}`;
     }
 
     // General question (no explicit file/line/selection): tell the agent what the
@@ -228,7 +242,7 @@ export function useAIChat({
     setThread(prev => ({ ...prev, sessionId }));
   }, []);
 
-  const createSession = useCallback(async (signal: AbortSignal, epoch: number): Promise<string> => {
+  const createSession = useCallback(async (signal: AbortSignal, epoch: number, providerOverride?: string): Promise<string> => {
     if (!context) {
       throw new Error('AI context is unavailable');
     }
@@ -236,7 +250,10 @@ export function useAIChat({
     const requestId = ++createRequestRef.current;
     setIsCreatingSession(true);
     try {
-      const res = await aiTransport.session({
+      const res = await aiTransport.session(providerOverride ? {
+        context,
+        providerId: providerOverride,
+      } : {
         context,
         ...(providerId && { providerId }),
         ...(model && { model }),
@@ -274,7 +291,11 @@ export function useAIChat({
     return safeAbort(sessionId);
   }, []);
 
-  const ask = useCallback(async (params: AskAIParams) => {
+  // The params each question was asked with, so a busy answer can be
+  // re-asked ("Ask when it finishes", "Interrupt and ask now").
+  const paramsByQuestionRef = useRef(new Map<string, AskAIParams>());
+
+  const ask = useCallback(async (params: AskAIParams, askOptions?: { providerId?: string }) => {
     if (abortRef.current) {
       abortRef.current.abort();
       // Supersede: stop the server-side turn (not just the browser fetch).
@@ -295,6 +316,7 @@ export function useAIChat({
     setError(null);
 
     const questionId = generateId('ai-question');
+    paramsByQuestionRef.current.set(questionId, params);
     const question: AIQuestion = {
       id: questionId,
       prompt: params.prompt,
@@ -319,7 +341,9 @@ export function useAIChat({
 
     try {
       let sid = sessionIdRef.current;
-      if (!sid) {
+      if (askOptions?.providerId) {
+        sid = await createSession(controller.signal, epoch, askOptions.providerId);
+      } else if (!sid) {
         sid = await createSession(controller.signal, epoch);
       }
 
@@ -332,6 +356,7 @@ export function useAIChat({
         sessionId: sid,
         prompt: fullPrompt,
         ...(params.contextUpdate && { contextUpdate: params.contextUpdate }),
+        ...(params.busyPolicy && { busyPolicy: params.busyPolicy }),
       }, controller.signal);
 
       if (!res.ok || !res.body) {
@@ -363,7 +388,19 @@ export function useAIChat({
               updateMessages(prev =>
                 prev.map(m =>
                   m.question.id === questionId
-                    ? { ...m, response: { ...m.response, text: m.response.text + msg.delta } }
+                    ? { ...m, response: m.response.status
+                        ? { ...m.response, text: m.response.text + msg.delta, status: undefined }
+                        : { ...m.response, text: m.response.text + msg.delta } }
+                    : m
+                )
+              );
+            } else if (msg.type === 'status') {
+              // "Ask this session": waiting on / interrupting a busy session.
+              const status = msg.status === 'waiting' || msg.status === 'interrupting' ? msg.status : undefined;
+              updateMessages(prev =>
+                prev.map(m =>
+                  m.question.id === questionId
+                    ? { ...m, response: { ...m.response, status } }
                     : m
                 )
               );
@@ -385,11 +422,39 @@ export function useAIChat({
                 description: msg.description,
                 toolUseId: msg.toolUseId,
               }]);
+            } else if (msg.type === 'error' && msg.code === SESSION_ASK_ERROR_CODES.takenOver) {
+              // "Ask this session": the person typed into the session while it
+              // answered. The answer so far stands; the reason is a note under
+              // it, not an error that would replace it.
+              updateMessages(prev =>
+                prev.map(m =>
+                  m.question.id === questionId
+                    ? {
+                        ...m,
+                        response: {
+                          ...m.response,
+                          notice: typeof msg.error === 'string' ? msg.error : undefined,
+                          ...(m.response.status && { status: undefined }),
+                          isStreaming: false,
+                        },
+                      }
+                    : m
+                )
+              );
             } else if (msg.type === 'error') {
               updateMessages(prev =>
                 prev.map(m =>
                   m.question.id === questionId
-                    ? { ...m, response: { ...m.response, error: msg.error, isStreaming: false } }
+                    ? {
+                        ...m,
+                        response: {
+                          ...m.response,
+                          error: msg.error,
+                          ...(typeof msg.code === 'string' && { errorCode: msg.code }),
+                          ...(m.response.status && { status: undefined }),
+                          isStreaming: false,
+                        },
+                      }
                     : m
                 )
               );
@@ -418,8 +483,8 @@ export function useAIChat({
 
       updateMessages(prev =>
         prev.map(m =>
-          m.question.id === questionId && m.response.isStreaming
-            ? { ...m, response: { ...m.response, isStreaming: false } }
+          m.question.id === questionId && (m.response.isStreaming || m.response.status)
+            ? { ...m, response: { ...m.response, isStreaming: false, ...(m.response.status && { status: undefined }) } }
             : m
         )
       );
@@ -428,7 +493,7 @@ export function useAIChat({
         updateMessages(prev =>
           prev.map(m =>
             m.question.id === questionId
-              ? { ...m, response: { ...m.response, isStreaming: false } }
+              ? { ...m, response: { ...m.response, isStreaming: false, ...(m.response.status && { status: undefined }) } }
               : m
           )
         );
@@ -452,6 +517,25 @@ export function useAIChat({
     }
   }, [buildPrompt, createSession, updateMessages, updatePermissions, postServerAbort]);
 
+  /**
+   * Re-ask an earlier question in place of its answer: the busy-session choice
+   * ("Ask when it finishes" / "Interrupt and ask now"). `providerId` re-asks
+   * on another provider for hosts that offer one.
+   */
+  const retry = useCallback((questionId: string, options: AIRetryOptions = {}) => {
+    const original = paramsByQuestionRef.current.get(questionId);
+    if (!original) return;
+    paramsByQuestionRef.current.delete(questionId);
+    updateMessages(prev => prev.filter(m => m.question.id !== questionId));
+    const { busyPolicy: _previousPolicy, ...base } = original;
+    const params: AskAIParams = {
+      ...base,
+      ...options.params,
+      ...(options.busyPolicy && { busyPolicy: options.busyPolicy }),
+    };
+    return ask(params, options.providerId ? { providerId: options.providerId } : undefined);
+  }, [ask, updateMessages]);
+
   const abort = useCallback(() => {
     if (abortRef.current) {
       abortRef.current.abort();
@@ -502,6 +586,7 @@ export function useAIChat({
       abortRef.current = null;
       pendingAbortRef.current = postServerAbort();
     }
+    paramsByQuestionRef.current.clear();
     setThread(createThread(threadTitle));
     setIsCreatingSession(false);
     setIsStreaming(false);
@@ -527,6 +612,7 @@ export function useAIChat({
     permissionRequests: thread.permissionRequests,
     respondToPermission,
     ask,
+    retry,
     abort,
     resetSession,
     resetThread,

package/hooks/useAIProviderActivation.ts

@@ -23,13 +23,26 @@ export interface ActivatedAIProvider extends AIProviderOption {
 
 export function useAIProviderActivation(options: {
   onCapabilities: (providers: ActivatedAIProvider[], defaultProvider: string | null) => void;
+  /**
+   * The Ask AI providers the server currently lists. When given, an id not in
+   * it is never activated: at page load the selection can still hold a saved
+   * provider id (e.g. `codex-sdk`) for one render before the resolver moves it
+   * to what the server offers, and activating that id would start its model
+   * discovery even though Ask AI does not offer it (a session-bridge server
+   * lists only the bridge). Omitted keeps the old behavior.
+   */
+  providers?: ReadonlyArray<Pick<AIProviderOption, 'id'>>;
 }) {
   const activatedRef = useRef<Set<string>>(new Set());
   const onCapabilitiesRef = useRef(options.onCapabilities);
   onCapabilitiesRef.current = options.onCapabilities;
+  const providersRef = useRef(options.providers);
+  providersRef.current = options.providers;
 
   return useCallback((providerId: string | null | undefined) => {
     if (!providerId || activatedRef.current.has(providerId)) return;
+    const listed = providersRef.current;
+    if (listed && !listed.some(provider => provider.id === providerId)) return;
     activatedRef.current.add(providerId);
     fetch(`/api/ai/capabilities?activate=${encodeURIComponent(providerId)}`)
       .then(res => (res.ok ? res.json() : null))

package/hooks/useAIProviderConfig.ts

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import type { Origin } from '@plannotator/core/agents';
 import {
   getAIProviderSettings,
@@ -56,16 +56,26 @@ export function useAIProviderConfig({
     };
   });
 
+  // A provider picked for this page only (`applyConfigChange(..., { persist:
+  // false })`): never written to the cookie, but kept across capability
+  // refreshes so the resolver does not flip back.
+  const sessionPickRef = useRef<string | null>(null);
+
   // Auto-resolve provider/model once capabilities are known.
   useEffect(() => {
     if (!available || providers.length === 0) return;
     const saved = getAIProviderSettings();
-    const selection = resolveAIProviderSelection({
-      providers,
-      origin,
-      settings: saved,
-      serverDefaultProvider: defaultProvider,
-    });
+    const sessionPick = sessionPickRef.current
+      ? providers.find(p => p.id === sessionPickRef.current) ?? null
+      : null;
+    const selection = sessionPick
+      ? { providerId: sessionPick.id, model: resolveAIModelForProvider(sessionPick, saved.preferredModels) }
+      : resolveAIProviderSelection({
+          providers,
+          origin,
+          settings: saved,
+          serverDefaultProvider: defaultProvider,
+        });
 
     setAiConfig(prev => {
       if (prev.providerId === selection.providerId && prev.model === selection.model) return prev;
@@ -81,7 +91,13 @@ export function useAIProviderConfig({
   // Update the selection (provider/model/effort). Does NOT reset the session —
   // the caller composes that (see the cycle note above).
   const applyConfigChange = useCallback(
-    (config: { providerId?: string | null; model?: string | null; reasoningEffort?: string | null }) => {
+    (
+      config: { providerId?: string | null; model?: string | null; reasoningEffort?: string | null },
+      options?: { persist?: boolean },
+    ) => {
+      const persist = options?.persist !== false;
+      if (!persist && config.providerId) sessionPickRef.current = config.providerId;
+      else if (persist && config.providerId !== undefined) sessionPickRef.current = null;
       setAiConfig(prev => {
         const saved = getAIProviderSettings();
         const providerId = config.providerId !== undefined ? config.providerId : prev.providerId;
@@ -104,12 +120,14 @@ export function useAIProviderConfig({
         // (e.g. the static fallback a lazily-discovered provider advertises
         // before activation) must never overwrite the user's saved preference
         // — the session request may fall back, the cookie may not.
-        saveAIProviderSelection({
-          providerId: next.providerId,
-          model: config.model !== undefined ? next.model : null,
-          origin,
-          settings: saved,
-        });
+        if (persist) {
+          saveAIProviderSelection({
+            providerId: next.providerId,
+            model: config.model !== undefined ? next.model : null,
+            origin,
+            settings: saved,
+          });
+        }
         return next;
       });
     },

package/hooks/useActiveSection.ts

@@ -21,8 +21,9 @@ export function useActiveSection(
     const viewport = scrollElement ?? contentContainer;
     if (!contentContainer || !viewport) return;
     
-    // Find all heading elements with data-block-id
-    const headings = contentContainer.querySelectorAll('[data-block-type="heading"]');
+    // Only document headings: a heading inside a question card's context has
+    // no block id and is not a TOC section.
+    const headings = contentContainer.querySelectorAll('[data-block-type="heading"][data-block-id]');
     if (headings.length === 0) return;
     
     // Track which headings are currently intersecting

package/hooks/useAgentToolSetting.ts

@@ -0,0 +1,33 @@
+import { useCallback, useState } from 'react';
+import {
+  parseAgentToolSetting,
+  saveAgentToolSetting,
+  withSavedAgentTool,
+  type AgentToolSetting,
+} from '../utils/agentToolSetting';
+
+export interface AgentToolSettingState {
+  /** Undefined until a serverConfig reporting a tool host is adopted. */
+  readonly setting: AgentToolSetting | undefined;
+  /** Takes the agent tool fields from a `/api/plan` or `/api/diff` serverConfig. */
+  readonly adopt: (serverConfig: unknown) => void;
+  /** Writes the switch; resolves once config.json holds it, rejects with a readable Error. */
+  readonly save: (enabled: boolean) => Promise<void>;
+}
+
+/**
+ * The agent tool switch for an App: the Settings row and the one-time offer
+ * read the same state, so turning the tool on from the offer shows in
+ * Settings at once, and vice versa.
+ */
+export function useAgentToolSetting(): AgentToolSettingState {
+  const [setting, setSetting] = useState<AgentToolSetting | undefined>(undefined);
+  const adopt = useCallback((serverConfig: unknown) => {
+    setSetting(parseAgentToolSetting(serverConfig));
+  }, []);
+  const save = useCallback(async (enabled: boolean) => {
+    await saveAgentToolSetting(enabled);
+    setSetting((current) => (current ? withSavedAgentTool(current, enabled) : current));
+  }, []);
+  return { setting, adopt, save };
+}

package/hooks/useAnnotationDraft.ts

@@ -41,17 +41,30 @@ const DEBOUNCE_MS = 500;
  *  - `load` returns the raw stored body (or null) plus the generation the
  *    store reports when there is NO draft (the default reads `draftGeneration`
  *    from the 404 body) so the client can resume past a tombstone.
+ *  - `save` MAY resolve `{ staleGeneration }` when the store refused the body
+ *    as stale (the default reads it from a `409 { draftGeneration }` that is
+ *    not marked `decided: true`, which
+ *    annotate servers answer when the file's path copy was deleted or moved
+ *    ahead by another session). The hook then raises its counter above that
+ *    generation and saves again, once. Resolving nothing keeps the old
+ *    behavior, so a host transport that never refuses needs no change.
  */
 export interface DraftTransport {
   /** GET the draft. `data` is the raw stored body (null if none). `generation`
       is the store's reported generation when there is no draft (null otherwise). */
   load(): Promise<{ data: unknown | null; generation: number | null }>;
-  /** Persist the draft body. `keepalive` requests best-effort delivery on close. */
-  save(body: object, opts: { keepalive: boolean }): Promise<void>;
+  /** Persist the draft body. `keepalive` requests best-effort delivery on close.
+      Resolves `{ staleGeneration }` when the store refused the body as stale. */
+  save(body: object, opts: { keepalive: boolean }): Promise<void | DraftSaveRefused>;
   /** Generation-gated tombstone delete. */
   remove(generation: number, opts: { keepalive: boolean }): Promise<void>;
 }
 
+/** A save the store refused as stale: the highest generation it knows. */
+export interface DraftSaveRefused {
+  staleGeneration: number;
+}
+
 /**
  * Default transport — Plannotator's `/api/draft` fetches, moved verbatim.
  * `save` rejects on failure (the keepalive retry stays in the hook so its
@@ -73,7 +86,15 @@ const defaultDraftTransport: DraftTransport = {
     const payload = JSON.stringify(body);
     const headers = { 'Content-Type': 'application/json' };
     return fetch('/api/draft', { method: 'POST', headers, body: payload, keepalive }).then(
-      () => {},
+      async (res): Promise<void | DraftSaveRefused> => {
+        if (res.status !== 409) return;
+        const data = (await res.json().catch(() => null)) as (MissingDraftData & { decided?: boolean }) | null;
+        // The review was decided: saving again would put back comments that
+        // were just sent, so a decided refusal is never retried.
+        if (data?.decided === true) return;
+        const staleGeneration = readDraftGeneration(data?.draftGeneration);
+        return staleGeneration !== null ? { staleGeneration } : undefined;
+      },
     );
   },
   remove(generation, { keepalive }) {
@@ -281,6 +302,10 @@ interface UseAnnotationDraftResult {
   scheduleDraftSaveAfterSubmitFailure: () => void;
   getDraftGeneration: () => number;
   dismissDraft: () => void;
+  /** Send a pending (debounced) save now, if there is one. For a session
+      that ends WITHOUT a decision body (the agent closed it): the comment
+      typed just before must still reach the kept draft. */
+  flushPendingSave: () => void;
 }
 
 export function useAnnotationDraft({
@@ -393,7 +418,7 @@ export function useAnnotationDraft({
       });
   }, [isApiMode, isSharedSession]);
 
-  const persistNow = useCallback((keepalive: boolean) => {
+  const persistNow = useCallback((keepalive: boolean, retried = false) => {
     // Re-check: the session may have been submitted while the debounce was
     // pending — a save landing after submit would resurrect a draft the
     // server just deleted, ghosting it into the next session for this plan.
@@ -429,15 +454,29 @@ export function useAnnotationDraft({
     // The transport moves the POST behind the seam; the keepalive retry-on-failure
     // gate stays in the hook verbatim so a host transport that resolves/rejects on
     // failure still won't resurrect a superseded save.
-    getDraftTransport().save(payload, { keepalive }).catch(() => {
+    // A refused (stale) save means the store moved past this tab's counter:
+    // another session on the same file decided or saved ahead of it. Adopt
+    // the store's generation and save again, so the reviewer's comments are
+    // not silently left unsaved. Only while this is still the latest save,
+    // and only once per save.
+    const retryIfRefused = (result: void | DraftSaveRefused) => {
+      if (!result || retried) return;
+      if (!canPersistRef.current || draftGenerationRef.current !== draftGeneration) return;
+      draftGenerationRef.current = Math.max(draftGenerationRef.current, result.staleGeneration);
+      persistNowRef.current(false, true);
+    };
+
+    getDraftTransport().save(payload, { keepalive }).then(retryIfRefused, () => {
       // Chromium caps keepalive bodies (~64KB); retry without it. Completes
       // fine when the page was only backgrounded, best-effort on close.
       if (keepalive && canPersistRef.current && draftGenerationRef.current === draftGeneration) {
-        getDraftTransport().save(payload, { keepalive: false }).catch(() => {});
+        getDraftTransport().save(payload, { keepalive: false }).then(retryIfRefused, () => {});
       }
       // Otherwise silent failure — draft is best-effort.
     });
   }, []);
+  const persistNowRef = useRef(persistNow);
+  persistNowRef.current = persistNow;
 
   const scheduleDraftSave = useCallback(() => {
     if (!canPersistRef.current || !hasMountedRef.current) return;
@@ -457,6 +496,13 @@ export function useAnnotationDraft({
 
   const getDraftGeneration = useCallback(() => draftGenerationRef.current + 1, []);
 
+  const flushPendingSave = useCallback(() => {
+    if (timerRef.current === null) return;
+    clearTimeout(timerRef.current);
+    timerRef.current = null;
+    persistNow(false);
+  }, [persistNow]);
+
   // Flush a pending save when the page is backgrounded or closed — otherwise
   // the last debounce window of typing is lost on tab close, and reopening
   // the (still-running) session would restore a draft missing those
@@ -519,5 +565,5 @@ export function useAnnotationDraft({
     getDraftTransport().remove(deletedGeneration, { keepalive: false }).catch(() => {});
   }, []);
 
-  return { draftBanner, restoreDraft, scheduleDraftSave, scheduleDraftSaveAfterSubmitFailure, getDraftGeneration, dismissDraft };
+  return { draftBanner, restoreDraft, scheduleDraftSave, scheduleDraftSaveAfterSubmitFailure, getDraftGeneration, dismissDraft, flushPendingSave };
 }