@plannotator/ui 0.47.0 → 0.50.0

package/components/QuestionsPanelSection.tsx

@@ -0,0 +1,121 @@
+import React from 'react';
+import { cn } from '../lib/utils';
+import { questionProgress, type QuestionPanelRow } from '../utils/questionAnswers';
+
+/**
+ * The annotations panel's Questions section (the approved Card mock): a
+ * header with the progress count, a thin progress bar, and one row per
+ * `:::question` block with its answer or "Not answered yet" and an
+ * Open / answered state. A row whose question is no longer in the document
+ * carries the Unanchored chip; its answer still exports.
+ */
+const CheckIcon = () => (
+  <svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" strokeWidth="2.2" aria-hidden="true" className="text-success">
+    <path d="m3.5 8.5 3 3 6-7" strokeLinecap="round" strokeLinejoin="round" />
+  </svg>
+);
+
+const StateTag: React.FC<{ row: QuestionPanelRow }> = ({ row }) => {
+  if (row.orphaned) {
+    return (
+      <span
+        data-annotation-unanchored="true"
+        className="whitespace-nowrap rounded px-1.5 py-0.5 text-[9px] font-medium bg-muted text-muted-foreground"
+        title="This question is no longer in the document. The answer is still sent."
+      >
+        Unanchored
+      </span>
+    );
+  }
+  if (row.status === 'answered' || row.status === 'settled') {
+    return (
+      <span className="inline-flex" title={row.status === 'settled' ? 'Settled' : 'Answered'}>
+        <CheckIcon />
+        <span className="sr-only">{row.status === 'settled' ? 'Settled' : 'Answered'}</span>
+      </span>
+    );
+  }
+  if (row.status === 'skipped') {
+    return <span className="whitespace-nowrap rounded bg-muted px-1.5 py-px text-[10px] font-semibold text-muted-foreground">Skipped</span>;
+  }
+  return (
+    <span className="whitespace-nowrap rounded border border-dashed border-border px-1.5 py-px text-[10px] font-semibold text-muted-foreground">
+      Open
+    </span>
+  );
+};
+
+export interface QuestionsPanelSectionProps {
+  rows: readonly QuestionPanelRow[];
+  onSelect?: (row: QuestionPanelRow) => void;
+  /** Remove an orphaned answer (its card is gone, so the panel is the only
+   *  place to drop it). Absent: no remove control. */
+  onRemoveOrphan?: (row: QuestionPanelRow) => void;
+}
+
+export const QuestionsPanelSection: React.FC<QuestionsPanelSectionProps> = ({ rows, onSelect, onRemoveOrphan }) => {
+  const { done, total } = questionProgress(rows);
+  const complete = total > 0 && done === total;
+  return (
+    <section data-questions-panel="true" aria-label="Questions" className="mb-2">
+      <div className="mx-0.5 mb-2 mt-1 flex items-center gap-2 text-[11px] font-semibold uppercase tracking-[0.07em] text-muted-foreground">
+        <span className="flex-1">Questions</span>
+        {total > 0 && <span className="tabular-nums">{done}/{total}</span>}
+      </div>
+      {total > 0 && (
+        <div className="mx-0.5 mb-2.5 h-1 overflow-hidden rounded-sm bg-muted" aria-hidden="true">
+          <i
+            className={cn('block h-full rounded-sm', complete ? 'bg-success' : 'bg-primary')}
+            style={{ width: `${(done / total) * 100}%` }}
+          />
+        </div>
+      )}
+      <div className="flex flex-col">
+        {rows.map((row) => {
+          const ok = !row.orphaned && (row.status === 'answered' || row.status === 'settled');
+          const summary = row.answerText ?? 'Not answered yet';
+          const clickable = !!onSelect && !row.orphaned;
+          const body = (
+            <>
+              <span className={cn('font-mono text-[10.5px] font-semibold leading-[1.6]', ok ? 'text-success' : 'text-muted-foreground')}>
+                {row.number ? `Q${row.number}` : 'Q'}
+              </span>
+              <span className="min-w-0 text-[12.5px] leading-[1.4] text-foreground">{row.prompt}</span>
+              <StateTag row={row} />
+              <span className={cn('col-start-2 col-end-4 text-xs', row.answerText && row.status !== 'skipped' ? 'text-foreground' : 'text-muted-foreground')}>
+                {summary}
+                {row.hasNote ? ' · has note' : ''}
+              </span>
+            </>
+          );
+          const rowClass = 'grid w-full grid-cols-[auto_1fr_auto] items-start gap-x-2 gap-y-0.5 rounded-[7px] px-2 py-2 text-left';
+          return clickable ? (
+            <button
+              key={row.key}
+              type="button"
+              data-question-row={row.key}
+              data-question-row-status={row.status}
+              onClick={() => onSelect!(row)}
+              className={cn(rowClass, 'cursor-pointer transition-colors hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring')}
+            >
+              {body}
+            </button>
+          ) : (
+            <div key={row.key} data-question-row={row.key} data-question-row-status={row.status} className={rowClass}>
+              {body}
+              {row.orphaned && onRemoveOrphan && (
+                <button
+                  type="button"
+                  onClick={() => onRemoveOrphan(row)}
+                  className="col-start-2 col-end-4 justify-self-start text-[11px] text-muted-foreground underline-offset-2 hover:text-destructive hover:underline"
+                >
+                  Remove answer
+                </button>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </section>
+  );
+};

package/components/Settings.tsx

@@ -102,6 +102,10 @@ interface SettingsProps {
   aiProviders?: Array<{ id: string; name: string; capabilities: Record<string, boolean>; models?: Array<{ id: string; label: string; default?: boolean }> }>;
   /** Git user name from `git config user.name`, for quick identity set */
   gitUser?: string;
+  /** Present when the server advertises the auto-update setting (#1634);
+   *  `env` is PLANNOTATOR_AUTO_UPDATE when it overrides the config file.
+   *  Hosts that omit it get no toggle. */
+  autoUpdateSetting?: { env?: boolean };
   /** Current session is a local git review where since-base ISN'T offered
    *  (base ref unresolvable) — the Git tab shows a note that the Git-status
    *  preference can't take effect in THIS repo. */
@@ -937,8 +941,9 @@ const CommentsTab: React.FC = () => {
   );
 };
 
-export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange, onIdentityChange, origin, mode = 'plan', annotateParity = false, onUIPreferencesChange, externalOpen, onExternalClose, aiProviders = [], gitUser, sinceBaseUnavailable, isCompactTouchLayout = false, onDetectObsidianVaults, agentTerminalAvailable = false, webmcpAvailable = false }) => {
+export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange, onIdentityChange, origin, mode = 'plan', annotateParity = false, onUIPreferencesChange, externalOpen, onExternalClose, aiProviders = [], gitUser, autoUpdateSetting, sinceBaseUnavailable, isCompactTouchLayout = false, onDetectObsidianVaults, agentTerminalAvailable = false, webmcpAvailable = false }) => {
   const webmcpTools = useWebMcpToolsEnabled();
+  const autoUpdate = useConfigValue('autoUpdate');
   const [showDialog, setShowDialog] = useState(false);
   const settingsWasOpenRef = useRef(false);
   const [themePreview, setThemePreview] = useState(false);
@@ -1379,6 +1384,25 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
                       </div>
                     </div>
 
+                    {/* Auto-update (#1634): opt-in, default off. Writes
+                        autoUpdate to ~/.plannotator/config.json. */}
+                    {autoUpdateSetting && (
+                      <>
+                        <div className="border-t border-border" />
+                        <ToggleSwitch
+                          checked={autoUpdateSetting.env ?? autoUpdate}
+                          onChange={(v) => configStore.set('autoUpdate', v)}
+                          disabled={autoUpdateSetting.env !== undefined}
+                          label="Keep Plannotator up to date"
+                          description={
+                            autoUpdateSetting.env !== undefined
+                              ? 'Set by PLANNOTATOR_AUTO_UPDATE in your environment.'
+                              : 'Installs new releases in the background, at most once a day, never while another review is open.'
+                          }
+                        />
+                      </>
+                    )}
+
                     {/* Agent tools (WebMCP). Shown only when the browser
                         exposes document.modelContext; off unregisters the
                         tools for this browser. Cookie-only and idle at its

package/components/Viewer.tsx

@@ -1,6 +1,7 @@
 import { generateId } from '../utils/generateId';
-import React, { useRef, useState, useEffect, useMemo, forwardRef, useImperativeHandle, useCallback, lazy, Suspense } from 'react';
+import React, { useRef, useState, useEffect, useLayoutEffect, useMemo, forwardRef, useImperativeHandle, useCallback, lazy, Suspense } from 'react';
 import { createPortal } from 'react-dom';
+import { ImageLightbox } from './ImageLightbox';
 import { AnnotationType, type Block, type Annotation, type EditorMode, type InputMethod, type ImageAttachment, type ActionsLabelMode } from '../types';
 import { applyHighlight, codeBlockClassName, onCodeHighlightSwap } from '../utils/codeHighlight';
 import { paintCodeBlockMark } from '../utils/codeBlockMark';
@@ -9,6 +10,8 @@ import { computeListIndices, groupBlocks, type Frontmatter, type FrontmatterValu
 import { buildHeadingSlugMap } from '../utils/slugify';
 import { copyTextToClipboard } from '../utils/clipboard';
 import { BlockRenderer } from './BlockRenderer';
+import { indexQuestionBlocks, type IndexedQuestion, type ParsedQuestion, type QuestionAnswer } from '@plannotator/core/question-block';
+import { resolveQuestionAnswers } from '../utils/questionAnswers';
 import { CodeBlock } from './blocks/CodeBlock';
 import { TableBlock } from './blocks/TableBlock';
 import { TableToolbar } from './blocks/TableToolbar';
@@ -187,6 +190,34 @@ export interface ViewerProps {
   // Checkbox toggle props
   onToggleCheckbox?: (blockId: string, checked: boolean) => void;
   checkboxOverrides?: Map<string, boolean>;
+  /** Answer handler for `:::question` blocks. The Viewer draws each answer
+   *  from the `annotations` row carrying `questionAnswer` for that question's
+   *  key; a change calls this with the next answer, or null when it became
+   *  empty, and the host upserts or removes that annotation (see
+   *  `upsertQuestionAnswerAnnotation` in `utils/questionAnswers`). Absent (or
+   *  `readOnly`), question blocks render read-only. */
+  onAnswerQuestion?: (blockId: string, answer: QuestionAnswer | null, key: string) => void;
+  /** Host-kept answers, keyed by the question's (de-duplicated) key from
+   *  `indexQuestionBlocks` / `findQuestionBlocks`. When given, the cards read
+   *  their answers from here and never from `annotations`; entries that fail
+   *  `parseQuestionAnswer` are ignored. Absent: answers come from the
+   *  annotations carrying `questionAnswer` (Plannotator's own path). */
+  questionAnswers?: ReadonlyMap<string, QuestionAnswer> | Readonly<Record<string, QuestionAnswer>>;
+  /** Explicit save mode for question cards: edits stay a draft in the card,
+   *  which shows Save answer and Cancel (and no Skip); Save calls this with
+   *  the question's key and the answer, or null when the draft is empty. Return
+   *  a promise to keep the draft until it settles (a rejection keeps it for a
+   *  retry). Takes precedence over `onAnswerQuestion`. Ignored when
+   *  `readOnly`. */
+  onSaveQuestionAnswer?: (key: string, answer: QuestionAnswer | null) => void | Promise<unknown>;
+  /** Label of the explicit-save-mode Save button, or a function of the
+   *  question returning it. Default "Save answer"; never derived from
+   *  `decisionOnAnswer` (only the host knows whether saving records one). */
+  saveQuestionAnswerLabel?: string | ((question: ParsedQuestion) => string);
+  /** Host actions at the right of a question card's footer (e.g. "Mark as
+   *  decision"), given the indexed question and its saved answer. Rendered in
+   *  read-only cards too; return null for none. */
+  renderQuestionFooter?: (question: IndexedQuestion, answer: QuestionAnswer | undefined) => React.ReactNode;
   onAskAI?: CommentAskAIHandler;
   /** Whether comment popovers offer image attachments. Hosts without an
    *  uploadTransport pass false so the attach affordance never dead-ends.
@@ -310,6 +341,87 @@ const FrontmatterCard: React.FC<{ frontmatter: Frontmatter }> = ({ frontmatter }
   );
 };
 
+/** Viewport offset (px) the legacy action cluster pins to while stuck (`top-3`). */
+const STICKY_ACTIONS_TOP_PX = 12;
+
+interface StickyActionsBox {
+  readonly width: number;
+  readonly height: number;
+  readonly marginTop: number;
+  readonly marginRight: number;
+}
+
+/**
+ * Legacy top-right action cluster, pinned while the document scrolls.
+ *
+ * The cluster must not be a sticky float: when float-avoiding siblings (the
+ * `overflow-x-auto` table and code wrappers) reflow, Firefox lays them out
+ * around the float's *stuck* position, so annotating a long table while
+ * scrolled squeezed it to a sliver. A static float spacer reserves the title's
+ * wrap space instead, and the cluster sticks inside a zero-height lane. Both
+ * copy the cluster's measured box and margins, so host CSS that restyles
+ * `[data-sticky-actions]` keeps its effect.
+ */
+const StickyActionsLane: React.FC<{ className: string; children: React.ReactNode }> = ({ className, children }) => {
+  const actionsRef = useRef<HTMLDivElement>(null);
+  const [box, setBox] = useState<StickyActionsBox | null>(null);
+
+  useLayoutEffect(() => {
+    const el = actionsRef.current;
+    if (!el) return;
+    const measure = () => {
+      const style = window.getComputedStyle(el);
+      const next: StickyActionsBox = {
+        width: el.offsetWidth,
+        height: el.offsetHeight,
+        marginTop: Number.parseFloat(style.marginTop) || 0,
+        marginRight: Number.parseFloat(style.marginRight) || 0,
+      };
+      setBox((prev) =>
+        prev
+        && prev.width === next.width
+        && prev.height === next.height
+        && prev.marginTop === next.marginTop
+        && prev.marginRight === next.marginRight
+          ? prev
+          : next);
+    };
+    measure();
+    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(measure);
+    observer?.observe(el);
+    // Breakpoint-only margin changes (lg/xl) don't resize the cluster.
+    window.addEventListener('resize', measure);
+    return () => {
+      observer?.disconnect();
+      window.removeEventListener('resize', measure);
+    };
+  }, []);
+
+  return (
+    <>
+      <div
+        data-print-hide
+        data-sticky-actions-lane
+        className="sticky z-30 flex h-0 items-start justify-end"
+        // The lane carries no margin, so offset it by the cluster's own top
+        // margin to pin the cluster's border box exactly where the float did.
+        style={{ top: STICKY_ACTIONS_TOP_PX - (box?.marginTop ?? 0) }}
+      >
+        <div ref={actionsRef} data-print-hide data-sticky-actions className={className}>
+          {children}
+        </div>
+      </div>
+      {/* After the lane: the lane is a flex box, so a float placed before it would narrow it. */}
+      <div
+        data-print-hide
+        aria-hidden="true"
+        className="float-right"
+        style={box ? { width: box.width, height: box.height, marginTop: box.marginTop, marginRight: box.marginRight } : undefined}
+      />
+    </>
+  );
+};
+
 interface ViewerDocumentHeaderProps {
   readonly config: ViewerAnnotationHeaderConfig;
   readonly inputMethod: InputMethod;
@@ -473,6 +585,11 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   messagePickerInfo,
   onToggleCheckbox,
   checkboxOverrides,
+  onAnswerQuestion,
+  questionAnswers: hostQuestionAnswers,
+  onSaveQuestionAnswer,
+  saveQuestionAnswerLabel,
+  renderQuestionFooter,
   onAskAI,
   allowImages = true,
   readOnly = false,
@@ -535,6 +652,19 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   // anchor ids stay stable across re-renders and duplicate heading texts get
   // `-1`/`-2`/... suffixes rather than colliding on the same id.
   const headingSlugMap = useMemo(() => buildHeadingSlugMap(blocks), [blocks]);
+  // `:::question` blocks: numbered in document order, answers drawn from the
+  // annotations that carry `questionAnswer` (matched by question key, so an
+  // answer follows its question across re-parses).
+  const questionIndex = useMemo(() => {
+    const list = indexQuestionBlocks(blocks);
+    return { byBlock: new Map(list.map((q) => [q.blockId, q])), total: list.length };
+  }, [blocks]);
+  // A host that keeps answers itself (`questionAnswers`) replaces the
+  // annotation-derived map; each entry is validated like any other reader.
+  const answersByKey = useMemo(
+    () => resolveQuestionAnswers(annotations, hostQuestionAnswers),
+    [annotations, hostQuestionAnswers],
+  );
   const isTouchDevice = useMemo(() => window.matchMedia('(pointer: coarse)').matches, []);
   const [codeBlockToolbar, setCodeBlockToolbar] =
     useState<CodeBlockToolbarTarget | null>(null);
@@ -911,8 +1041,11 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
       ? container.querySelector<HTMLElement>('[data-viewer-document-header]')
         ?? container.querySelector<HTMLElement>('[data-sticky-actions]')
       : null;
+    // The legacy cluster sticks via its lane, so its own `top` is `auto`.
     const stickyTop = documentHeader
-      ? Number.parseFloat(window.getComputedStyle(documentHeader).top || '0') || 0
+      ? documentHeader.hasAttribute('data-viewer-document-header')
+        ? Number.parseFloat(window.getComputedStyle(documentHeader).top || '0') || 0
+        : STICKY_ACTIONS_TOP_PX
       : 0;
     const headerOffset = documentHeader
       ? documentHeader.getBoundingClientRect().height + stickyTop
@@ -1252,9 +1385,15 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
           <>
             {badgeClearance > 0 && <div data-print-hide style={{ height: badgeClearance }} aria-hidden="true" />}
             {stickyActions && <div ref={stickySentinelRef} className="h-0 w-0 float-right" aria-hidden="true" />}
-            <div data-print-hide data-sticky-actions className={`${stickyActions ? 'sticky top-3' : ''} z-30 float-right flex items-start gap-1 md:gap-2 rounded-lg p-1 md:p-2 transition-colors duration-150 ${isStuck ? 'bg-card/95 backdrop-blur-sm shadow-sm' : ''} ${gridEnabled ? '-mr-3 md:-mr-5 lg:-mr-7 xl:-mr-9' : '-mr-1 md:-mr-2'} mt-6 md:-mt-5 lg:-mt-7 xl:-mt-9`}>
-              {documentActions}
-            </div>
+            {stickyActions ? (
+              <StickyActionsLane className={`flex items-start gap-1 md:gap-2 rounded-lg p-1 md:p-2 transition-colors duration-150 ${isStuck ? 'bg-card/95 backdrop-blur-sm shadow-sm' : ''} ${gridEnabled ? '-mr-3 md:-mr-5 lg:-mr-7 xl:-mr-9' : '-mr-1 md:-mr-2'} mt-6 md:-mt-5 lg:-mt-7 xl:-mt-9`}>
+                {documentActions}
+              </StickyActionsLane>
+            ) : (
+              <div data-print-hide data-sticky-actions className={`z-30 float-right flex items-start gap-1 md:gap-2 rounded-lg p-1 md:p-2 transition-colors duration-150 ${gridEnabled ? '-mr-3 md:-mr-5 lg:-mr-7 xl:-mr-9' : '-mr-1 md:-mr-2'} mt-6 md:-mt-5 lg:-mt-7 xl:-mt-9`}>
+                {documentActions}
+              </div>
+            )}
           </>
         )}
         {frontmatter && <><div className="clear-right md:hidden" /><FrontmatterCard frontmatter={frontmatter} /></>}
@@ -1385,7 +1524,32 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
               }
             />
           ) : (
-            <BlockRenderer imageBaseDir={imageBaseDir} onImageClick={(src, alt) => setLightbox({ src, alt })} key={group.block.id} block={group.block} onOpenLinkedDoc={onOpenLinkedDoc} onOpenCodeFile={onOpenCodeFile} onNavigateAnchor={scrollToAnchor} onToggleCheckbox={readOnly ? undefined : onToggleCheckbox} checkboxOverrides={checkboxOverrides} githubRepo={repoInfo?.display} repoHost={repoInfo?.host} headingAnchorId={headingSlugMap.get(group.block.id)} />
+            (() => {
+              const question = questionIndex.byBlock.get(group.block.id);
+              return (
+                <BlockRenderer
+                  imageBaseDir={imageBaseDir}
+                  onImageClick={(src, alt) => setLightbox({ src, alt })}
+                  key={group.block.id}
+                  block={group.block}
+                  onOpenLinkedDoc={onOpenLinkedDoc}
+                  onOpenCodeFile={onOpenCodeFile}
+                  onNavigateAnchor={scrollToAnchor}
+                  onToggleCheckbox={readOnly ? undefined : onToggleCheckbox}
+                  checkboxOverrides={checkboxOverrides}
+                  githubRepo={repoInfo?.display}
+                  repoHost={repoInfo?.host}
+                  headingAnchorId={headingSlugMap.get(group.block.id)}
+                  question={question}
+                  questionTotal={questionIndex.total}
+                  questionAnswer={question ? answersByKey.get(question.question.key) : undefined}
+                  onAnswerQuestion={readOnly ? undefined : onAnswerQuestion}
+                  onSaveQuestionAnswer={readOnly ? undefined : onSaveQuestionAnswer}
+                  saveQuestionAnswerLabel={saveQuestionAnswerLabel}
+                  renderQuestionFooter={renderQuestionFooter}
+                />
+              );
+            })()
           )
         )}
 
@@ -1617,31 +1781,3 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
     </CodePathValidationContext.Provider>
   );
 });
-
-/** Simple lightbox overlay for enlarged image viewing. */
-const ImageLightbox: React.FC<{ src: string; alt: string; onClose: () => void }> = ({ src, alt, onClose }) => {
-  useEffect(() => {
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') onClose();
-    };
-    window.addEventListener('keydown', handleKeyDown);
-    return () => window.removeEventListener('keydown', handleKeyDown);
-  }, [onClose]);
-
-  return (
-    <div
-      className="fixed inset-0 z-[200] flex flex-col items-center justify-center bg-black/80 backdrop-blur-sm cursor-zoom-out"
-      onClick={onClose}
-    >
-      <img
-        src={src}
-        alt={alt}
-        className="max-w-[90vw] max-h-[85vh] object-contain rounded-lg shadow-2xl"
-        onClick={(e) => e.stopPropagation()}
-      />
-      {alt && (
-        <div className="mt-3 text-sm text-white/70 max-w-[90vw] text-center truncate">{alt}</div>
-      )}
-    </div>
-  );
-};

package/components/ai/AIProviderBar.tsx

@@ -37,7 +37,7 @@ export const AIProviderBar: React.FC<AIProviderBarProps> = ({
   const effectiveModel = selectedModel ?? defaultModel?.id ?? '';
   const currentModel = models.find(m => m.id === effectiveModel) ?? defaultModel;
   const reasoningEfforts = currentModel?.reasoningEfforts ?? [];
-  const meta = getProviderMeta(currentProvider?.name ?? 'AI');
+  const meta = getProviderMeta(currentProvider?.name ?? 'AI', currentProvider?.label);
   const Icon = meta.icon;
   // Show only when the selected model actually reports reasoning efforts.
   const showReasoningEffort = !!onReasoningEffortChange && reasoningEfforts.length > 0;
@@ -49,11 +49,11 @@ export const AIProviderBar: React.FC<AIProviderBarProps> = ({
       <select
         value={effectiveProviderId ?? ''}
         onChange={(event) => onProviderChange(event.target.value)}
-        className="min-w-0 max-w-[8rem] bg-transparent text-[11px] text-foreground focus:outline-none"
+        className="min-w-0 max-w-[8rem] bg-transparent text-[11px] text-foreground focus:outline-none [&>option]:bg-card [&>option]:text-foreground"
         aria-label="AI provider"
       >
         {providers.map(provider => {
-          const providerMeta = getProviderMeta(provider.name);
+          const providerMeta = getProviderMeta(provider.name, provider.label);
           return (
             <option key={provider.id} value={provider.id}>
               {providerMeta.label}
@@ -66,7 +66,7 @@ export const AIProviderBar: React.FC<AIProviderBarProps> = ({
         <select
           value={effectiveModel}
           onChange={(event) => onModelChange(event.target.value)}
-          className="min-w-0 flex-1 bg-transparent text-[11px] text-foreground focus:outline-none"
+          className="min-w-0 flex-1 bg-transparent text-[11px] text-foreground focus:outline-none [&>option]:bg-card [&>option]:text-foreground"
           aria-label="AI model"
         >
           {models.map(model => (
@@ -81,7 +81,7 @@ export const AIProviderBar: React.FC<AIProviderBarProps> = ({
         <select
           value={selectedReasoningEffort ?? ''}
           onChange={(event) => onReasoningEffortChange?.(event.target.value || null)}
-          className="w-16 bg-transparent text-[11px] text-foreground focus:outline-none"
+          className="w-16 bg-transparent text-[11px] text-foreground focus:outline-none [&>option]:bg-card [&>option]:text-foreground"
           aria-label="Reasoning effort"
         >
           <option value="">Auto</option>

package/components/ai/DocumentAIChatPanel.tsx

@@ -5,6 +5,7 @@ import { formatRelativeTime, renderChatMarkdown } from '../../utils/aiChatFormat
 import { OverlayScrollArea } from '../OverlayScrollArea';
 import { SparklesIcon } from '../SparklesIcon';
 import { AIProviderBar } from './AIProviderBar';
+import { SessionAskActions, SessionAskStatus, sessionAskErrorTone, type SessionAskAction } from './SessionAskNotice';
 import { submitHint } from '../../utils/platform';
 
 interface DocumentAIChatPanelProps {
@@ -19,6 +20,10 @@ interface DocumentAIChatPanelProps {
   aiProviders?: AIProviderOption[];
   aiConfig?: { providerId: string | null; model: string | null; reasoningEffort?: string | null };
   onAIConfigChange?: (config: { providerId?: string | null; model?: string | null; reasoningEffort?: string | null }) => void;
+  /** "Ask this session": the reviewer's choice on a busy/gone/blocked answer. */
+  onSessionAskAction?: (questionId: string, action: SessionAskAction) => void;
+  /** Label of the provider "Ask a separate AI instead" would use; null hides it. */
+  sessionAskFallbackLabel?: string | null;
 }
 
 function truncate(text: string, max = 180): string {
@@ -64,6 +69,8 @@ export const DocumentAIChatPanel: React.FC<DocumentAIChatPanelProps> = ({
   aiProviders = [],
   aiConfig,
   onAIConfigChange,
+  onSessionAskAction,
+  sessionAskFallbackLabel,
 }) => {
   const scrollRef = useRef<HTMLDivElement>(null);
   const [generalInput, setGeneralInput] = useState('');
@@ -109,7 +116,12 @@ export const DocumentAIChatPanel: React.FC<DocumentAIChatPanelProps> = ({
           )}
 
           {messages.map(entry => (
-            <DocumentQAPair key={entry.question.id} entry={entry} />
+            <DocumentQAPair
+              key={entry.question.id}
+              entry={entry}
+              onSessionAskAction={onSessionAskAction}
+              sessionAskFallbackLabel={sessionAskFallbackLabel}
+            />
           ))}
         </div>
       </OverlayScrollArea>
@@ -152,7 +164,11 @@ export const DocumentAIChatPanel: React.FC<DocumentAIChatPanelProps> = ({
   );
 };
 
-const DocumentQAPair = memo<{ entry: AIChatEntry }>(({ entry }) => {
+const DocumentQAPair = memo<{
+  entry: AIChatEntry;
+  onSessionAskAction?: (questionId: string, action: SessionAskAction) => void;
+  sessionAskFallbackLabel?: string | null;
+}>(({ entry, onSessionAskAction, sessionAskFallbackLabel }) => {
   const { question, response } = entry;
   const renderedResponse = useMemo(
     () => response.text ? renderChatMarkdown(response.text) : null,
@@ -190,12 +206,21 @@ const DocumentQAPair = memo<{ entry: AIChatEntry }>(({ entry }) => {
 
       <div className="group relative p-2.5 rounded-lg border border-border/50 bg-popover/50 hover:bg-muted/30 transition-colors">
         {response.error ? (
-          <p className="text-xs text-destructive">{response.error}</p>
+          <>
+            <p className={`text-xs ${sessionAskErrorTone(response)}`}>{response.error}</p>
+            <SessionAskActions
+              response={response}
+              fallbackLabel={sessionAskFallbackLabel}
+              onAction={onSessionAskAction ? (action) => onSessionAskAction(question.id, action) : undefined}
+            />
+          </>
         ) : response.text ? (
           <div className="text-xs">
             {renderedResponse}
             {response.isStreaming && <span className="ai-streaming-cursor inline-block ml-0.5" />}
           </div>
+        ) : response.status ? (
+          <SessionAskStatus response={response} />
         ) : response.isStreaming ? (
           <span className="text-xs text-muted-foreground">
             <span className="ai-streaming-cursor" /> Thinking...

package/components/ai/SessionAskNotice.tsx

@@ -0,0 +1,89 @@
+import React from 'react';
+import type { AIResponse } from '../../types';
+import { SESSION_ASK_ERROR_CODES } from '../../utils/aiProvider';
+
+/** What the reviewer chose on an "Ask this session" answer that could not run. */
+export type SessionAskAction = 'wait' | 'interrupt' | 'fallback';
+
+/**
+ * In-progress line for a question waiting on a busy session. Renders nothing
+ * for any other response, so providers without a bridge are unaffected.
+ */
+export const SessionAskStatus: React.FC<{ response: AIResponse }> = ({ response }) => {
+  if (!response.status) return null;
+  return (
+    <span className="text-xs text-muted-foreground" data-session-ask-status={response.status}>
+      <span className="ai-streaming-cursor" />{' '}
+      {response.status === 'waiting'
+        ? 'Waiting for the session to finish its current turn…'
+        : 'Interrupting the session…'}
+    </span>
+  );
+};
+
+/**
+ * Colour for an answer's error line: a busy session is a choice, not a
+ * failure, so it reads muted; every other error keeps the destructive tone.
+ */
+export function sessionAskErrorTone(response: Pick<AIResponse, 'errorCode'>): string {
+  return response.errorCode === SESSION_ASK_ERROR_CODES.agentBusy ? 'text-muted-foreground' : 'text-destructive';
+}
+
+const buttonClass =
+  'px-2 py-1 rounded-md text-[10px] font-medium transition-colors';
+
+/**
+ * Follow-up actions under an "Ask this session" error:
+ * - the session is busy: ask when it finishes, or interrupt it and ask now;
+ * - the session is gone or blocked: ask a separate AI instead.
+ * Renders nothing for other errors or when the host passes no handler.
+ */
+export const SessionAskActions: React.FC<{
+  response: AIResponse;
+  onAction?: (action: SessionAskAction) => void;
+  /** Label of the provider the fallback would use; null hides the fallback. */
+  fallbackLabel?: string | null;
+}> = ({ response, onAction, fallbackLabel }) => {
+  if (!onAction || !response.errorCode) return null;
+
+  if (response.errorCode === SESSION_ASK_ERROR_CODES.agentBusy) {
+    return (
+      <div className="flex flex-wrap gap-1.5 mt-2" data-session-ask-actions="busy">
+        <button
+          type="button"
+          onClick={() => onAction('wait')}
+          className={`${buttonClass} bg-primary text-primary-foreground hover:opacity-90`}
+        >
+          Ask when it finishes
+        </button>
+        <button
+          type="button"
+          onClick={() => onAction('interrupt')}
+          className={`${buttonClass} bg-muted text-foreground hover:bg-muted/80`}
+          title="Stops the session's current work, then asks your question"
+        >
+          Interrupt and ask now
+        </button>
+      </div>
+    );
+  }
+
+  if (
+    (response.errorCode === SESSION_ASK_ERROR_CODES.gone || response.errorCode === SESSION_ASK_ERROR_CODES.blocked) &&
+    fallbackLabel
+  ) {
+    return (
+      <div className="flex flex-wrap gap-1.5 mt-2" data-session-ask-actions="fallback">
+        <button
+          type="button"
+          onClick={() => onAction('fallback')}
+          className={`${buttonClass} bg-muted text-foreground hover:bg-muted/80`}
+        >
+          Ask a separate AI instead ({fallbackLabel})
+        </button>
+      </div>
+    );
+  }
+
+  return null;
+};