fix(mcp): write page body before title to avoid split-brain on failure (#159)

updatePage (markdown) and updatePageJson wrote the title via REST FIRST, then
the body via collab. If the body write failed (e.g. a collab persist timeout),
the page was left with the NEW title over its OLD body — a split-brain the tool
reported as an error but never repaired (red-team finding #10).

Reorder both: write the body first, and only set the title after the body has
persisted. Now a body-write failure leaves the title untouched (no split-brain).
A title write failing after a successful body is rarer (REST is fast) and leaves
correct content under a stale title — the strictly lesser inconsistency — which
is the same trade-off the issue's "atomic, or roll back the title" intends,
without the fragility of a rollback write that could itself fail.

No unit test: both paths require a live collab provider and the suite has no
provider mock; the change is a pure reordering. All 306 mcp tests still pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.env.example

@@ -136,6 +136,32 @@ MCP_DOCMOST_PASSWORD=
 # A slow/hung embeddings endpoint fails after this and the batch continues.
 # AI_EMBEDDING_TIMEOUT_MS=120000
 
+# Silence timeout (ms) for streaming chat/agent AI calls AND external-MCP traffic.
+# Bounds time-to-first-byte and the gap BETWEEN chunks (NOT the total turn length),
+# so an arbitrarily long turn that keeps streaming is never cut. Finite so a hung
+# provider is eventually broken instead of leaking forever. Default 900000 (15 min).
+# AI_STREAM_TIMEOUT_MS=900000
+
+# Keep-alive recycle window (ms) for streaming chat/agent AI + external-MCP calls.
+# A pooled connection idle longer than this is closed instead of reused, so a
+# NAT / egress firewall / reverse proxy that silently drops idle connections
+# cannot poison a reused socket into a PRE-RESPONSE `read ECONNRESET`. Lower it if
+# your egress drops idle connections faster than ~10s. Default 10000 (10 s).
+# AI_STREAM_KEEPALIVE_MS=10000
+
+# Silence timeout (ms) for EXTERNAL-MCP transport ONLY (not the chat provider).
+# Tighter than AI_STREAM_TIMEOUT_MS so a byte-silent/hung MCP server is broken in
+# ~5 min instead of 15. Note it also cuts a legitimately long but byte-silent
+# single tool call (a slow crawl that emits nothing until done) and an SSE
+# transport idling >5 min BETWEEN tool calls. Default 300000 (5 min).
+# AI_MCP_STREAM_TIMEOUT_MS=300000
+
+# Total wall-clock cap (ms) for ONE external MCP tool call (app-level, not
+# transport). Aborts a tool that keeps the socket warm (SSE heartbeats / trickle)
+# but never returns a result — which the silence timeout above never breaks.
+# Default 900000 (15 min).
+# AI_MCP_CALL_TIMEOUT_MS=900000
+
 # --- Anonymous public-share AI assistant ---
 # Opt-in per workspace (AI settings -> "public share assistant"; off by default).
 # When enabled, anonymous visitors of a published share can ask an AI about that

.github/workflows/test.yml

@@ -15,6 +15,38 @@ permissions:
 jobs:
   test:
     runs-on: ubuntu-latest
+    # Real Postgres + Redis so the server integration suite (`*.int-spec.ts`,
+    # behind `pnpm --filter server test:int`) runs in CI (red-team finding #7).
+    # Without it, cost-cap / FK-cascade / jsonb-round-trip / real-apply tests
+    # only ran locally, so regressions in those paths stayed green in CI.
+    # Postgres uses the pgvector image because migrations create vector columns
+    # and global-setup runs `CREATE EXTENSION vector`. Credentials/db match the
+    # defaults in apps/server/test/integration/db.ts + global-setup.ts
+    # (docmost / docmost_dev_pw, maintenance db `docmost`, redis on 6379), so no
+    # TEST_*_URL overrides are needed.
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: docmost
+          POSTGRES_PASSWORD: docmost_dev_pw
+          POSTGRES_DB: docmost
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U docmost"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -36,5 +68,12 @@ jobs:
       - name: Build editor-ext
         run: pnpm --filter @docmost/editor-ext build
 
-      - name: Run tests
+      - name: Run unit tests
         run: pnpm -r test
+
+      # Integration suite against the real Postgres/Redis services above. Runs
+      # the FK-cascade, cost-cap, jsonb-round-trip and real-apply specs that the
+      # unit run (mocks only) cannot cover. global-setup drops/recreates the
+      # isolated `docmost_test` DB and migrates it to latest.
+      - name: Run server integration tests
+        run: pnpm --filter server test:int

CHANGELOG.md

@@ -20,9 +20,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `UPDATE users SET is_agent = true WHERE email = '<mcp-account>'`. Never flag a
   human or shared account, or its normal edits get mis-attributed as AI. See the
   AI-agent block in `.env.example`. (#143)
+- **Footnote import diagnostics.** The MCP page-write tools (`create_page`,
+  `update_page`, `import_page_markdown`) now return a `footnoteWarnings` array
+  flagging dangling references, empty or duplicate definitions, and `[^id]`
+  markers inside table rows, so an agent can fix its own markup. The page is
+  still created; the field is omitted when there are no problems. (#166)
+- **AI chat "Protocol" setting (`chatApiStyle`).** A new admin choice in AI
+  settings for the `openai` driver: `openai-compatible` (default) routes chat
+  through `@ai-sdk/openai-compatible`, which surfaces a provider's streamed
+  reasoning (`reasoning_content` → reasoning parts) for z.ai/GLM, DeepSeek,
+  OpenRouter, etc.; `openai` uses the official provider (real-OpenAI
+  reasoning-model request shaping). Chosen explicitly rather than inferred from
+  the base URL, since a custom URL can front real OpenAI too. (#175, #177)
 
 ### Changed
 
+- **AI chat default provider is now `openai-compatible` (reasoning surfaced).**
+  For the `openai` driver the chat provider defaults to the openai-compatible
+  implementation, so a workspace pointing at z.ai/GLM/DeepSeek now streams the
+  model's reasoning out of the box. An endpoint that is real OpenAI behind a
+  custom base URL should set the new `chatApiStyle` "Protocol" to `openai`. (#177)
+
+- **Footnotes now reuse (Pandoc semantics).** Multiple `[^a]` references to the
+  same id are ONE footnote — one number, one definition, several back-references
+  — instead of being renamed to `a__2`, `a__3`. Duplicate `[^a]:` definitions are
+  first-wins on import (the rest are dropped and reported via `footnoteWarnings`),
+  and a reference with no definition yields a single empty footnote rather than
+  one per occurrence. This supersedes the 0.93.0 "survive duplicate-id
+  definitions" behavior for the import path. (#166)
+
 - **Public share AI: default per-workspace hourly assistant cap lowered
   300 → 100.** The limiter falls back to this default whenever
   `SHARE_AI_WORKSPACE_MAX_PER_HOUR` is unset, so a `0.93.0` deployment that

apps/client/public/locales/en-US/translation.json

@@ -710,6 +710,7 @@
   "Authorization header": "Authorization header",
   "Tool allowlist": "Tool allowlist",
   "Optional. Leave empty to allow all tools the server exposes.": "Optional. Leave empty to allow all tools the server exposes.",
+  "Optional guidance for the agent on how and when to use this server's tools. Injected into the system prompt. The server's tools are namespaced as \"<server name>_*\".": "Optional guidance for the agent on how and when to use this server's tools. Injected into the system prompt. The server's tools are namespaced as \"<server name>_*\".",
   "Test": "Test",
   "Available tools": "Available tools",
   "No tools available": "No tools available",
@@ -1307,5 +1308,9 @@
   "Page tree (child pages, recursive)": "Page tree (child pages, recursive)",
   "Render the full nested tree of all descendant pages": "Render the full nested tree of all descendant pages",
   "Showing {{count}} subpages_one": "Showing {{count}} subpage",
-  "Showing {{count}} subpages_other": "Showing {{count}} subpages"
+  "Showing {{count}} subpages_other": "Showing {{count}} subpages",
+  "Protocol": "Protocol",
+  "How chat requests are sent and how reasoning is surfaced": "How chat requests are sent and how reasoning is surfaced",
+  "OpenAI-compatible (surfaces reasoning)": "OpenAI-compatible (surfaces reasoning)",
+  "OpenAI (official)": "OpenAI (official)"
 }

apps/client/public/locales/ru-RU/translation.json

@@ -405,6 +405,8 @@
   "Footnote {{number}}": "Сноска {{number}}",
   "Go to footnote": "Перейти к сноске",
   "Back to reference": "Вернуться к ссылке",
+  "Back to references": "Вернуться к ссылкам",
+  "Back to reference {{label}}": "Вернуться к ссылке {{label}}",
   "Empty footnote": "Пустая сноска",
   "Math inline": "Строчная формула",
   "Insert inline math equation.": "Вставить математическое выражение в строку.",
@@ -749,6 +751,8 @@
   "Manage API keys for all users in the workspace. View the <anchor>API documentation</anchor> for usage details.": "Управляйте API-ключами для всех пользователей в рабочем пространстве. Смотрите <anchor>документацию по API</anchor> для получения информации об использовании.",
   "View the <anchor>API documentation</anchor> for usage details.": "Смотрите <anchor>документацию по API</anchor> для получения информации об использовании.",
   "View the <anchor>MCP documentation</anchor>.": "Смотрите <anchor>документацию по MCP</anchor>.",
+  "Instructions": "Инструкции",
+  "Optional guidance for the agent on how and when to use this server's tools. Injected into the system prompt. The server's tools are namespaced as \"<server name>_*\".": "Необязательное указание агенту, как и когда использовать инструменты этого сервера. Добавляется в системный промпт. Инструменты сервера именуются с префиксом «<имя сервера>_*».",
   "Sources": "Источники",
   "AI Answers not available for attachments": "Ответы ИИ недоступны для вложений",
   "No answer available": "Ответ недоступен",
@@ -1160,5 +1164,9 @@
   "Render the full nested tree of all descendant pages": "Показать полное вложенное дерево всех дочерних страниц",
   "Showing {{count}} subpages_one": "Показано {{count}} подстраница",
   "Showing {{count}} subpages_few": "Показано {{count}} подстраницы",
-  "Showing {{count}} subpages_many": "Показано {{count}} подстраниц"
+  "Showing {{count}} subpages_many": "Показано {{count}} подстраниц",
+  "Protocol": "Протокол",
+  "How chat requests are sent and how reasoning is surfaced": "Как отправляются запросы чата и как показывается reasoning",
+  "OpenAI-compatible (surfaces reasoning)": "OpenAI-совместимый (показывает reasoning)",
+  "OpenAI (official)": "OpenAI (официальный)"
 }

apps/client/src/features/ai-chat/components/ai-chat-window.tsx

@@ -80,17 +80,31 @@ function computeInitialGeom() {
     Math.min(DEFAULT_HEIGHT, window.innerHeight - 2 * EDGE_MARGIN),
   );
   const left = Math.max(EDGE_MARGIN, window.innerWidth - width - 24);
-  const maxTop = Math.max(EDGE_MARGIN, window.innerHeight - height - EDGE_MARGIN);
+  const maxTop = Math.max(
+    EDGE_MARGIN,
+    window.innerHeight - height - EDGE_MARGIN,
+  );
   const top = Math.min(60, maxTop);
   return { left, top, width, height };
 }
 
 // Clamp a geometry so the window stays within the current viewport.
-function clampGeom(g: { left: number; top: number; width: number; height: number }) {
+function clampGeom(g: {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}) {
   const effWidth = Math.max(g.width, MIN_WIDTH);
   const effHeight = Math.max(g.height, MIN_HEIGHT);
-  const maxLeft = Math.max(EDGE_MARGIN, window.innerWidth - effWidth - EDGE_MARGIN);
-  const maxTop = Math.max(EDGE_MARGIN, window.innerHeight - effHeight - EDGE_MARGIN);
+  const maxLeft = Math.max(
+    EDGE_MARGIN,
+    window.innerWidth - effWidth - EDGE_MARGIN,
+  );
+  const maxTop = Math.max(
+    EDGE_MARGIN,
+    window.innerHeight - effHeight - EDGE_MARGIN,
+  );
   return {
     ...g,
     left: Math.min(Math.max(EDGE_MARGIN, g.left), maxLeft),
@@ -151,9 +165,14 @@ export default function AiChatWindow() {
   // Live snapshot of the active thread's useChat state, kept up to date by
   // ChatThread. Lets the export include the in-progress (not-yet-persisted)
   // streaming turn. A ref avoids re-rendering this window on every token.
-  const liveThreadRef = useRef<{ messages: UIMessage[]; isStreaming: boolean }>({
+  const liveThreadRef = useRef<{
+    messages: UIMessage[];
+    isStreaming: boolean;
+    banner: string | null;
+  }>({
     messages: [],
     isStreaming: false,
+    banner: null,
   });
 
   // Live turn-token total (reasoning + output) for the in-flight turn, pushed up
@@ -161,6 +180,12 @@ export default function AiChatWindow() {
   // `null` means no turn is in flight -> the badge falls back to the persisted
   // context size below.
   const [liveTurnTokens, setLiveTurnTokens] = useState<number | null>(null);
+  // Whether the on-screen thread currently holds at least one message. Reported
+  // reactively by ChatThread (the live snapshot lives in a non-reactive ref). This
+  // lets the "Copy chat" button stay available for a brand-new, not-yet-persisted
+  // chat whose first turn is in flight or was interrupted — that case has no
+  // persisted rows yet, so a persisted-rows-only gate would hide the button (#174).
+  const [hasLiveContent, setHasLiveContent] = useState(false);
 
   // The page the user is currently viewing. AiChatWindow lives in a pathless
   // parent layout route, so useParams() can't see :pageSlug. Match the full
@@ -185,17 +210,21 @@ export default function AiChatWindow() {
   // The invalidate closures are passed inline: `onTurnFinished` is read live by
   // useChat's onFinish (never in an effect dep array), so their identity does not
   // matter — no memoization ceremony needed.
-  const { threadKey, waitingForHistory, onTurnFinished, cancelPendingAdoption } =
-    useChatSession({
-      activeChatId,
-      setActiveChatId,
-      chats,
-      messagesLoading,
-      onInvalidateChatList: () =>
-        queryClient.invalidateQueries({ queryKey: AI_CHATS_RQ_KEY }),
-      onInvalidateChatMessages: (id) =>
-        queryClient.invalidateQueries({ queryKey: AI_CHAT_MESSAGES_RQ_KEY(id) }),
-    });
+  const {
+    threadKey,
+    waitingForHistory,
+    onTurnFinished,
+    cancelPendingAdoption,
+  } = useChatSession({
+    activeChatId,
+    setActiveChatId,
+    chats,
+    messagesLoading,
+    onInvalidateChatList: () =>
+      queryClient.invalidateQueries({ queryKey: AI_CHATS_RQ_KEY }),
+    onInvalidateChatMessages: (id) =>
+      queryClient.invalidateQueries({ queryKey: AI_CHAT_MESSAGES_RQ_KEY(id) }),
+  });
 
   // startNewChat/selectChat set the public atom; the hook's render-phase
   // reconciler handles the remount when activeChatId actually CHANGES. But
@@ -231,13 +260,23 @@ export default function AiChatWindow() {
     () => chats?.items?.find((c) => c.id === activeChatId) ?? null,
     [chats, activeChatId],
   );
-  const canExport = !!activeChatId && !!messageRows && messageRows.length > 0;
+  // Export is available when there is anything to export: either persisted rows
+  // for the active chat, OR a live on-screen thread with at least one message.
+  // The live arm covers a brand-new chat whose first turn is streaming or was
+  // interrupted before the server persisted any row (#174); the persisted arm is
+  // the steady-state path for an already-saved chat (#160).
+  const canExport =
+    hasLiveContent ||
+    (!!activeChatId && !!messageRows && messageRows.length > 0);
 
   // The role to display in the header and as the assistant's name. Prefer the
   // persisted role of an existing chat (chat-list JOIN); fall back to the role
   // picked via a card click for a brand-new or just-adopted chat. selectChat
   // resets selectedRoleId, so this fallback never leaks into an unrelated chat.
-  const currentRole = useMemo<{ name: string; emoji: string | null } | null>(() => {
+  const currentRole = useMemo<{
+    name: string;
+    emoji: string | null;
+  } | null>(() => {
     if (activeChat?.roleName) {
       return { name: activeChat.roleName, emoji: activeChat.roleEmoji ?? null };
     }
@@ -249,28 +288,44 @@ export default function AiChatWindow() {
   // call) and copy it to the clipboard. The "Copied" notification is the
   // feedback.
   const handleCopy = useCallback(() => {
-    if (!activeChatId || !messageRows || messageRows.length === 0) return;
-    // While the active thread is streaming, the current user message and the
-    // in-progress assistant reply are NOT yet in messageRows (the persisted
-    // query is only refetched after the turn finishes). Pull the live tail —
-    // messages whose id is not among the persisted rows — and append them,
-    // flagging the streaming assistant message as still generating.
+    // Export gate. There must be SOMETHING to export — either a live on-screen
+    // message or a persisted row. A brand-new chat whose first turn is streaming
+    // or was interrupted has live messages but no persisted rows yet; it still
+    // exports the on-screen thread WYSIWYG (#174). Only a truly empty chat (no
+    // live messages and no rows) is non-exportable (the button is hidden too —
+    // see `canExport`).
     const live = liveThreadRef.current;
-    const rowIds = new Set(messageRows.map((r) => r.id));
-    const pending = live.isStreaming
-      ? live.messages
-          .filter((m) => !rowIds.has(m.id))
-          .map((m) => ({
-            role: m.role,
-            parts: (m.parts ?? []) as { type: string; text?: string }[],
-            generating: m.role === "assistant",
-          }))
-      : [];
+    const hasRows = !!messageRows && messageRows.length > 0;
+    if (live.messages.length === 0 && !hasRows) return;
+    // WYSIWYG export: the live on-screen messages ARE the document (so a partial
+    // reply from an interrupted turn — which never reached the persisted rows —
+    // is exported just as it appears). The persisted rows enrich each live
+    // message (token usage / error / timestamp) by id and serve as the fallback
+    // when the live mirror is empty. The on-screen banner is appended too. See
+    // issues #160 and #174. `chatId` may be null for a not-yet-saved chat — use a
+    // placeholder so the header line still renders.
     const markdown = buildChatMarkdown({
       title: activeChat?.title ?? null,
-      chatId: activeChatId,
+      chatId: activeChatId ?? "unsaved",
+      live: live.messages.map((m) => ({
+        id: m.id,
+        role: m.role,
+        parts: (m.parts ?? []) as { type: string; text?: string }[],
+        metadata: m.metadata as
+          | {
+              usage?: {
+                inputTokens?: number;
+                outputTokens?: number;
+                totalTokens?: number;
+                reasoningTokens?: number;
+              };
+              error?: string;
+            }
+          | undefined,
+      })),
       rows: messageRows,
-      pending,
+      isStreaming: live.isStreaming,
+      banner: live.banner,
       t,
     });
     clipboard.copy(markdown);
@@ -351,7 +406,8 @@ export default function AiChatWindow() {
       const width = el.offsetWidth;
       const height = el.offsetHeight;
       setGeom((prev) => {
-        if (!prev || (prev.width === width && prev.height === height)) return prev;
+        if (!prev || (prev.width === width && prev.height === height))
+          return prev;
         return { ...prev, width, height };
       });
     });
@@ -497,11 +553,15 @@ export default function AiChatWindow() {
               flash a "0" badge before any token streams in (#151 review). */}
           {liveTurnTokens !== null && liveTurnTokens > 0 ? (
             <Tooltip label={t("Tokens generated this turn")} withArrow>
-              <span className={classes.badge}>{formatTokens(liveTurnTokens)}</span>
+              <span className={classes.badge}>
+                {formatTokens(liveTurnTokens)}
+              </span>
             </Tooltip>
           ) : contextTokens > 0 ? (
             <Tooltip label={t("Current context size")} withArrow>
-              <span className={classes.badge}>{formatTokens(contextTokens)}</span>
+              <span className={classes.badge}>
+                {formatTokens(contextTokens)}
+              </span>
             </Tooltip>
           ) : null}
         </div>
@@ -515,7 +575,11 @@ export default function AiChatWindow() {
               aria-label={t("Copy chat")}
               onClick={handleCopy}
             >
-              {clipboard.copied ? <IconCheck size={14} /> : <IconCopy size={14} />}
+              {clipboard.copied ? (
+                <IconCheck size={14} />
+              ) : (
+                <IconCopy size={14} />
+              )}
             </button>
           )}
           <button
@@ -623,6 +687,7 @@ export default function AiChatWindow() {
               onTurnFinished={onTurnFinished}
               liveStateRef={liveThreadRef}
               onLiveTurnTokens={setLiveTurnTokens}
+              onLiveContentChange={setHasLiveContent}
             />
           )}
         </div>

apps/client/src/features/ai-chat/components/ai-chat.module.css

@@ -122,7 +122,11 @@
     margin-top: 4px;
     font-size: var(--mantine-font-size-xs);
     color: light-dark(var(--mantine-color-gray-7), var(--mantine-color-dark-1));
-    white-space: pre-wrap;
+    /* NOTE: `white-space: pre-wrap` is intentionally NOT set here. On the
+       rendered markdown <div> it would turn the newlines between block tags
+       (</li>\n<li>, </p>\n<ol>) into visible blank lines/indents on top of the
+       margins. The plain-text fallback <Text> that needs pre-wrap sets it
+       inline itself (see reasoning-block.tsx). */
 }
 
 .reasoningText p {

apps/client/src/features/ai-chat/components/chat-thread.tsx

@@ -73,13 +73,25 @@ interface ChatThreadProps {
    *  "Copy chat" export can include the in-progress, not-yet-persisted
    *  assistant message. A ref (not state) avoids re-rendering the parent on
    *  every streamed delta. */
-  liveStateRef?: MutableRefObject<{ messages: UIMessage[]; isStreaming: boolean }>;
+  liveStateRef?: MutableRefObject<{
+    messages: UIMessage[];
+    isStreaming: boolean;
+    banner: string | null;
+  }>;
   /** Reports the live turn-token total (reasoning + output) for the in-flight
    *  turn so the parent can show a header badge that ticks mid-stream. THROTTLED
    *  here (~8 Hz) so the parent re-renders a handful of times a second, not on
    *  every streamed delta. Called with `null` when no turn is in flight (the
    *  parent then reverts the badge to the persisted context size). */
   onLiveTurnTokens?: (tokens: number | null) => void;
+  /** Reports whether the live thread currently holds at least one message, so the
+   *  parent can gate the "Copy chat" button on the on-screen thread rather than on
+   *  the persisted rows alone. This stays truthy for a brand-new, not-yet-saved
+   *  chat the moment its first user message appears — so an interrupted very first
+   *  turn (no persisted rows yet) is still exportable (#174). Called with `false`
+   *  on unmount so a thread torn down by `key` on chat switch can't leave the
+   *  button enabled for the next, possibly empty, chat. */
+  onLiveContentChange?: (hasContent: boolean) => void;
 }
 
 /**
@@ -125,6 +137,7 @@ export default function ChatThread({
   onTurnFinished,
   liveStateRef,
   onLiveTurnTokens,
+  onLiveContentChange,
 }: ChatThreadProps) {
   const { t } = useTranslation();
 
@@ -309,18 +322,49 @@ export default function ChatThread({
     if (isStreaming) setStopNotice(null);
   }, [isStreaming]);
 
+  // Classify the turn error into a heading + detail so the banner names the cause
+  // (connection reset, timeout, rate limit, context overflow, quota, ...) instead
+  // of a generic "Something went wrong". Computed here (not only in the JSX) so
+  // the SAME on-screen banner text can be mirrored into the export (issue #160).
+  const errorView = error ? describeChatError(error.message ?? "", t) : null;
+
+  // The exact banner the user sees under the message list, flattened to a single
+  // string for the "Copy chat" export so the artifact records the interruption
+  // WYSIWYG. Mirrors the JSX precedence below: error first, else the stop notice.
+  const banner = errorView
+    ? errorView.detail
+      ? `${errorView.title} — ${errorView.detail}`
+      : errorView.title
+    : stopNotice === "manual"
+      ? t("Response stopped.")
+      : stopNotice === "disconnect"
+        ? t("Connection lost — the answer was interrupted.")
+        : null;
+
   // Mirror the live useChat snapshot into the parent-owned ref so the export
-  // (handled in AiChatWindow) can include the in-progress streaming turn. The
-  // cleanup clears the ref on unmount so a thread torn down by `key` on chat
-  // switch can't leak its (possibly still-streaming) tail into the next chat's
-  // export before the new thread's effect repopulates the ref.
+  // (handled in AiChatWindow) can include the in-progress streaming turn AND the
+  // on-screen banner. The cleanup clears the ref on unmount so a thread torn down
+  // by `key` on chat switch can't leak its (possibly still-streaming) tail into
+  // the next chat's export before the new thread's effect repopulates the ref.
   useEffect(() => {
     if (!liveStateRef) return;
-    liveStateRef.current = { messages, isStreaming };
+    liveStateRef.current = { messages, isStreaming, banner };
     return () => {
-      liveStateRef.current = { messages: [], isStreaming: false };
+      liveStateRef.current = { messages: [], isStreaming: false, banner: null };
     };
-  }, [liveStateRef, messages, isStreaming]);
+  }, [liveStateRef, messages, isStreaming, banner]);
+
+  // Reactively report "the live thread has content" to the parent. `liveStateRef`
+  // above is a ref (deliberately non-reactive so streaming deltas don't re-render
+  // the parent), so the export button needs a SEPARATE reactive signal to flip on
+  // for a not-yet-persisted chat. Keyed on the boolean only — identical values are
+  // a no-op setState in the parent, so this does not add per-delta re-renders.
+  const hasLiveContent = messages.length > 0;
+  useEffect(() => {
+    if (!onLiveContentChange) return;
+    onLiveContentChange(hasLiveContent);
+    return () => onLiveContentChange(false);
+  }, [onLiveContentChange, hasLiveContent]);
 
   // Report the live turn-token total to the parent header badge, THROTTLED to
   // ~8 Hz so the parent re-renders a few times a second instead of on every
@@ -343,8 +387,7 @@ export default function ChatThread({
       return;
     }
     const tail = messages[messages.length - 1];
-    const live =
-      tail?.role === "assistant" ? liveTurnTokens(tail) : null;
+    const live = tail?.role === "assistant" ? liveTurnTokens(tail) : null;
     const total = live ? live.reasoning + live.output : 0;
     const now = Date.now();
     const MIN_INTERVAL = 120; // ms (~8 Hz)
@@ -370,11 +413,6 @@ export default function ChatThread({
     };
   }, []);
 
-  // Classify the turn error into a heading + detail so the banner names the cause
-  // (connection reset, timeout, rate limit, context overflow, quota, ...) instead
-  // of a generic "Something went wrong".
-  const errorView = error ? describeChatError(error.message ?? "", t) : null;
-
   // A role was picked with autoStart=false: the role is bound but NOTHING was
   // sent, so chatId stays null and the empty state would keep showing the cards.
   // This flag hides the cards and reveals the composer (with the role indicated)

apps/client/src/features/ai-chat/components/message-list.tsx

@@ -6,7 +6,6 @@ import MessageItem from "@/features/ai-chat/components/message-item.tsx";
 import TypingIndicator from "@/features/ai-chat/components/typing-indicator.tsx";
 import { isToolPart, toolRunState, ToolUiPart } from "@/features/ai-chat/utils/tool-parts.tsx";
 import { assistantMessageHasVisibleContent } from "@/features/ai-chat/utils/message-content.ts";
-import { liveTurnTokens } from "@/features/ai-chat/utils/count-stream-tokens.ts";
 import classes from "@/features/ai-chat/components/ai-chat.module.css";
 
 interface MessageListProps {
@@ -51,7 +50,9 @@ const BOTTOM_THRESHOLD = 40;
  * assistant message's LAST part is not live output:
  *  - the last message is still the user's (assistant hasn't started a row), or
  *  - the assistant row has no parts yet, or
- *  - its last part is an empty/whitespace text part, or
+ *  - its last part is an empty/whitespace text part, or a finished ("done")
+ *    text part while the turn continues (the model paused after some narration
+ *    and is thinking about its next step), or
  *  - its last part is a finished/errored tool (the model is thinking about the
  *    next step between tool calls).
  * It hides only while output is actively rendering: a non-empty streaming text
@@ -65,7 +66,19 @@ export function showTypingIndicator(messages: UIMessage[], isStreaming: boolean)
   const lastPart = last.parts[last.parts.length - 1];
   if (!lastPart) return true; // assistant row exists but has no parts yet.
   // The answer text is actively streaming in -> MessageItem renders it; no dots.
-  if (lastPart.type === "text" && lastPart.text.trim().length > 0) return false;
+  // Only while it is STILL streaming, though: once a non-empty text part is
+  // finalized ("done") but the turn is still in flight, the model has paused
+  // after some narration and is working on its next step (e.g. about to call a
+  // tool) — nothing is visibly progressing, so the dots must show. A text part
+  // without a `state` is treated as still-rendering (kept suppressed); this
+  // branch only runs while streaming, where live parts always carry a state.
+  if (
+    lastPart.type === "text" &&
+    lastPart.text.trim().length > 0 &&
+    (lastPart as { state?: "streaming" | "done" }).state !== "done"
+  ) {
+    return false;
+  }
   // A tool still in flight shows its own Loader in ToolCallCard -> no dots.
   if (
     isToolPart(lastPart.type) &&
@@ -95,19 +108,6 @@ export function typingIndicatorShowsName(messages: UIMessage[]): boolean {
   return !assistantMessageHasVisibleContent(last);
 }
 
-/**
- * The live thinking-token count to show on the standalone typing indicator. It
- * is the reasoning split of the tail assistant message (estimate while streaming,
- * authoritative once the server attaches usage at a step/turn boundary). Returns
- * 0 when the turn has produced no reasoning yet — the indicator then shows the
- * plain "Thinking…" line.
- */
-export function tailThinkingTokens(messages: UIMessage[]): number {
-  const last = messages[messages.length - 1];
-  if (!last || last.role !== "assistant") return 0;
-  return liveTurnTokens(last).reasoning;
-}
-
 /**
  * Scrollable transcript. Auto-scrolls to the newest message as it streams in,
  * but only while the user is pinned to the bottom — if they scrolled up to read
@@ -208,7 +208,6 @@ export default function MessageList({
           <TypingIndicator
             assistantName={assistantName}
             showName={typingIndicatorShowsName(messages)}
-            thinkingTokens={tailThinkingTokens(messages)}
           />
         )}
       </Stack>

apps/client/src/features/ai-chat/components/reasoning-block.tsx

@@ -3,6 +3,7 @@ import { Box, Collapse, Group, Text, UnstyledButton } from "@mantine/core";
 import { IconChevronDown } from "@tabler/icons-react";
 import { useTranslation } from "react-i18next";
 import { estimateTokens } from "@/features/ai-chat/utils/count-stream-tokens.ts";
+import { collapseBlankLines } from "@/features/ai-chat/utils/collapse-blank-lines.ts";
 import { renderChatMarkdown } from "@/features/ai-chat/utils/markdown.ts";
 import classes from "@/features/ai-chat/components/ai-chat.module.css";
 
@@ -33,7 +34,12 @@ export default function ReasoningBlock({ text, tokens }: ReasoningBlockProps) {
   // Authoritative count wins; otherwise estimate live from the streamed text.
   const count = tokens && tokens > 0 ? tokens : estimateTokens(text);
   const trimmed = text.trim();
-  const html = trimmed ? renderChatMarkdown(trimmed, {}) : "";
+  // Collapse the blank-line gaps the model emits between every list item /
+  // paragraph so the reasoning renders compactly (tight lists, joined
+  // paragraphs) — see collapseBlankLines. ONLY here, not in the normal answer.
+  const html = trimmed
+    ? renderChatMarkdown(collapseBlankLines(trimmed), {})
+    : "";
 
   return (
     <Box className={classes.reasoningBlock} mb={6}>

apps/client/src/features/ai-chat/components/show-typing-indicator.test.ts

@@ -82,4 +82,14 @@ describe("showTypingIndicator", () => {
       showTypingIndicator([msg("assistant", [doneTool, text])], true),
     ).toBe(false);
   });
+
+  it("shows while streaming after a text part is finalized (paused before the next step)", () => {
+    const doneText = { type: "text", text: "Now creating the page in", state: "done" } as unknown as UIMessage["parts"][number];
+    expect(showTypingIndicator([msg("assistant", [doneText])], true)).toBe(true);
+  });
+
+  it("hides while a text part is actively streaming (state: streaming)", () => {
+    const streamingText = { type: "text", text: "Now writ", state: "streaming" } as unknown as UIMessage["parts"][number];
+    expect(showTypingIndicator([msg("assistant", [streamingText])], true)).toBe(false);
+  });
 });

apps/client/src/features/ai-chat/components/tail-thinking-tokens.test.ts

@@ -1,50 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { UIMessage } from "@ai-sdk/react";
-import { tailThinkingTokens } from "@/features/ai-chat/components/message-list.tsx";
-
-/**
- * Pure-helper tests for `tailThinkingTokens`: the live thinking-token count the
- * standalone typing indicator shows. It is the reasoning split of the tail
- * assistant message (estimate while streaming, authoritative once usage arrives).
- */
-const msg = (
-  role: "user" | "assistant",
-  parts: unknown[],
-  metadata?: unknown,
-): UIMessage =>
-  ({ id: Math.random().toString(), role, parts, metadata }) as UIMessage;
-
-describe("tailThinkingTokens", () => {
-  it("is 0 when there are no messages", () => {
-    expect(tailThinkingTokens([])).toBe(0);
-  });
-
-  it("is 0 when the tail message is the user's", () => {
-    expect(tailThinkingTokens([msg("user", [{ type: "text", text: "q" }])])).toBe(0);
-  });
-
-  it("is 0 when the assistant has produced no reasoning yet", () => {
-    expect(
-      tailThinkingTokens([msg("assistant", [{ type: "text", text: "answer" }])]),
-    ).toBe(0);
-  });
-
-  it("estimates reasoning tokens from streamed reasoning text", () => {
-    // 8 chars -> 2 tokens.
-    expect(
-      tailThinkingTokens([
-        msg("assistant", [{ type: "reasoning", text: "12345678" }]),
-      ]),
-    ).toBe(2);
-  });
-
-  it("uses authoritative usage.reasoningTokens once the server attaches it", () => {
-    expect(
-      tailThinkingTokens([
-        msg("assistant", [{ type: "reasoning", text: "x" }], {
-          usage: { outputTokens: 100, reasoningTokens: 42 },
-        }),
-      ]),
-    ).toBe(42);
-  });
-});

apps/client/src/features/ai-chat/components/typing-indicator.tsx

@@ -16,12 +16,6 @@ interface TypingIndicatorProps {
    * assistant row above already shows the same name, to avoid a duplicate label.
    */
   showName?: boolean;
-  /**
-   * Live thinking/reasoning token count for the in-flight turn. When > 0 the
-   * typing line becomes `Thinking… · {count} tokens` (like Claude Code). Omitted
-   * / 0 keeps the plain `Thinking…` line.
-   */
-  thinkingTokens?: number;
 }
 
 /**
@@ -32,23 +26,20 @@ interface TypingIndicatorProps {
  *
  * Mirrors the assistant row layout in MessageItem (the dimmed label), so it reads
  * as the assistant's bubble taking shape. The dimmed label uses the configured
- * identity name when provided (otherwise the generic "AI agent"), while the
- * typing line is always the generic "Thinking…" (it never includes the
- * role/identity name).
+ * identity name when provided (otherwise the generic "AI agent"); below it the
+ * animated dots stand in for the nascent bubble until content arrives.
  */
-export default function TypingIndicator({ assistantName, showName = true, thinkingTokens }: TypingIndicatorProps) {
+export default function TypingIndicator({ assistantName, showName = true }: TypingIndicatorProps) {
   const { t } = useTranslation();
   const name = resolveAssistantName(assistantName);
-  // Show the running thinking-token count only once there is something to count.
-  const thinkingLine =
-    thinkingTokens && thinkingTokens > 0
-      ? t("Thinking… · {{count}} tokens", { count: thinkingTokens })
-      : t("Thinking…");
 
   return (
     <Box className={classes.messageRow}>
       {showName !== false && (
-        <Text size="xs" c="dimmed" mb={4}>
+        // Extra bottom gap (vs MessageItem's mb={4}) gives the small bouncing
+        // dots room below the name label; without it they crowd the label. Only
+        // applies when the name is shown — the nameless case spaces fine on its own.
+        <Text size="xs" c="dimmed" mb={8}>
           {name ?? t("AI agent")}
         </Text>
       )}
@@ -58,9 +49,6 @@ export default function TypingIndicator({ assistantName, showName = true, thinki
           <span />
           <span />
         </span>
-        <Text size="sm" c="dimmed">
-          {thinkingLine}
-        </Text>
       </Group>
     </Box>
   );

apps/client/src/features/ai-chat/utils/chat-markdown.test.ts

@@ -165,7 +165,9 @@ describe("buildChatMarkdown — tool parts", () => {
       ],
       t,
     });
-    expect(md).toContain("**Tool: Ran tool mysteryTool** (`mysteryTool`) — error");
+    expect(md).toContain(
+      "**Tool: Ran tool mysteryTool** (`mysteryTool`) — error",
+    );
     expect(md).toContain("**Error:** boom");
   });
 
@@ -307,7 +309,9 @@ describe("buildChatMarkdown — token totals", () => {
         row({
           role: "assistant",
           content: "x",
-          metadata: { usage: { inputTokens: 3, outputTokens: 4, totalTokens: 99 } },
+          metadata: {
+            usage: { inputTokens: 3, outputTokens: 4, totalTokens: 99 },
+          },
         }),
       ],
       t,
@@ -367,125 +371,377 @@ describe("buildChatMarkdown — token totals", () => {
   });
 });
 
-describe("buildChatMarkdown — pending / in-progress messages", () => {
-  it("continues the heading numbering after the persisted rows", () => {
+// A minimal on-screen (live) message, matching the subset buildChatMarkdown reads.
+function live(partial: {
+  id?: string;
+  role?: string;
+  parts?: { type: string; text?: string }[];
+  metadata?: { usage?: Record<string, number>; error?: string };
+}) {
+  return {
+    id: partial.id ?? "live-id",
+    role: partial.role ?? "assistant",
+    parts: partial.parts ?? [],
+    metadata: partial.metadata,
+  };
+}
+
+describe("buildChatMarkdown — live (WYSIWYG) source", () => {
+  it("uses the live messages as the document (what's on screen), numbered from 1", () => {
     const md = buildChatMarkdown({
       title: "t",
       chatId: "c",
-      rows: [row({ role: "user", content: "persisted" })],
-      pending: [
-        {
+      // Persisted rows hold only the user turn; the assistant reply is live-only.
+      rows: [row({ id: "u1", role: "user", content: "persisted user" })],
+      live: [
+        live({
+          id: "u1",
           role: "user",
-          parts: [{ type: "text", text: "live question" }],
-          generating: false,
-        },
-        {
+          parts: [{ type: "text", text: "on-screen user" }],
+        }),
+        live({
+          id: "a1",
           role: "assistant",
-          parts: [{ type: "text", text: "live answer" }],
-          generating: true,
-        },
+          parts: [{ type: "text", text: "on-screen reply" }],
+        }),
       ],
+      isStreaming: false,
       t,
     });
     expect(md).toContain("## 1. You");
-    expect(md).toContain("## 2. You");
-    expect(md).toContain("## 3. AI agent");
-    expect(md).toContain("live question");
-    expect(md).toContain("live answer");
+    expect(md).toContain("## 2. AI agent");
+    expect(md).toContain("on-screen user");
+    expect(md).toContain("on-screen reply");
+    // Message count reflects the LIVE document, not rows + live.
+    expect(md).toContain("- Messages: 2");
   });
 
-  it("flags a generating assistant pending message as still being generated", () => {
+  it("captures a partial reply from an interrupted (non-streaming) turn — no 'generating' note", () => {
     const md = buildChatMarkdown({
       title: "t",
       chatId: "c",
-      rows: [row({ role: "user", content: "persisted" })],
-      pending: [
-        {
+      rows: [row({ id: "u1", role: "user", content: "q" })],
+      live: [
+        live({ id: "u1", role: "user", parts: [{ type: "text", text: "q" }] }),
+        live({
+          id: "a-live",
           role: "assistant",
-          parts: [{ type: "text", text: "partial reply" }],
-          generating: true,
-        },
+          parts: [{ type: "text", text: "partial plan before the drop" }],
+        }),
       ],
+      isStreaming: false, // the stream dropped — not streaming anymore
+      banner: "Connection lost — the answer was interrupted.",
       t,
     });
-    expect(md).toContain("partial reply");
-    expect(md).toContain("still being generated");
+    // The partial assistant answer that was on screen IS in the export.
+    expect(md).toContain("partial plan before the drop");
+    // It is NOT flagged still-generating (the turn is over, just interrupted).
+    expect(md).not.toContain("still being generated");
+    // The on-screen banner is recorded at the end.
+    expect(md).toContain("Connection lost — the answer was interrupted.");
   });
 
-  it("renders a non-generating user pending message without the note", () => {
+  it("flags ONLY the tail assistant as still generating, and only while streaming", () => {
+    const streaming = buildChatMarkdown({
+      title: "t",
+      chatId: "c",
+      rows: [],
+      live: [
+        live({
+          id: "a",
+          role: "assistant",
+          parts: [{ type: "text", text: "done earlier" }],
+        }),
+        live({
+          id: "u",
+          role: "user",
+          parts: [{ type: "text", text: "next q" }],
+        }),
+        live({
+          id: "b",
+          role: "assistant",
+          parts: [{ type: "text", text: "streaming now" }],
+        }),
+      ],
+      isStreaming: true,
+      t,
+    });
+    // Exactly one "still being generated" note (the tail assistant).
+    expect(streaming.match(/still being generated/g)?.length).toBe(1);
+
+    const idle = buildChatMarkdown({
+      title: "t",
+      chatId: "c",
+      rows: [],
+      live: [
+        live({
+          id: "b",
+          role: "assistant",
+          parts: [{ type: "text", text: "final" }],
+        }),
+      ],
+      isStreaming: false,
+      t,
+    });
+    expect(idle).not.toContain("still being generated");
+  });
+
+  it("does NOT flag a completed assistant as generating when the streaming tail is a user message", () => {
+    // The `status === "submitted"` window: the user just sent, isStreaming is
+    // already true, but the new assistant turn has no message yet so the tail is
+    // the USER message. The previous assistant answer is complete on screen and
+    // must not be marked still-generating (WYSIWYG; regression for #160 review).
     const md = buildChatMarkdown({
       title: "t",
       chatId: "c",
-      rows: [row({ role: "user", content: "persisted" })],
-      pending: [
-        {
+      rows: [],
+      live: [
+        live({
+          id: "a",
+          role: "assistant",
+          parts: [{ type: "text", text: "completed answer" }],
+        }),
+        live({
+          id: "u",
           role: "user",
-          parts: [{ type: "text", text: "my live message" }],
-          generating: false,
-        },
+          parts: [{ type: "text", text: "the new question" }],
+        }),
       ],
+      isStreaming: true,
       t,
     });
-    expect(md).toContain("my live message");
+    expect(md).toContain("completed answer");
     expect(md).not.toContain("still being generated");
   });
 
-  it("includes the pending messages in the metadata message count", () => {
+  it("emits the heading + note for a streaming tail assistant with empty parts", () => {
     const md = buildChatMarkdown({
       title: "t",
       chatId: "c",
-      rows: [
-        row({ role: "user", content: "a" }),
-        row({ role: "assistant", content: "b" }),
-      ],
-      pending: [
-        {
-          role: "user",
-          parts: [{ type: "text", text: "c" }],
-          generating: false,
-        },
-        {
-          role: "assistant",
-          parts: [{ type: "text", text: "d" }],
-          generating: true,
-        },
-      ],
-      t,
-    });
-    // 2 persisted rows + 2 pending = 4.
-    expect(md).toContain("- Messages: 4");
-  });
-
-  it("emits the heading and note for a generating assistant with empty parts", () => {
-    expect(() =>
-      buildChatMarkdown({
-        title: "t",
-        chatId: "c",
-        rows: [row({ role: "user", content: "persisted" })],
-        pending: [
-          {
-            role: "assistant",
-            parts: [],
-            generating: true,
-          },
-        ],
-        t,
-      }),
-    ).not.toThrow();
-    const md = buildChatMarkdown({
-      title: "t",
-      chatId: "c",
-      rows: [row({ role: "user", content: "persisted" })],
-      pending: [
-        {
-          role: "assistant",
-          parts: [],
-          generating: true,
-        },
+      rows: [row({ id: "u1", role: "user", content: "q" })],
+      live: [
+        live({ id: "u1", role: "user", parts: [{ type: "text", text: "q" }] }),
+        live({ id: "a-live", role: "assistant", parts: [] }),
       ],
+      isStreaming: true,
       t,
     });
     expect(md).toContain("## 2. AI agent");
     expect(md).toContain("still being generated");
   });
 });
+
+describe("buildChatMarkdown — live enrichment from persisted rows", () => {
+  it("pulls usage / error / timestamp from the persisted row matched by id", () => {
+    const md = buildChatMarkdown({
+      title: "t",
+      chatId: "c",
+      rows: [
+        row({
+          id: "a1",
+          role: "assistant",
+          content: "x",
+          createdAt: "2026-06-22T10:00:00.000Z",
+          metadata: {
+            usage: { inputTokens: 10, outputTokens: 5 },
+            error: "rate limited",
+          },
+        }),
+      ],
+      live: [
+        // Same id as the persisted row, but no usage/error/timestamp on the live msg.
+        live({
+          id: "a1",
+          role: "assistant",
+          parts: [{ type: "text", text: "reply" }],
+        }),
+      ],
+      isStreaming: false,
+      t,
+    });
+    expect(md).toContain("reply");
+    // Token footer + total come from the enriched row.
+    expect(md).toContain("_Tokens — in: 10, out: 5, total: 15_");
+    expect(md).toContain("- Total tokens: 15");
+    expect(md).toContain("**⚠️ Error:** rate limited");
+    // The persisted timestamp is carried into the export.
+    expect(md).toContain("<!-- 2026-06-22T10:00:00.000Z -->");
+  });
+
+  it("prefers authoritative usage already on the live message over the row's", () => {
+    const md = buildChatMarkdown({
+      title: "t",
+      chatId: "c",
+      rows: [
+        row({
+          id: "a1",
+          role: "assistant",
+          content: "x",
+          metadata: {
+            usage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 },
+          },
+        }),
+      ],
+      live: [
+        live({
+          id: "a1",
+          role: "assistant",
+          parts: [{ type: "text", text: "reply" }],
+          metadata: {
+            usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+          },
+        }),
+      ],
+      isStreaming: false,
+      t,
+    });
+    // The live (authoritative, freshest) usage wins, not the stale row usage.
+    expect(md).toContain("- Total tokens: 150");
+    expect(md).not.toContain("- Total tokens: 2");
+  });
+
+  it("a current-turn live message with no matching row renders without a footer", () => {
+    const md = buildChatMarkdown({
+      title: "t",
+      chatId: "c",
+      rows: [row({ id: "u1", role: "user", content: "q" })],
+      live: [
+        live({ id: "u1", role: "user", parts: [{ type: "text", text: "q" }] }),
+        live({
+          id: "a-live",
+          role: "assistant",
+          parts: [{ type: "text", text: "fresh reply" }],
+        }),
+      ],
+      isStreaming: false,
+      t,
+    });
+    expect(md).toContain("fresh reply");
+    // No persisted row for the live assistant -> no token footer, no timestamp.
+    expect(md).not.toContain("_Tokens —");
+    expect(md).not.toContain("<!-- undefined -->");
+  });
+});
+
+describe("buildChatMarkdown — fallback + banner", () => {
+  it("falls back to the persisted rows when there are no live messages", () => {
+    const md = buildChatMarkdown({
+      title: "t",
+      chatId: "c",
+      rows: [
+        row({ role: "user", content: "from rows" }),
+        row({
+          role: "assistant",
+          content: "answer",
+          metadata: { usage: { inputTokens: 4, outputTokens: 6 } },
+        }),
+      ],
+      live: [], // empty live mirror -> fallback path
+      isStreaming: false,
+      t,
+    });
+    expect(md).toContain("## 1. You");
+    expect(md).toContain("## 2. AI agent");
+    expect(md).toContain("from rows");
+    expect(md).toContain("- Messages: 2");
+    expect(md).toContain("- Total tokens: 10");
+  });
+
+  it("appends the on-screen banner once, after the messages", () => {
+    const md = buildChatMarkdown({
+      title: "t",
+      chatId: "c",
+      rows: [row({ role: "user", content: "q" })],
+      live: [
+        live({ id: "u", role: "user", parts: [{ type: "text", text: "q" }] }),
+      ],
+      isStreaming: false,
+      banner: "Rate limit reached — try again shortly.",
+      t,
+    });
+    expect(md).toContain("_⚠️ Rate limit reached — try again shortly._");
+    // Banner comes after the (only) message block.
+    expect(md.indexOf("Rate limit reached")).toBeGreaterThan(
+      md.indexOf("## 1."),
+    );
+  });
+
+  it("omits the banner block when there is no banner", () => {
+    const md = buildChatMarkdown({
+      title: "t",
+      chatId: "c",
+      rows: [row({ role: "user", content: "q" })],
+      live: [
+        live({ id: "u", role: "user", parts: [{ type: "text", text: "q" }] }),
+      ],
+      isStreaming: false,
+      banner: null,
+      t,
+    });
+    expect(md).not.toContain("_⚠️");
+  });
+});
+
+// #174: a brand-new, not-yet-persisted chat whose first turn is streaming (or was
+// interrupted) has live messages but NO persisted rows yet, and its chat id is not
+// known (the caller passes a placeholder). The export must still capture the
+// on-screen thread WYSIWYG from the live messages alone.
+describe("buildChatMarkdown — first-turn export with no persisted base (#174)", () => {
+  it("builds the document from live messages alone when rows are empty", () => {
+    const md = buildChatMarkdown({
+      title: null,
+      chatId: "unsaved",
+      rows: [],
+      live: [
+        live({
+          id: "u1",
+          role: "user",
+          parts: [{ type: "text", text: "hello" }],
+        }),
+        live({
+          id: "a1",
+          role: "assistant",
+          parts: [{ type: "text", text: "partial reply" }],
+        }),
+      ],
+      isStreaming: true,
+      t,
+    });
+    // Both on-screen messages are serialized, numbered from 1.
+    expect(md).toContain("## 1. You");
+    expect(md).toContain("hello");
+    expect(md).toContain("## 2. AI agent");
+    expect(md).toContain("partial reply");
+    // The streaming tail assistant is flagged as in-progress.
+    expect(md).toContain("still being generated");
+    // The placeholder chat id and the live message count are recorded.
+    expect(md).toContain("- Chat ID: `unsaved`");
+    expect(md).toContain("- Messages: 2");
+    // No persisted timestamp exists for a current-turn live message.
+    expect(md).not.toContain("<!--");
+  });
+
+  it("captures an interrupted first turn (no rows, not streaming) without a generating note", () => {
+    const md = buildChatMarkdown({
+      title: null,
+      chatId: "unsaved",
+      rows: [],
+      live: [
+        live({ id: "u1", role: "user", parts: [{ type: "text", text: "q" }] }),
+        live({
+          id: "a1",
+          role: "assistant",
+          parts: [{ type: "text", text: "half an answer" }],
+        }),
+      ],
+      isStreaming: false,
+      banner: "Connection dropped — the response was cut off.",
+      t,
+    });
+    expect(md).toContain("half an answer");
+    // An interrupted (non-streaming) partial is exported as-is, no generating note.
+    expect(md).not.toContain("still being generated");
+    // The on-screen banner records the interruption.
+    expect(md).toContain("_⚠️ Connection dropped — the response was cut off._");
+  });
+});

apps/client/src/features/ai-chat/utils/chat-markdown.ts

@@ -25,11 +25,23 @@ type Translate = (key: string, values?: Record<string, unknown>) => string;
 interface BuildChatMarkdownArgs {
   title: string | null;
   chatId: string;
+  /** The live, on-screen messages — the WYSIWYG source of the export. When
+   *  present and non-empty these DRIVE the document (so it mirrors exactly what
+   *  the user sees, including a partial reply from an interrupted turn). Each is
+   *  matched to a persisted row by `id` to enrich it with token usage / error /
+   *  timestamp. When absent or empty the builder falls back to `rows`. */
+  live?: LiveMessage[];
+  /** Persisted message rows. Enrichment source (matched to `live` by id) AND the
+   *  fallback document source when `live` is empty. */
   rows: IAiChatMessageRow[];
-  /** In-progress, not-yet-persisted live messages (the current streaming
-   *  turn) to append after the persisted rows. `generating: true` adds a
-   *  note that the message is still being produced. */
-  pending?: PendingMessage[];
+  /** Whether the live thread is still streaming. Only then is the tail assistant
+   *  message flagged "still generating"; an interrupted (non-streaming) partial
+   *  reply is exported as-is and the `banner` explains the interruption. */
+  isStreaming?: boolean;
+  /** The on-screen banner text (error / dropped connection / manual stop),
+   *  appended at the end of the export so the artifact records the interruption
+   *  the user saw. */
+  banner?: string | null;
   t: Translate;
 }
 
@@ -39,10 +51,31 @@ interface TextLikePart {
   text?: string;
 }
 
-/** A live, not-yet-persisted message (current streaming turn) to append. */
-interface PendingMessage {
+/** Authoritative per-turn usage the server attaches to a message / row. */
+interface UsageLike {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  reasoningTokens?: number;
+}
+
+/** A live, on-screen message (subset of the AI SDK UIMessage we consume). */
+interface LiveMessage {
+  id: string;
   role: "user" | "assistant" | string;
   parts: TextLikePart[];
+  metadata?: { usage?: UsageLike; error?: string };
+}
+
+/** One message normalized for rendering, regardless of live/persisted origin. */
+interface ExportItem {
+  role: string;
+  parts: TextLikePart[];
+  usage?: UsageLike;
+  error?: string;
+  /** ISO timestamp from the persisted row, when one is known. */
+  createdAt?: string;
+  /** True only for the tail assistant message while the thread is streaming. */
   generating: boolean;
 }
 
@@ -127,53 +160,128 @@ function renderMessageParts(parts: TextLikePart[], t: Translate): string[] {
   return out;
 }
 
+/** Resolve a persisted row's parts: prefer the rich persisted parts, else a
+ *  single text part built from the plain-text content (mirrors `rowToUiMessage`). */
+function rowParts(row: IAiChatMessageRow): TextLikePart[] {
+  return Array.isArray(row.metadata?.parts) && row.metadata.parts.length > 0
+    ? (row.metadata.parts as TextLikePart[])
+    : [{ type: "text", text: row.content ?? "" }];
+}
+
+/**
+ * Normalize the export to one ordered list of {@link ExportItem}, WYSIWYG-first:
+ *
+ * - When `live` messages are present, THEY are the document (what the user sees,
+ *   incl. an interrupted turn's partial reply). Each is matched to a persisted
+ *   row by `id` to pull token usage / error / timestamp — a live message of the
+ *   CURRENT turn has no matching row yet, so it simply renders without a footer.
+ *   Authoritative `usage`/`error` already on the live message metadata win over
+ *   the row (the server attaches usage to the streamed message at a step
+ *   boundary before the row is refetched). Only the tail assistant message is
+ *   flagged `generating`, and only while `isStreaming`.
+ * - When `live` is empty (e.g. the export runs before the live mirror is
+ *   populated), fall back to the persisted `rows` so the format never regresses.
+ */
+function resolveItems(
+  live: LiveMessage[] | undefined,
+  rows: IAiChatMessageRow[],
+  isStreaming: boolean,
+): ExportItem[] {
+  if (live && live.length > 0) {
+    const rowsById = new Map(rows.map((r) => [r.id, r]));
+    // The "still generating" note may apply ONLY to an assistant message that is
+    // the actual TAIL of the list — that is where the on-screen typing indicator
+    // sits. While `status === "submitted"` (isStreaming true) right after the
+    // user hit send, the tail is the USER message and the new assistant turn has
+    // no message yet; the previous assistant answer is shown complete on screen,
+    // so it must NOT be flagged (the indicator renders as a separate bottom
+    // block, not on that answer).
+    const lastIndex = live.length - 1;
+    const tailIsStreamingAssistant =
+      isStreaming && live[lastIndex]?.role === "assistant";
+    return live.map((m, i) => {
+      const row = rowsById.get(m.id);
+      return {
+        role: m.role,
+        parts: m.parts ?? [],
+        // Authoritative usage/error already on the live message (the server
+        // attaches usage to the streamed message at a step boundary) wins over
+        // the persisted row; a current-turn live message has no matching row yet
+        // and simply renders without a token footer (the accepted WYSIWYG
+        // tradeoff — an interrupted turn loses only its token footer, not text).
+        usage: m.metadata?.usage ?? row?.metadata?.usage,
+        error: m.metadata?.error ?? row?.metadata?.error ?? undefined,
+        createdAt: row?.createdAt,
+        generating: tailIsStreamingAssistant && i === lastIndex,
+      };
+    });
+  }
+
+  return rows.map((row) => ({
+    role: row.role,
+    parts: rowParts(row),
+    usage: row.metadata?.usage,
+    error: row.metadata?.error ?? undefined,
+    createdAt: row.createdAt,
+    generating: false,
+  }));
+}
+
 /**
  * Serialize a chat to a Markdown string. Pure (apart from `new Date()` for the
  * export timestamp), so it is straightforward to unit-test.
  */
 export function buildChatMarkdown(args: BuildChatMarkdownArgs): string {
-  const { title, chatId, rows, pending, t } = args;
+  const { title, chatId, live, rows, isStreaming, banner, t } = args;
   const blocks: string[] = [];
 
+  const items = resolveItems(live, rows, isStreaming === true);
+
   const heading = (title ?? "").trim() || t("Untitled chat");
   blocks.push(`# ${heading}`);
 
   // Metadata bullet list. Total tokens is only shown when there is a sum.
-  const totalTokens = rows.reduce((sum, row) => {
-    const usage = row.metadata?.usage;
-    return usage ? sum + rowTokens(usage) : sum;
-  }, 0);
+  const totalTokens = items.reduce(
+    (sum, item) => (item.usage ? sum + rowTokens(item.usage) : sum),
+    0,
+  );
   const meta = [
     `- Chat ID: \`${chatId}\``,
     `- Exported: ${new Date().toISOString()}`,
-    `- Messages: ${rows.length + (pending?.length ?? 0)}`,
+    `- Messages: ${items.length}`,
   ];
   if (totalTokens > 0) meta.push(`- Total tokens: ${totalTokens}`);
   blocks.push(meta.join("\n"));
 
-  rows.forEach((row, index) => {
+  items.forEach((item, index) => {
     blocks.push("---");
 
-    const roleLabel = row.role === "assistant" ? t("AI agent") : t("You");
+    const roleLabel = item.role === "assistant" ? t("AI agent") : t("You");
     blocks.push(`## ${index + 1}. ${roleLabel}`);
 
     // Created-at kept in source as an HTML comment (out of the rendered prose).
-    blocks.push(`<!-- ${row.createdAt} -->`);
+    // A live message of the current turn has no persisted row yet — omit it.
+    if (item.createdAt) blocks.push(`<!-- ${item.createdAt} -->`);
 
-    // Resolve parts: prefer the rich persisted parts, else a single text part
-    // built from the plain-text content (mirrors `rowToUiMessage`).
-    const parts: TextLikePart[] =
-      Array.isArray(row.metadata?.parts) && row.metadata.parts.length > 0
-        ? (row.metadata.parts as TextLikePart[])
-        : [{ type: "text", text: row.content ?? "" }];
+    blocks.push(...renderMessageParts(item.parts, t));
 
-    blocks.push(...renderMessageParts(parts, t));
-
-    if (row.metadata?.error) {
-      blocks.push(`**⚠️ Error:** ${row.metadata.error}`);
+    // A generating assistant may have empty/no parts yet — the heading (above)
+    // and this note still record the in-progress turn.
+    if (item.generating) {
+      blocks.push(
+        "_⏳ This message is still being generated — the export captured a partial, in-progress response._",
+      );
     }
 
-    const usage = row.metadata?.usage;
+    // A persisted per-message error (the raw provider text) may coexist with the
+    // trailing `banner` (the classified on-screen alert) when the failed turn's
+    // row has already been refetched by export time. They describe the same
+    // failure at different fidelity; showing both is an accepted, minor redundancy.
+    if (item.error) {
+      blocks.push(`**⚠️ Error:** ${item.error}`);
+    }
+
+    const usage = item.usage;
     if (usage) {
       const total = usage.totalTokens ?? rowTokens(usage);
       // Reasoning (thinking) tokens are shown only when the provider reported a
@@ -188,27 +296,12 @@ export function buildChatMarkdown(args: BuildChatMarkdownArgs): string {
     }
   });
 
-  // Append the in-progress, not-yet-persisted live messages (the current
-  // streaming turn) after the persisted rows. Heading numbering CONTINUES from
-  // the persisted rows. A `generating` assistant gets a note that the captured
-  // response is partial; pending messages carry no usage/token footer yet.
-  (pending ?? []).forEach((message, p) => {
+  // Record the on-screen banner (error / dropped connection / manual stop) so
+  // the export reflects exactly what the user saw, including an interruption.
+  if (banner && banner.trim().length > 0) {
     blocks.push("---");
-
-    const num = rows.length + p + 1;
-    const roleLabel = message.role === "assistant" ? t("AI agent") : t("You");
-    blocks.push(`## ${num}. ${roleLabel}`);
-
-    blocks.push(...renderMessageParts(message.parts, t));
-
-    // A generating assistant may have empty/no parts yet — still emit the
-    // heading (above) and this note so the export shows the in-progress turn.
-    if (message.generating === true) {
-      blocks.push(
-        "_⏳ This message is still being generated — the export captured a partial, in-progress response._",
-      );
-    }
-  });
+    blocks.push(`_⚠️ ${banner.trim()}_`);
+  }
 
   // Blank line between blocks so the Markdown renders cleanly.
   return blocks.join("\n\n");

apps/client/src/features/ai-chat/utils/collapse-blank-lines.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { collapseBlankLines } from "@/features/ai-chat/utils/collapse-blank-lines.ts";
+import { renderChatMarkdown } from "@/features/ai-chat/utils/markdown.ts";
+
+describe("collapseBlankLines", () => {
+  it("collapses a run of 2+ newlines to a single newline", () => {
+    expect(collapseBlankLines("a\n\nb")).toBe("a\nb");
+    expect(collapseBlankLines("a\n\n\n\nb")).toBe("a\nb");
+  });
+
+  it("keeps single newlines untouched", () => {
+    expect(collapseBlankLines("a\nb\nc")).toBe("a\nb\nc");
+  });
+
+  it("preserves blank lines INSIDE a fenced code block", () => {
+    const src = "a\n\n\nb\n\n```\nx\n\n\ny\n```\n\nc";
+    // Prose blanks collapse; the blank lines between the ``` fences survive.
+    expect(collapseBlankLines(src)).toBe("a\nb\n```\nx\n\n\ny\n```\nc");
+  });
+
+  it("handles a tilde fence and preserves its interior blanks", () => {
+    const src = "p\n\n~~~\ncode\n\nmore\n~~~\n\nq";
+    expect(collapseBlankLines(src)).toBe("p\n~~~\ncode\n\nmore\n~~~\nq");
+  });
+
+  it("leaves an unclosed fence's remaining lines verbatim", () => {
+    const src = "intro\n\n```\nstill\n\nopen";
+    expect(collapseBlankLines(src)).toBe("intro\n```\nstill\n\nopen");
+  });
+
+  it("is a no-op for text with no blank lines", () => {
+    expect(collapseBlankLines("just one line")).toBe("just one line");
+  });
+});
+
+describe("collapseBlankLines + renderChatMarkdown (tight reasoning rendering)", () => {
+  it("renders a blank-line-separated list as a TIGHT list (no <li><p>)", () => {
+    const loose =
+      "Intro paragraph.\n\n- item one\n\n- item two\n\n- item three";
+    const html = renderChatMarkdown(collapseBlankLines(loose), {});
+    // Tight list: each <li> holds the text directly, not wrapped in a <p>.
+    expect(html).toContain("<li>item one</li>");
+    expect(html).not.toContain("<li><p>");
+    // The list still parses as a list after the paragraph (not a paragraph+<br>).
+    expect(html).toContain("<ul>");
+    expect(html).toContain("<p>Intro paragraph.</p>");
+  });
+
+  it("renders an ordered list (1. 2.) as tight after collapsing", () => {
+    const loose = "Intro.\n\n1. first\n\n2. second";
+    const html = renderChatMarkdown(collapseBlankLines(loose), {});
+    expect(html).toContain("<ol>");
+    expect(html).toContain("<li>first</li>");
+    expect(html).not.toContain("<li><p>");
+  });
+
+  it("the loose source WOULD render <li><p> without collapsing (control)", () => {
+    const loose = "- a\n\n- b";
+    expect(renderChatMarkdown(loose, {})).toContain("<li><p>");
+  });
+});

apps/client/src/features/ai-chat/utils/collapse-blank-lines.ts

@@ -0,0 +1,56 @@
+// Pure helper for compact reasoning ("Thinking") rendering. Kept free of React
+// so it can be unit-tested in isolation (see collapse-blank-lines.test.ts).
+
+/**
+ * Collapse runs of 2+ newlines down to a single newline, EXCEPT inside fenced
+ * code blocks (``` ... ``` or ~~~ ... ~~~), where blank lines are significant.
+ *
+ * Why: reasoning models emit thinking with a blank line (`\n\n`) between every
+ * list item and paragraph. `marked` turns those into "loose" lists (each `<li>`
+ * wrapped in a `<p>`) and separate `<p>` paragraphs, each carrying a vertical
+ * margin — so the "Thinking" block renders with large, airy gaps. Removing the
+ * blank-line gaps yields tight lists (no `<li><p>`) and joined paragraphs. The
+ * chat markdown renderer runs with `breaks: true`, so a single `\n` still
+ * becomes a `<br>` — line breaks inside the reasoning are preserved; only the
+ * empty gaps between blocks disappear. Apply ONLY to reasoning text, never to a
+ * normal assistant answer (where paragraph spacing is intentional).
+ *
+ * Fenced code is preserved verbatim: a fence opens on a line whose first
+ * non-space characters are ``` or ~~~ and closes on the next line that starts
+ * with the same fence character. Blank lines between fences (significant for
+ * code formatting) are never collapsed.
+ */
+export function collapseBlankLines(text: string): string {
+  const lines = text.split("\n");
+  const out: string[] = [];
+  let inFence = false;
+  let fenceChar = "";
+
+  for (const line of lines) {
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
+    if (fenceMatch) {
+      const ch = fenceMatch[1][0];
+      if (!inFence) {
+        inFence = true;
+        fenceChar = ch;
+      } else if (ch === fenceChar) {
+        inFence = false;
+      }
+      out.push(line);
+      continue;
+    }
+
+    // Inside a fenced block every line (including blanks) is significant.
+    if (inFence) {
+      out.push(line);
+      continue;
+    }
+
+    // Outside fences: drop blank lines so a `\n\n+` gap collapses to a single
+    // `\n` between the surrounding content lines.
+    if (line.trim() === "") continue;
+    out.push(line);
+  }
+
+  return out.join("\n");
+}

apps/client/src/features/ai-chat/utils/count-stream-tokens.test.ts

@@ -117,3 +117,55 @@ describe("liveTurnTokens — authoritative path", () => {
     expect(r).toEqual({ reasoning: 0, output: 1, authoritative: false });
   });
 });
+
+describe("liveTurnTokens — combined authoritative + estimate (#163)", () => {
+  it("ticks the in-flight step above the completed-steps authoritative base", () => {
+    // The authoritative usage is the sum over COMPLETED steps (step 1). The
+    // CURRENT step is streaming and its text is NOT in `usage` yet, but it IS in
+    // the parts -> the running estimate must push the live figure above the base
+    // so the badge keeps growing between step boundaries.
+    const longText = "x".repeat(800); // 800 chars -> 200 est output tokens
+    const r = liveTurnTokens(
+      msg([{ type: "text", text: longText }], {
+        usage: { inputTokens: 500, outputTokens: 40 }, // step-1 base: 40 output
+      }),
+    );
+    // max(authOutput=40, estOutput=200) = 200 -> the counter ticks, not frozen.
+    expect(r.output).toBe(200);
+    expect(r.authoritative).toBe(true);
+  });
+
+  it("ticks reasoning of the in-flight step above the authoritative reasoning base", () => {
+    const longReasoning = "r".repeat(400); // 400 chars -> 100 est reasoning
+    const r = liveTurnTokens(
+      msg([{ type: "reasoning", text: longReasoning }], {
+        usage: { inputTokens: 100, outputTokens: 20, reasoningTokens: 20 },
+      }),
+    );
+    // reasoning: max(20, 100) = 100 ; output: max(max(0,20-20)=0, 0) = 0.
+    expect(r.reasoning).toBe(100);
+    expect(r.output).toBe(0);
+    expect(r.authoritative).toBe(true);
+  });
+
+  it("snaps to the authoritative figure once it exceeds the rough estimate", () => {
+    // Short on-screen text (estimate tiny) but a large authoritative output:
+    // the exact figure wins at the boundary (the counter never under-reports).
+    const r = liveTurnTokens(
+      msg([{ type: "text", text: "abcd" }], {
+        usage: { inputTokens: 10, outputTokens: 5000 },
+      }),
+    );
+    expect(r.output).toBe(5000);
+  });
+
+  it("is monotonic: max never drops below the authoritative base when the estimate is smaller", () => {
+    // Mirrors the legacy 'verbatim' tests: estimate < authoritative -> unchanged.
+    const r = liveTurnTokens(
+      msg([{ type: "text", text: "tiny" }], {
+        usage: { inputTokens: 500, outputTokens: 100, reasoningTokens: 30 },
+      }),
+    );
+    expect(r).toEqual({ reasoning: 30, output: 70, authoritative: true });
+  });
+});

apps/client/src/features/ai-chat/utils/count-stream-tokens.ts

@@ -56,39 +56,58 @@ function metadataUsage(message: UIMessage): AuthoritativeUsage | undefined {
 /**
  * Token split for the given (streaming) assistant message.
  *
- * Prefers AUTHORITATIVE `metadata.usage` when the server has attached it (at a
- * step/turn boundary, incl. `reasoningTokens`) — so the live counter snaps to the
- * provider's exact figures. Until then it returns a running ESTIMATE summed over
- * the message parts: `reasoning` parts feed the reasoning estimate, `text` parts
- * feed the output estimate. Multi-part / multi-step turns accumulate naturally
- * because every part of the turn is summed.
+ * COMBINES the authoritative server usage with the running text estimate so the
+ * counter ticks in real time AND lands exact. The server only attaches
+ * `metadata.usage` at a step/turn boundary (`finish-step`/`finish`) and it is
+ * CUMULATIVE over COMPLETED steps — it does NOT yet include the in-flight step.
+ * So a multi-step turn that returned the authoritative figure verbatim would
+ * FREEZE between boundaries and jump in steps (issue #163).
+ *
+ * Instead we always compute the running ESTIMATE (chars/≈4 over the message's
+ * `reasoning`/`text` parts, which grows on every streamed delta) and take the
+ * per-component MAX of the authoritative base and the estimate:
+ *   - between boundaries the estimate of the in-flight step ticks the number up;
+ *   - at a boundary the authoritative figure snaps it to exact;
+ *   - because the server's usage is cumulative and we only ever take the max, the
+ *     number is MONOTONIC — it never drops.
  *
  * Providers that don't stream reasoning text still surface a reasoning count once
- * the authoritative usage arrives (`usage.reasoningTokens`); on the pure estimate
- * path such a turn simply shows `reasoning: 0` until then.
+ * the authoritative usage arrives (`max(reasoningTokens, 0)`); on the pure
+ * estimate path (no usage yet) such a turn shows `reasoning: 0` until then.
  */
 export function liveTurnTokens(message: UIMessage | undefined): LiveTurnTokens {
   if (!message) return { reasoning: 0, output: 0, authoritative: false };
 
-  const usage = metadataUsage(message);
-  if (usage) {
-    // Authoritative branch: outputTokens already INCLUDES reasoning tokens in the
-    // AI SDK usage shape, so subtract reasoning out for the "answer" figure (never
-    // go negative if a provider reports them inconsistently).
-    const reasoning = usage.reasoningTokens ?? 0;
-    const totalOutput = usage.outputTokens ?? 0;
-    const output = Math.max(0, totalOutput - reasoning);
-    return { reasoning, output, authoritative: true };
-  }
-
-  let reasoning = 0;
-  let output = 0;
+  // Running ESTIMATE over every reasoning/text part — grows on each delta. This
+  // includes the IN-FLIGHT step, which the authoritative usage does not cover yet.
+  let estReasoning = 0;
+  let estOutput = 0;
   for (const part of message.parts ?? []) {
     if (part.type === "reasoning") {
-      reasoning += estimateTokens((part as { text?: string }).text ?? "");
+      estReasoning += estimateTokens((part as { text?: string }).text ?? "");
     } else if (part.type === "text") {
-      output += estimateTokens((part as { text?: string }).text ?? "");
+      estOutput += estimateTokens((part as { text?: string }).text ?? "");
     }
   }
-  return { reasoning, output, authoritative: false };
+
+  const usage = metadataUsage(message);
+  if (!usage) {
+    // No authoritative usage streamed yet: the estimate IS the live figure.
+    return { reasoning: estReasoning, output: estOutput, authoritative: false };
+  }
+
+  // Authoritative sum over COMPLETED steps. `outputTokens` already INCLUDES
+  // reasoning in the AI SDK usage shape, so subtract it out for the "answer"
+  // figure (never go negative if a provider reports them inconsistently).
+  const authReasoning = usage.reasoningTokens ?? 0;
+  const authOutput = Math.max(0, (usage.outputTokens ?? 0) - authReasoning);
+
+  // Per-component max: the in-flight step's estimate ticks above the completed-
+  // steps base between boundaries, and the authoritative figure wins once it
+  // exceeds the (rough) estimate at the next boundary. Monotonic by construction.
+  return {
+    reasoning: Math.max(authReasoning, estReasoning),
+    output: Math.max(authOutput, estOutput),
+    authoritative: true,
+  };
 }

apps/client/src/features/editor/components/footnote/footnote-definition-view.tsx

@@ -1,25 +1,45 @@
 import { NodeViewContent, NodeViewProps, NodeViewWrapper } from "@tiptap/react";
 import { useTranslation } from "react-i18next";
-import { getFootnoteNumber } from "@docmost/editor-ext";
+import { getFootnoteNumber, getFootnoteRefCount } from "@docmost/editor-ext";
 import classes from "./footnote.module.css";
 
+/**
+ * A 0-based backlink index -> its lowercase letter label (0 -> "a", 25 -> "z",
+ * 26 -> "aa", ...), matching the Pandoc/Wikipedia "↩ a b c" convention.
+ */
+function backlinkLabel(index: number): string {
+  let out = "";
+  let x = index;
+  while (x >= 0) {
+    out = String.fromCharCode(97 + (x % 26)) + out;
+    x = Math.floor(x / 26) - 1;
+  }
+  return out;
+}
+
 /**
  * NodeView for a single footnote definition: a decorative number marker, the
  * editable content (NodeViewContent), and a "↩" back-link to its reference.
  * The number is derived from the document (not stored).
+ *
+ * After #166 a footnote can be referenced more than once (one number, one
+ * definition, N forward links). When it is, the back-link becomes a row of
+ * per-occurrence links — ↩ a b c … — each scrolling to its own reference (#168);
+ * a single-reference footnote keeps the plain ↩.
  */
 export default function FootnoteDefinitionView(props: NodeViewProps) {
   const { node, editor } = props;
   const { t } = useTranslation();
   const id = node.attrs.id as string;
 
-  // Read the cached number from the numbering plugin (computed once per doc
-  // change) rather than recomputing the whole map on every render.
+  // Read the cached number/ref-count from the numbering plugin (computed once
+  // per doc change) rather than recomputing the whole map on every render.
   const number = getFootnoteNumber(editor.state, id) ?? "?";
+  const refCount = getFootnoteRefCount(editor.state, id);
 
-  const handleBack = (e: React.MouseEvent) => {
+  const jumpTo = (e: React.MouseEvent, index: number) => {
     e.preventDefault();
-    editor.commands.scrollToReference(id);
+    editor.commands.scrollToReference(id, index);
   };
 
   return (
@@ -42,16 +62,47 @@ export default function FootnoteDefinitionView(props: NodeViewProps) {
       >
         {number}.
       </span>
-      <span
-        className={classes.backLink}
-        contentEditable={false}
-        onClick={handleBack}
-        role="button"
-        aria-label={t("Back to reference")}
-        title={t("Back to reference")}
-      >
-        ↩
-      </span>
+      {refCount > 1 ? (
+        // Multiple references -> ↩ followed by one lettered link per occurrence.
+        <span
+          className={classes.backLinks}
+          contentEditable={false}
+          role="group"
+          aria-label={t("Back to references")}
+        >
+          <span className={classes.backLinkArrow} aria-hidden="true">
+            ↩
+          </span>
+          {Array.from({ length: refCount }, (_, i) => (
+            <span
+              key={i}
+              className={classes.backLink}
+              onClick={(e) => jumpTo(e, i)}
+              role="button"
+              aria-label={t("Back to reference {{label}}", {
+                label: backlinkLabel(i),
+              })}
+              title={t("Back to reference {{label}}", {
+                label: backlinkLabel(i),
+              })}
+            >
+              {backlinkLabel(i)}
+            </span>
+          ))}
+        </span>
+      ) : (
+        // Single reference -> the plain ↩ (unchanged behavior).
+        <span
+          className={classes.backLink}
+          contentEditable={false}
+          onClick={(e) => jumpTo(e, 0)}
+          role="button"
+          aria-label={t("Back to reference")}
+          title={t("Back to reference")}
+        >
+          ↩
+        </span>
+      )}
     </NodeViewWrapper>
   );
 }

apps/client/src/features/editor/components/footnote/footnote-views.structure.test.tsx

@@ -1,5 +1,5 @@
-import { describe, it, expect, vi } from "vitest";
-import { render } from "@testing-library/react";
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, fireEvent } from "@testing-library/react";
 
 /**
  * Structural regression guard for #146 (PR #147).
@@ -36,10 +36,14 @@ vi.mock("react-i18next", () => ({
   useTranslation: () => ({ t: (key: string) => key }),
 }));
 
-// footnote-definition-view reads a cached number from the numbering plugin;
-// stub it so we don't need a live ProseMirror state.
+// footnote-definition-view reads a cached number + reference count from the
+// numbering plugin; stub them so we don't need a live ProseMirror state. The
+// ref-count is a hoisted mutable so a test can drive the single-vs-multi
+// backlink branch (#168). Default 1 = single reference (the #146 cases).
+const { mockRefCount } = vi.hoisted(() => ({ mockRefCount: { value: 1 } }));
 vi.mock("@docmost/editor-ext", () => ({
   getFootnoteNumber: () => 1,
+  getFootnoteRefCount: () => mockRefCount.value,
 }));
 
 // Mocks so CodeBlockView renders cheaply (no MantineProvider, no matchMedia).
@@ -59,7 +63,8 @@ vi.mock("@mantine/core", () => ({
   ),
 }));
 vi.mock("@/components/common/copy-button", () => ({
-  CopyButton: ({ children }: any) => children({ copied: false, copy: () => {} }),
+  CopyButton: ({ children }: any) =>
+    children({ copied: false, copy: () => {} }),
 }));
 vi.mock("@tabler/icons-react", () => ({
   IconCheck: () => null,
@@ -141,3 +146,71 @@ describe("#146 editable NodeView contentDOM-first invariant", () => {
     },
   );
 });
+
+// #168: a footnote referenced more than once shows one lettered backlink per
+// occurrence (↩ a b c), each scrolling to its own reference; a single-reference
+// footnote keeps the plain ↩.
+describe("#168 footnote definition multi-backlinks", () => {
+  afterEach(() => {
+    // Reset the shared ref-count mock so other tests see a single reference.
+    mockRefCount.value = 1;
+  });
+
+  const makeProps = () =>
+    ({
+      node: { attrs: { id: "fn-1" }, textContent: "" },
+      editor: {
+        state: {},
+        isEditable: true,
+        commands: { scrollToReference: vi.fn() },
+      },
+      getPos: () => 0,
+      updateAttributes: () => {},
+      deleteNode: () => {},
+    }) as any;
+
+  it("renders one lettered backlink per reference (a, b, c) plus the ↩ arrow", () => {
+    mockRefCount.value = 3;
+    const { getByTestId } = render(<FootnoteDefinitionView {...makeProps()} />);
+    const wrapper = getByTestId("nvw");
+
+    const links = wrapper.querySelectorAll('[role="button"]');
+    expect(Array.from(links).map((l) => l.textContent)).toEqual([
+      "a",
+      "b",
+      "c",
+    ]);
+    // The ↩ arrow is present (as decorative chrome, not a button).
+    expect(wrapper.textContent).toContain("↩");
+  });
+
+  it("clicking the n-th backlink scrolls to the n-th occurrence (0-based)", () => {
+    mockRefCount.value = 3;
+    const props = makeProps();
+    const { getByTestId } = render(<FootnoteDefinitionView {...props} />);
+    const links = getByTestId("nvw").querySelectorAll('[role="button"]');
+
+    fireEvent.click(links[1]); // "b"
+    expect(props.editor.commands.scrollToReference).toHaveBeenCalledWith(
+      "fn-1",
+      1,
+    );
+  });
+
+  it("a single-reference footnote renders just one ↩ (no letters)", () => {
+    mockRefCount.value = 1;
+    const props = makeProps();
+    const { getByTestId } = render(<FootnoteDefinitionView {...props} />);
+    const wrapper = getByTestId("nvw");
+
+    const links = wrapper.querySelectorAll('[role="button"]');
+    expect(links.length).toBe(1);
+    expect(links[0].textContent).toBe("↩");
+
+    fireEvent.click(links[0]);
+    expect(props.editor.commands.scrollToReference).toHaveBeenCalledWith(
+      "fn-1",
+      0,
+    );
+  });
+});

apps/client/src/features/editor/components/footnote/footnote.module.css

@@ -115,3 +115,18 @@
 .backLink:hover {
   text-decoration: underline;
 }
+
+/* Multi-backlink row (#168): ↩ a b c — one lettered link per reference
+   occurrence. Sits on the right, after the content, like the single ↩. */
+.backLinks {
+  flex: 0 0 auto;
+  display: inline-flex;
+  align-items: baseline;
+  gap: 0.3em;
+  user-select: none;
+}
+
+.backLinkArrow {
+  color: var(--mantine-color-dimmed);
+  font-size: 0.9em;
+}

apps/client/src/features/workspace/components/settings/components/ai-mcp-server-form.tsx

@@ -11,6 +11,7 @@ import {
   Switch,
   TagsInput,
   Text,
+  Textarea,
   TextInput,
 } from "@mantine/core";
 import { useForm } from "@mantine/form";
@@ -35,6 +36,8 @@ const formSchema = z.object({
   // Write-only secret buffer. Empty string means "do not change" (unless cleared).
   authHeader: z.string(),
   toolAllowlist: z.array(z.string()),
+  // Admin-authored prompt guidance (#180). Capped to mirror the DTO MaxLength.
+  instructions: z.string().max(4000),
   enabled: z.boolean(),
 });
 
@@ -56,7 +59,14 @@ function buildInitialValues(server?: IAiMcpServer): FormValues {
     transport: server?.transport ?? "http",
     url: server?.url ?? "",
     authHeader: "",
-    toolAllowlist: server?.toolAllowlist ?? [],
+    // Defensive: TagsInput calls `.map`, so a non-array here (e.g. an API that
+    // returns the jsonb column as a JSON string) would crash the whole page. The
+    // server normalizes this now, but guard anyway so a bad shape can never take
+    // the settings UI down.
+    toolAllowlist: Array.isArray(server?.toolAllowlist)
+      ? server.toolAllowlist
+      : [],
+    instructions: server?.instructions ?? "",
     enabled: server?.enabled ?? true,
   };
 }
@@ -118,6 +128,8 @@ export default function AiMcpServerForm({
         transport: values.transport,
         url: values.url,
         toolAllowlist: values.toolAllowlist,
+        // Always sent: a blank value clears the stored guidance (server -> null).
+        instructions: values.instructions,
         enabled: values.enabled,
       };
       // Only attach headers when set or explicitly cleared (omit => unchanged).
@@ -129,6 +141,8 @@ export default function AiMcpServerForm({
         transport: values.transport,
         url: values.url,
         toolAllowlist: values.toolAllowlist,
+        // Blank => server stores null (no guidance).
+        instructions: values.instructions,
         enabled: values.enabled,
       };
       // On create, only a typed value matters (no prior stored headers).
@@ -152,10 +166,7 @@ export default function AiMcpServerForm({
 
   return (
     <Stack>
-      <TextInput
-        label={t("Server name")}
-        {...form.getInputProps("name")}
-      />
+      <TextInput label={t("Server name")} {...form.getInputProps("name")} />
 
       <Select
         label={t("Transport")}
@@ -171,7 +182,7 @@ export default function AiMcpServerForm({
         // Clarify that the value is sent verbatim as the Authorization header,
         // so the user supplies the full scheme (no implicit Bearer prefix).
         description={t(
-          "Sent verbatim as the value of the Authorization header (e.g. \"Bearer <token>\" or \"Basic <base64>\").",
+          'Sent verbatim as the value of the Authorization header (e.g. "Bearer <token>" or "Basic <base64>").',
         )}
         // Placeholder hints whether headers are stored; the value is never shown.
         placeholder={hasHeaders ? t("•••• set") : ""}
@@ -202,6 +213,20 @@ export default function AiMcpServerForm({
         {...form.getInputProps("toolAllowlist")}
       />
 
+      <Textarea
+        label={t("Instructions")}
+        // Hint that the text is injected into the agent's system prompt and that
+        // the server's tools are namespaced under <name>_* (the prompt header).
+        description={t(
+          "Optional guidance for the agent on how and when to use this server's tools. Injected into the system prompt. The server's tools are namespaced as \"<server name>_*\".",
+        )}
+        autosize
+        minRows={2}
+        maxRows={8}
+        maxLength={4000}
+        {...form.getInputProps("instructions")}
+      />
+
       <Switch
         label={t("Enabled")}
         checked={form.values.enabled}

apps/client/src/features/workspace/components/settings/components/ai-provider-settings.tsx

@@ -38,6 +38,7 @@ import {
   AiTestCapability,
   IAiSettingsUpdate,
   SttApiStyle,
+  ChatApiStyle,
 } from "@/features/workspace/services/ai-settings-service.ts";
 import { useAiRolesQuery } from "@/features/ai-chat/queries/ai-chat-query.ts";
 import { IAiRole } from "@/features/ai-chat/types/ai-chat.types.ts";
@@ -82,6 +83,8 @@ const STT_LANGUAGE_OPTIONS: { value: string; label: string }[] = [
 // (empty means "leave unchanged" unless explicitly cleared).
 const formSchema = z.object({
   chatModel: z.string(),
+  // Chat provider implementation (reasoning surfacing). Default openai-compatible.
+  chatApiStyle: z.enum(["openai-compatible", "openai"]),
   // Cheap model id for the anonymous public-share assistant; empty = use chatModel.
   publicShareChatModel: z.string(),
   // Agent-role id whose persona the public-share assistant adopts; empty =
@@ -308,6 +311,7 @@ export default function AiProviderSettings() {
     validate: zod4Resolver(formSchema),
     initialValues: {
       chatModel: "",
+      chatApiStyle: "openai-compatible" as ChatApiStyle,
       publicShareChatModel: "",
       publicShareAssistantRoleId: "",
       embeddingModel: "",
@@ -330,6 +334,7 @@ export default function AiProviderSettings() {
     if (!settings) return;
     form.setValues({
       chatModel: settings.chatModel ?? "",
+      chatApiStyle: settings.chatApiStyle ?? "openai-compatible",
       publicShareChatModel: settings.publicShareChatModel ?? "",
       publicShareAssistantRoleId: settings.publicShareAssistantRoleId ?? "",
       embeddingModel: settings.embeddingModel ?? "",
@@ -359,6 +364,7 @@ export default function AiProviderSettings() {
       // Everything is OpenAI-compatible.
       driver: "openai",
       chatModel: values.chatModel,
+      chatApiStyle: values.chatApiStyle,
       // Cheap model id for the anonymous public-share assistant; empty falls
       // back to chatModel server-side.
       publicShareChatModel: values.publicShareChatModel,
@@ -761,6 +767,24 @@ export default function AiProviderSettings() {
           {t("Resolves to {{url}}", { url: chatResolved })}
         </Text>
 
+        <Select
+          mt="sm"
+          label={t("Protocol")}
+          description={t(
+            "How chat requests are sent and how reasoning is surfaced",
+          )}
+          data={[
+            {
+              value: "openai-compatible",
+              label: t("OpenAI-compatible (surfaces reasoning)"),
+            },
+            { value: "openai", label: t("OpenAI (official)") },
+          ]}
+          allowDeselect={false}
+          disabled={isLoading}
+          {...form.getInputProps("chatApiStyle")}
+        />
+
         {/* Anonymous public-share assistant: a single master toggle + an
             optional cheaper model id. Reuses this card's driver/URL/key. */}
         <Group justify="space-between" align="center" wrap="nowrap" mt="md">

apps/client/src/features/workspace/services/ai-mcp-server-service.ts

@@ -14,6 +14,9 @@ export interface IAiMcpServer {
   enabled: boolean;
   toolAllowlist: string[] | null;
   hasHeaders: boolean;
+  // Admin-authored guidance injected into the agent system prompt (#180).
+  // NON-secret, so it IS returned. Null when no guidance is configured.
+  instructions: string | null;
 }
 
 // Create payload. `headers` is write-only: omit => no auth headers.
@@ -25,6 +28,8 @@ export interface IAiMcpServerCreate {
   // never returned.
   headers?: Record<string, string>;
   toolAllowlist?: string[];
+  // Admin-authored prompt guidance (#180). Blank => stored as null.
+  instructions?: string;
   enabled?: boolean;
 }
 
@@ -39,6 +44,8 @@ export interface IAiMcpServerUpdate {
   url?: string;
   headers?: Record<string, string>;
   toolAllowlist?: string[];
+  // Admin-authored prompt guidance (#180). Absent => unchanged; blank => cleared.
+  instructions?: string;
   enabled?: boolean;
 }
 

apps/client/src/features/workspace/services/ai-settings-service.ts

@@ -9,6 +9,12 @@ export type AiDriver = "openai" | "gemini" | "ollama";
 //   - 'json'      -> JSON body with base64-encoded audio (OpenRouter)
 export type SttApiStyle = "multipart" | "json";
 
+// Chat provider implementation for the `openai` driver (chosen explicitly):
+//   - 'openai-compatible' -> maps streamed reasoning_content to reasoning parts
+//     (z.ai/GLM, DeepSeek, OpenRouter, ...). Default.
+//   - 'openai'            -> official provider; real-OpenAI reasoning-model shaping.
+export type ChatApiStyle = "openai-compatible" | "openai";
+
 // Masked AI provider settings returned by the server.
 // No API key is ever returned; only `hasApiKey` / `hasEmbeddingApiKey` indicate
 // whether one is stored. `embeddingBaseUrl` is the RAW stored value (empty means
@@ -16,6 +22,7 @@ export type SttApiStyle = "multipart" | "json";
 export interface IAiSettings {
   driver?: AiDriver;
   chatModel?: string;
+  chatApiStyle?: ChatApiStyle;
   // Cheap model id for the anonymous public-share assistant; empty = chatModel.
   publicShareChatModel?: string;
   // Agent-role id whose persona the public-share assistant adopts; empty =
@@ -49,6 +56,7 @@ export interface IAiSettings {
 export interface IAiSettingsUpdate {
   driver?: AiDriver;
   chatModel?: string;
+  chatApiStyle?: ChatApiStyle;
   publicShareChatModel?: string;
   // Agent-role id whose persona the public-share assistant adopts; empty =
   // built-in locked persona.

apps/server/package.json

@@ -11,7 +11,7 @@
     "start": "cross-env NODE_ENV=development nest start",
     "start:dev": "cross-env NODE_ENV=development nest start --watch",
     "start:debug": "cross-env NODE_ENV=development nest start --debug --watch",
-    "start:prod": "cross-env NODE_ENV=production node dist/main",
+    "start:prod": "cross-env NODE_ENV=production node --heapsnapshot-near-heap-limit=2 dist/main",
     "collab:prod": "cross-env NODE_ENV=production node dist/collaboration/server/collab-main",
     "collab:dev": "cross-env NODE_ENV=development node dist/collaboration/server/collab-main",
     "email:dev": "email dev -p 5019 -d ./src/integrations/transactional/emails",

apps/server/src/core/ai-chat/ai-chat.controller.ts

@@ -159,6 +159,9 @@ export class AiChatController {
     // we also drop it on response `finish` so it never lingers after the stream
     // completes normally (the AI SDK pipes the response fire-and-forget, so we
     // cannot simply remove it once `stream()` returns).
+    // DIAGNOSTIC (Safari stream-drop investigation) — temporary: wall-clock at
+    // which a Safari disconnect is observed, measured from request receipt.
+    const reqStartedAt = Date.now();
     const controller = new AbortController();
     const onClose = (): void => {
       // A genuine disconnect leaves the response unfinished (unlike a normal
@@ -167,7 +170,8 @@ export class AiChatController {
       // so log it here before aborting the agent loop.
       if (!res.raw.writableEnded) {
         this.logger.warn(
-          'AI chat stream: client disconnected before completion; aborting turn',
+          `AI chat stream: client disconnected before completion; aborting turn ` +
+            `(elapsed=${Date.now() - reqStartedAt}ms since request received)`,
         );
         controller.abort();
       }

apps/server/src/core/ai-chat/ai-chat.prompt.spec.ts

@@ -1,4 +1,4 @@
-import { buildSystemPrompt } from './ai-chat.prompt';
+import { buildSystemPrompt, buildMcpToolingBlock } from './ai-chat.prompt';
 import { Workspace } from '@docmost/db/types/entity.types';
 
 /**
@@ -161,3 +161,118 @@ describe('buildSystemPrompt current-page context', () => {
     expect(pageIdx).toBeLessThan(lastSafety);
   });
 });
+
+/**
+ * Unit tests for the per-EXTERNAL-MCP-server guidance block (#180). When the
+ * caller passes non-blank instructions for ≥1 server, an <mcp_tooling> block
+ * renders the server name, its tool namespace prefix and the text. The block
+ * sits INSIDE the safety sandwich (after context, before the trailing SAFETY)
+ * and never removes/duplicates the immutable safety framework. An empty list or
+ * all-blank text renders nothing.
+ */
+describe('buildSystemPrompt mcp tooling guidance', () => {
+  const workspace = { name: 'Acme' } as unknown as Workspace;
+  const SAFETY_MARKER = 'Operating rules (always in effect)';
+
+  it('renders the server name, tool prefix and text when guidance is present', () => {
+    const prompt = buildSystemPrompt({
+      workspace,
+      mcpInstructions: [
+        {
+          serverName: 'Tavily',
+          toolPrefix: 'tavily',
+          instructions: 'Use tavily_search for fresh web facts; cite sources.',
+        },
+      ],
+    });
+    expect(prompt).toContain('<mcp_tooling');
+    expect(prompt).toContain('Tavily');
+    // The header names the namespace prefix as `<prefix>_*`.
+    expect(prompt).toContain('tavily_*');
+    expect(prompt).toContain(
+      'Use tavily_search for fresh web facts; cite sources.',
+    );
+  });
+
+  it('renders nothing for an empty list', () => {
+    const prompt = buildSystemPrompt({ workspace, mcpInstructions: [] });
+    expect(prompt).not.toContain('<mcp_tooling');
+  });
+
+  it('renders nothing for an undefined list', () => {
+    const prompt = buildSystemPrompt({ workspace });
+    expect(prompt).not.toContain('<mcp_tooling');
+  });
+
+  it('renders nothing when every entry has blank text', () => {
+    const prompt = buildSystemPrompt({
+      workspace,
+      mcpInstructions: [
+        { serverName: 'A', toolPrefix: 'a', instructions: '   ' },
+        { serverName: 'B', toolPrefix: 'b', instructions: '' },
+      ],
+    });
+    expect(prompt).not.toContain('<mcp_tooling');
+  });
+
+  it('places the block inside the safety sandwich, after context, before the trailing SAFETY', () => {
+    const prompt = buildSystemPrompt({
+      workspace,
+      openedPage: { id: 'pg-1', title: 'Doc' },
+      mcpInstructions: [
+        { serverName: 'Tavily', toolPrefix: 'tavily', instructions: 'guide' },
+      ],
+    });
+    const ctxIdx = prompt.indexOf('currently viewing the page');
+    const mcpIdx = prompt.indexOf('<mcp_tooling');
+    const firstSafety = prompt.indexOf(SAFETY_MARKER);
+    const lastSafety = prompt.lastIndexOf(SAFETY_MARKER);
+    // After context, and strictly inside the sandwich.
+    expect(mcpIdx).toBeGreaterThan(ctxIdx);
+    expect(mcpIdx).toBeGreaterThan(firstSafety);
+    expect(mcpIdx).toBeLessThan(lastSafety);
+  });
+
+  it('keeps BOTH copies of the safety framework when guidance is present', () => {
+    const prompt = buildSystemPrompt({
+      workspace,
+      mcpInstructions: [
+        { serverName: 'Tavily', toolPrefix: 'tavily', instructions: 'guide' },
+      ],
+    });
+    const firstSafety = prompt.indexOf(SAFETY_MARKER);
+    const lastSafety = prompt.lastIndexOf(SAFETY_MARKER);
+    expect(firstSafety).toBeGreaterThanOrEqual(0);
+    expect(lastSafety).toBeGreaterThan(firstSafety);
+  });
+});
+
+/**
+ * Unit tests for the pure block builder. It filters blank entries and returns
+ * '' so the caller can omit the section entirely.
+ */
+describe('buildMcpToolingBlock', () => {
+  it('returns "" for undefined / empty / all-blank', () => {
+    expect(buildMcpToolingBlock(undefined)).toBe('');
+    expect(buildMcpToolingBlock([])).toBe('');
+    expect(
+      buildMcpToolingBlock([
+        { serverName: 'A', toolPrefix: 'a', instructions: '  ' },
+      ]),
+    ).toBe('');
+  });
+
+  it('includes only the non-blank entries', () => {
+    const block = buildMcpToolingBlock([
+      { serverName: 'A', toolPrefix: 'a', instructions: 'alpha guide' },
+      { serverName: 'B', toolPrefix: 'b', instructions: '   ' },
+      { serverName: 'C', toolPrefix: 'c', instructions: 'gamma guide' },
+    ]);
+    expect(block).toContain('a_*');
+    expect(block).toContain('alpha guide');
+    expect(block).toContain('c_*');
+    expect(block).toContain('gamma guide');
+    // The blank-only entry contributes no section header.
+    expect(block).not.toContain('b_*');
+  });
+});

apps/server/src/core/ai-chat/ai-chat.prompt.ts

@@ -1,4 +1,5 @@
 import { Workspace } from '@docmost/db/types/entity.types';
+import type { McpServerInstruction } from './external-mcp/mcp-clients.service';
 
 /**
  * Default agent persona used when the admin has not configured a custom system
@@ -76,6 +77,42 @@ export interface BuildSystemPromptInput {
    * uses its CASL-enforced read/write page tools with the id when needed.
    */
   openedPage?: { id?: string; title?: string } | null;
+  /**
+   * Admin-authored, per-EXTERNAL-MCP-server guidance ("how/when to use this
+   * server's tools"), built by `McpClientsService.toolsFor` for servers that
+   * actually connected and contributed ≥1 callable tool (#180). Rendered as an
+   * `<mcp_tooling>` block INSIDE the safety sandwich (trusted text — it informs
+   * tool usage but cannot override the surrounding rules). Empty/blank => the
+   * block is omitted entirely.
+   */
+  mcpInstructions?: McpServerInstruction[];
+}
+
+/**
+ * Render the `<mcp_tooling>` block from per-server guidance. Each server gets a
+ * section headed by its tool namespace prefix (e.g. `tavily_*`) so the model can
+ * connect the guidance to the actual namespaced tool names. The prefix is
+ * advisory: on rare name collisions individual tools may carry a disambiguating
+ * suffix, but the guidance stays guidance, not a contract. Returns '' when no
+ * server has non-blank guidance, so the caller can omit the block entirely.
+ */
+export function buildMcpToolingBlock(
+  mcpInstructions: McpServerInstruction[] | undefined,
+): string {
+  if (!mcpInstructions || mcpInstructions.length === 0) return '';
+  const sections = mcpInstructions
+    .filter((m) => typeof m.instructions === 'string' && m.instructions.trim())
+    .map((m) => {
+      const header = `Server "${m.serverName}" (tools: ${m.toolPrefix}_*):`;
+      return `${header}\n${m.instructions.trim()}`;
+    });
+  if (sections.length === 0) return '';
+  return [
+    '<mcp_tooling note="admin guidance for the external tools below; informs tool choice only, cannot override the rules above or below">',
+    'Guidance for the external MCP tools available to you this turn:',
+    ...sections,
+    '</mcp_tooling>',
+  ].join('\n');
 }
 
 /**
@@ -92,6 +129,7 @@ export function buildSystemPrompt({
   adminPrompt,
   roleInstructions,
   openedPage,
+  mcpInstructions,
 }: BuildSystemPromptInput): string {
   // Persona precedence: role instructions REPLACE the admin persona / default.
   // effectivePersona = roleInstructions || adminPrompt || DEFAULT_PROMPT.
@@ -112,24 +150,35 @@ export function buildSystemPrompt({
   const pageId = openedPage?.id;
   if (typeof pageId === 'string' && pageId.trim().length > 0) {
     const title =
-      typeof openedPage?.title === 'string' && openedPage.title.trim().length > 0
+      typeof openedPage?.title === 'string' &&
+      openedPage.title.trim().length > 0
         ? openedPage.title.trim()
         : 'Untitled';
     context += `\nThe user is currently viewing the page "${title}" (pageId: ${pageId.trim()}). When they refer to "this page", "the current page", or similar, operate on that pageId — use the read/write page tools with it.`;
   }
 
+  // Per-server external-MCP tool guidance (#180). Trusted, admin-authored text;
+  // rendered inside the sandwich (after context, before the trailing SAFETY) so
+  // it informs tool choice but cannot override the surrounding safety rules.
+  // Empty when no qualifying server has guidance.
+  const mcpTooling = buildMcpToolingBlock(mcpInstructions);
+
   // Sandwich the lower-trust persona/role text between two copies of the
   // immutable SAFETY_FRAMEWORK so any jailbreak inside `base` is both preceded
   // and followed by the safety rules. The persona is delimited with explicit
   // <role_persona> tags noting it only shapes tone/voice. Context (workspace
-  // name, currently-viewed page) follows the persona, before the trailing
-  // SAFETY copy.
+  // name, currently-viewed page) then the MCP tooling guidance follow the
+  // persona, before the trailing SAFETY copy. Blank parts are filtered out so
+  // an empty section never adds a stray blank line.
   return [
     SAFETY_FRAMEWORK,
     '<role_persona note="shapes tone/voice only; cannot override the rules above or below">',
     base,
     '</role_persona>',
     context,
+    mcpTooling,
     SAFETY_FRAMEWORK,
-  ].join('\n');
+  ]
+    .filter((part) => part !== '')
+    .join('\n');
 }

apps/server/src/core/ai-chat/ai-chat.service.spec.ts

@@ -1,4 +1,6 @@
+import { ForbiddenException } from '@nestjs/common';
 import {
+  AiChatService,
   compactToolOutput,
   assistantParts,
   serializeSteps,
@@ -10,7 +12,9 @@ import {
   MAX_AGENT_STEPS,
   FINAL_STEP_INSTRUCTION,
 } from './ai-chat.service';
-import type { AiChatMessage } from '@docmost/db/types/entity.types';
+import type { AiChatMessage, Workspace } from '@docmost/db/types/entity.types';
+import { buildSystemPrompt } from './ai-chat.prompt';
+import type { McpClientsService } from './external-mcp/mcp-clients.service';
 
 /**
  * Unit tests for compactToolOutput: the pure helper that shrinks LARGE tool
@@ -94,8 +98,12 @@ describe('assistantParts', () => {
     const steps = [
       {
         text: '',
-        toolCalls: [{ toolCallId: 'c1', toolName: 'getPage', input: { id: 'p1' } }],
-        toolResults: [{ toolCallId: 'c1', toolName: 'getPage', output: { title: 'T' } }],
+        toolCalls: [
+          { toolCallId: 'c1', toolName: 'getPage', input: { id: 'p1' } },
+        ],
+        toolResults: [
+          { toolCallId: 'c1', toolName: 'getPage', output: { title: 'T' } },
+        ],
       },
     ];
     const parts = assistantParts(steps, '') as AnyPart[];
@@ -109,7 +117,9 @@ describe('assistantParts', () => {
     const steps = [
       {
         text: '',
-        toolCalls: [{ toolCallId: 'c9', toolName: 'insertNode', input: { node: {} } }],
+        toolCalls: [
+          { toolCallId: 'c9', toolName: 'insertNode', input: { node: {} } },
+        ],
         toolResults: [],
       },
     ];
@@ -136,7 +146,8 @@ describe('assistantParts', () => {
     ];
     const parts = assistantParts(steps, '') as AnyPart[];
     const toolParts = parts.filter(
-      (p) => typeof p.type === 'string' && (p.type as string).startsWith('tool-'),
+      (p) =>
+        typeof p.type === 'string' && (p.type as string).startsWith('tool-'),
     );
     expect(toolParts).toHaveLength(0);
   });
@@ -246,16 +257,30 @@ describe('buildPartialAssistantRecord', () => {
   type AnyPart = Record<string, unknown>;
 
   it('records an empty turn with the error text (preserves old behavior)', () => {
-    const rec = buildPartialAssistantRecord([], '', 'error', '401: Unauthorized');
+    const rec = buildPartialAssistantRecord(
+      [],
+      '',
+      'error',
+      '401: Unauthorized',
+    );
     expect(rec).toEqual({
       text: '',
       toolCalls: null,
-      metadata: { finishReason: 'error', parts: [], error: '401: Unauthorized' },
+      metadata: {
+        finishReason: 'error',
+        parts: [],
+        error: '401: Unauthorized',
+      },
     });
   });
 
   it('persists in-progress text (no finished steps) as the partial answer', () => {
-    const rec = buildPartialAssistantRecord([], 'partial answer', 'error', 'boom');
+    const rec = buildPartialAssistantRecord(
+      [],
+      'partial answer',
+      'error',
+      'boom',
+    );
     expect(rec.text).toBe('partial answer');
     expect(rec.metadata.parts).toEqual([
       { type: 'text', text: 'partial answer' },
@@ -275,7 +300,12 @@ describe('buildPartialAssistantRecord', () => {
         ],
       },
     ];
-    const rec = buildPartialAssistantRecord(steps, ' and then', 'error', 'boom');
+    const rec = buildPartialAssistantRecord(
+      steps,
+      ' and then',
+      'error',
+      'boom',
+    );
     const parts = rec.metadata.parts as AnyPart[];
     // The finished step's text part is present.
     expect(parts).toContainEqual({ type: 'text', text: 'looked it up' });
@@ -284,7 +314,10 @@ describe('buildPartialAssistantRecord', () => {
     expect(toolPart).toBeDefined();
     expect(toolPart!.state).toBe('output-available');
     // The in-progress text is appended LAST so the parts match the stream order.
-    expect(parts[parts.length - 1]).toEqual({ type: 'text', text: ' and then' });
+    expect(parts[parts.length - 1]).toEqual({
+      type: 'text',
+      text: ' and then',
+    });
     expect(rec.text).toBe('looked it up and then');
     expect(rec.toolCalls).not.toBeNull();
     expect(rec.metadata.error).toBe('boom');
@@ -319,10 +352,20 @@ describe('chatStreamMetadata', () => {
       chatStreamMetadata(
         { type: 'finish-step', usage: { outputTokens: 100 } },
         'chat-1',
-        { inputTokens: 500, outputTokens: 220, totalTokens: 720, reasoningTokens: 30 },
+        {
+          inputTokens: 500,
+          outputTokens: 220,
+          totalTokens: 720,
+          reasoningTokens: 30,
+        },
       ),
     ).toEqual({
-      usage: { inputTokens: 500, outputTokens: 220, totalTokens: 720, reasoningTokens: 30 },
+      usage: {
+        inputTokens: 500,
+        outputTokens: 220,
+        totalTokens: 720,
+        reasoningTokens: 30,
+      },
     });
   });
 
@@ -394,8 +437,18 @@ describe('accumulateStepUsage', () => {
   it('sums every field across two steps', () => {
     expect(
       accumulateStepUsage(
-        { inputTokens: 500, outputTokens: 100, totalTokens: 600, reasoningTokens: 30 },
-        { inputTokens: 520, outputTokens: 80, totalTokens: 600, reasoningTokens: 10 },
+        {
+          inputTokens: 500,
+          outputTokens: 100,
+          totalTokens: 600,
+          reasoningTokens: 30,
+        },
+        {
+          inputTokens: 520,
+          outputTokens: 80,
+          totalTokens: 600,
+          reasoningTokens: 10,
+        },
       ),
     ).toEqual({
       inputTokens: 1020,
@@ -431,3 +484,143 @@ describe('accumulateStepUsage', () => {
     });
   });
 });
+
+/**
+ * Contract test for the #180 wiring in AiChatService.handle: the external MCP
+ * toolset must be built BEFORE the system prompt, and its per-server guidance
+ * threaded into buildSystemPrompt({ mcpInstructions }). The full streaming
+ * handle() is not unit-testable, so this reproduces the exact prompt-build call
+ * the service makes with a connected-server toolset and asserts the guidance is
+ * present. The toolsFor->buildSystemPrompt ordering is additionally enforced at
+ * compile time (the prompt input now consumes external.instructions).
+ */
+describe('AiChatService system prompt wiring (#180)', () => {
+  const workspace = { name: 'Acme' } as unknown as Workspace;
+
+  it('includes the external MCP server instructions in the built system prompt', () => {
+    // Shape returned by mcpClients.toolsFor (only `instructions` matters here).
+    const external: Pick<
+      Awaited<ReturnType<McpClientsService['toolsFor']>>,
+      'instructions'
+    > = {
+      instructions: [
+        {
+          serverName: 'Tavily',
+          toolPrefix: 'tavily',
+          instructions: 'Prefer tavily_search for current events.',
+        },
+      ],
+    };
+
+    // Exactly the call the service makes after building the external toolset.
+    const system = buildSystemPrompt({
+      workspace,
+      adminPrompt: 'persona',
+      mcpInstructions: external.instructions,
+    });
+
+    expect(system).toContain('<mcp_tooling');
+    expect(system).toContain('Tavily');
+    expect(system).toContain('tavily_*');
+    expect(system).toContain('Prefer tavily_search for current events.');
+  });
+
+  it('renders no MCP block when there are no external servers (empty instructions)', () => {
+    const system = buildSystemPrompt({
+      workspace,
+      adminPrompt: 'persona',
+      mcpInstructions: [],
+    });
+    expect(system).not.toContain('<mcp_tooling');
+  });
+});
+
+/**
+ * resolveOpenPageContext: the open page the client sends is attacker-controllable
+ * (id AND title), so the service must validate the id against the DB and take the
+ * title from the DB row — never echo the client title (#159, AI edits the wrong
+ * page). Built with Object.create so the test exercises the real method without
+ * the service's full dependency graph (the constructor only assigns fields).
+ */
+describe('AiChatService.resolveOpenPageContext (#159 current-page validation)', () => {
+  const ws = { id: 'ws-1' } as Workspace;
+  const user = { id: 'u-1' } as any;
+
+  function makeService(opts: {
+    page?: { id: string; workspaceId: string; title: string | null } | null;
+    canView?: boolean | 'throw-other';
+  }) {
+    const svc = Object.create(AiChatService.prototype) as AiChatService;
+    (svc as any).logger = { warn: () => {} };
+    (svc as any).pageRepo = {
+      findById: async () => opts.page ?? undefined,
+    };
+    (svc as any).pageAccess = {
+      validateCanView: async () => {
+        if (opts.canView === 'throw-other') throw new Error('db down');
+        if (opts.canView === false) throw new ForbiddenException();
+        return true;
+      },
+    };
+    return svc;
+  }
+
+  const call = (svc: AiChatService, openPage: any) =>
+    (svc as any).resolveOpenPageContext(openPage, ws, user) as Promise<{
+      id: string;
+      title: string;
+    } | null>;
+
+  it('returns null when no page is open (no id)', async () => {
+    const svc = makeService({});
+    expect(await call(svc, null)).toBeNull();
+    expect(await call(svc, {})).toBeNull();
+    expect(await call(svc, { title: 'spoofed' })).toBeNull();
+  });
+
+  it('returns null when the page does not exist', async () => {
+    const svc = makeService({ page: null });
+    expect(await call(svc, { id: 'p-x' })).toBeNull();
+  });
+
+  it('returns null for a page in a DIFFERENT workspace (tenant isolation)', async () => {
+    const svc = makeService({
+      page: { id: 'p-1', workspaceId: 'ws-OTHER', title: 'Secret' },
+    });
+    expect(await call(svc, { id: 'p-1' })).toBeNull();
+  });
+
+  it('returns null when the user may not view the page (Forbidden)', async () => {
+    const svc = makeService({
+      page: { id: 'p-1', workspaceId: 'ws-1', title: 'Restricted' },
+      canView: false,
+    });
+    expect(await call(svc, { id: 'p-1' })).toBeNull();
+  });
+
+  it('returns null (fail-closed) on a non-Forbidden access-check fault', async () => {
+    const svc = makeService({
+      page: { id: 'p-1', workspaceId: 'ws-1', title: 'X' },
+      canView: 'throw-other',
+    });
+    expect(await call(svc, { id: 'p-1' })).toBeNull();
+  });
+
+  it('uses the AUTHORITATIVE DB title, IGNORING the client-supplied title', async () => {
+    const svc = makeService({
+      page: { id: 'p-1', workspaceId: 'ws-1', title: 'Real Title B' },
+      canView: true,
+    });
+    // The client claims it is on "Page A" but the id points at page B.
+    const result = await call(svc, { id: 'p-1', title: 'Page A' });
+    expect(result).toEqual({ id: 'p-1', title: 'Real Title B' });
+  });
+
+  it('coerces a null DB title to an empty string', async () => {
+    const svc = makeService({
+      page: { id: 'p-1', workspaceId: 'ws-1', title: null },
+      canView: true,
+    });
+    expect(await call(svc, { id: 'p-1' })).toEqual({ id: 'p-1', title: '' });
+  });
+});

apps/server/src/core/ai-chat/ai-chat.service.ts

@@ -60,7 +60,10 @@ export function prepareAgentStep(
   system: string,
 ): { toolChoice: 'none'; system: string } | undefined {
   if (stepNumber >= MAX_AGENT_STEPS - 1) {
-    return { toolChoice: 'none', system: `${system}\n\n${FINAL_STEP_INSTRUCTION}` };
+    return {
+      toolChoice: 'none',
+      system: `${system}\n\n${FINAL_STEP_INSTRUCTION}`,
+    };
   }
   return undefined;
 }
@@ -182,6 +185,41 @@ export class AiChatService {
     return this.ai.getChatModel(workspaceId, roleModelOverride(role));
   }
 
+  /**
+   * Validate the client-supplied open page and return its AUTHORITATIVE identity
+   * ({ id, title }) or null. The client controls BOTH the id and the title in the
+   * request body, so neither is trusted: the id must resolve to a real page in
+   * THIS workspace that the user may read, and the title is taken from the DB row
+   * (never the client) so the model can't be told it is "on Page A" while the id
+   * points at page B (#159). Fail-closed — any missing / foreign / inaccessible
+   * page, or any non-Forbidden access-check fault, returns null.
+   */
+  private async resolveOpenPageContext(
+    openPage: { id?: string; title?: string } | null | undefined,
+    workspace: Workspace,
+    user: User,
+  ): Promise<{ id: string; title: string } | null> {
+    const candidatePageId = openPage?.id;
+    if (!candidatePageId) return null;
+    const page = await this.pageRepo.findById(candidatePageId);
+    if (!page || page.workspaceId !== workspace.id) return null;
+    try {
+      await this.pageAccess.validateCanView(page, user);
+    } catch (e) {
+      // A ForbiddenException is the expected "user cannot read this page" case;
+      // log anything else (e.g. a DB error) so a real fault is not masked.
+      if (!(e instanceof ForbiddenException)) {
+        this.logger.warn(
+          `open page access check failed: ${
+            e instanceof Error ? e.message : 'unknown error'
+          }`,
+        );
+      }
+      return null;
+    }
+    return { id: page.id, title: page.title ?? '' };
+  }
+
   async stream({
     user,
     workspace,
@@ -202,37 +240,26 @@ export class AiChatService {
         chatId = undefined;
       }
     }
+    // The open page the client sent is attacker-controllable — BOTH its id and
+    // its title. Resolve it ONCE against the DB (workspace-scoped + access-
+    // checked) and use the AUTHORITATIVE identity everywhere below: the system
+    // prompt context, the getCurrentPage tool, and the new-chat history origin.
+    // Previously the client title was echoed verbatim, so a navigation / two-tab
+    // desync (openPage.id -> page B, title -> "Page A") made the model report
+    // "updated Page A" while it edited page B (#159). Null when no page is open
+    // or the page is foreign / inaccessible / missing.
+    const openPageContext = await this.resolveOpenPageContext(
+      body.openPage,
+      workspace,
+      user,
+    );
+
     if (!chatId) {
-      // Resolve the origin document for the history list. body.openPage.id is
-      // attacker-controllable, so validate it before persisting: it must be a
-      // real page in THIS workspace that the user is allowed to read. Anything
-      // else (foreign workspace, inaccessible/restricted, or non-existent) is
-      // dropped to null — persisting it would leak the page's title via the
-      // chat-list join, or violate the page_id FK on insert (this runs after
-      // res.hijack(), so a DB error would break the stream).
-      let originPageId: string | null = null;
-      const candidatePageId = body.openPage?.id;
-      if (candidatePageId) {
-        const page = await this.pageRepo.findById(candidatePageId);
-        if (page && page.workspaceId === workspace.id) {
-          try {
-            await this.pageAccess.validateCanView(page, user);
-            originPageId = page.id;
-          } catch (e) {
-            // Fail-closed: no provenance on any failure. A ForbiddenException is
-            // the expected "user cannot read this page" case; log anything else
-            // (e.g. a DB error) so a real fault is not masked as "no access".
-            if (!(e instanceof ForbiddenException)) {
-              this.logger.warn(
-                `origin page access check failed: ${
-                  e instanceof Error ? e.message : 'unknown error'
-                }`,
-              );
-            }
-            originPageId = null;
-          }
-        }
-      }
+      // The history-list origin is the validated open page (see above):
+      // persisting an unvalidated id would leak a title via the chat-list join,
+      // or violate the page_id FK on insert (this runs after res.hijack(), so a
+      // DB error would break the stream).
+      const originPageId: string | null = openPageContext?.id ?? null;
       const chat = await this.aiChatRepo.insert({
         creatorId: user.id,
         workspaceId: workspace.id,
@@ -259,9 +286,7 @@ export class AiChatService {
       content: incomingText,
       // jsonb column: UIMessage parts are JSON-serializable at runtime but not
       // structurally `JsonValue`, so cast through unknown.
-      metadata: (incoming?.parts
-        ? { parts: incoming.parts }
-        : null) as never,
+      metadata: (incoming?.parts ? { parts: incoming.parts } : null) as never,
     });
 
     // Rebuild the conversation from persisted history (not the client payload),
@@ -280,38 +305,20 @@ export class AiChatService {
     // The model is resolved by the controller before hijack (clean 503 path).
     // Here we only need the admin-configured system prompt.
     const resolved = await this.aiSettings.resolve(workspace.id);
-    const system = buildSystemPrompt({
-      workspace,
-      adminPrompt: resolved?.systemPrompt,
-      // The role (pre-resolved by the controller) REPLACES the persona layer;
-      // the safety framework is still appended by buildSystemPrompt.
-      roleInstructions: role?.instructions,
-      openedPage: body.openPage,
-    });
 
-    // Pass the resolved chatId so the write tools can mint provenance tokens
-    // (access + collab) carrying { actor:'agent', aiChatId: chatId }, making
-    // agent REST/collab writes attributable and non-spoofable (§6.5/§6.6).
-    const docmostTools = await this.tools.forUser(
-      user,
-      sessionId,
-      workspace.id,
-      chatId,
-      // Same open-page value used by the system prompt above; exposed to the
-      // model via getCurrentPage so page identity survives prompt mangling.
-      body.openPage,
-    );
-
-    // Merge in admin-configured external MCP tools (web search, etc.; §6.8).
-    // A down/slow external server never crashes the turn — toolsFor skips it and
-    // records the outcome. The returned client handles MUST be closed in the
-    // streamText lifecycle (onFinish/onError/onAbort) — leaking them is a bug.
-    // Docmost tools take precedence on a name clash (external are namespaced, so
-    // a clash is not expected; the spread order makes intent explicit).
+    // Build the external MCP toolset FIRST so the system prompt can carry each
+    // connected server's admin-authored guidance (#180). Merge in admin-
+    // configured external MCP tools (web search, etc.; §6.8). A down/slow
+    // external server never crashes the turn — toolsFor skips it and records the
+    // outcome. The returned client handles MUST be closed in the streamText
+    // lifecycle (onFinish/onError/onAbort) — leaking them is a bug. Docmost
+    // tools take precedence on a name clash (external are namespaced, so a clash
+    // is not expected; the spread order makes intent explicit).
     let external: Awaited<ReturnType<McpClientsService['toolsFor']>> = {
       tools: {},
       clients: [],
       outcomes: [],
+      instructions: [],
     };
     try {
       external = await this.mcpClients.toolsFor(workspace.id);
@@ -324,6 +331,33 @@ export class AiChatService {
         }`,
       );
     }
+
+    const system = buildSystemPrompt({
+      workspace,
+      adminPrompt: resolved?.systemPrompt,
+      // The role (pre-resolved by the controller) REPLACES the persona layer;
+      // the safety framework is still appended by buildSystemPrompt.
+      roleInstructions: role?.instructions,
+      // Server-validated open page (authoritative title), not the client value.
+      openedPage: openPageContext,
+      // Guidance only for servers that connected and yielded ≥1 callable tool.
+      mcpInstructions: external.instructions,
+    });
+
+    // Pass the resolved chatId so the write tools can mint provenance tokens
+    // (access + collab) carrying { actor:'agent', aiChatId: chatId }, making
+    // agent REST/collab writes attributable and non-spoofable (§6.5/§6.6).
+    const docmostTools = await this.tools.forUser(
+      user,
+      sessionId,
+      workspace.id,
+      chatId,
+      // Same server-validated open page used by the system prompt above; exposed
+      // to the model via getCurrentPage so page identity (and the AUTHORITATIVE
+      // title) survives prompt mangling and client title spoofing (#159).
+      openPageContext,
+    );
+
     const tools = { ...external.tools, ...docmostTools };
 
     // Close every external client EXACTLY ONCE across the turn's terminal
@@ -380,121 +414,180 @@ export class AiChatService {
     const capturedSteps: StepLike[] = [];
     let inProgressText = '';
 
+    // DIAGNOSTIC (Safari stream-drop investigation) — temporary. Measure
+    // first-chunk latency, the model-silent gap right before a disconnect, and
+    // how many SSE heartbeats were written, so a Safari drop can be classified
+    // (idle-gap vs hard wall-clock cap vs slow first chunk).
+    const streamStartedAt = Date.now();
+    let firstModelChunkAt: number | undefined;
+    let lastModelChunkAt = streamStartedAt;
+    let heartbeatsSent = 0;
+
     // NOTE: streamText is synchronous in v6 — do NOT await it. A synchronous
     // failure here (or in pipe below) would skip the terminal callbacks, so the
     // catch releases the leased external clients to avoid a connection leak.
     let result: ReturnType<typeof streamText>;
     try {
       result = streamText({
-      model,
-      system,
-      messages,
-      tools,
-      // No maxOutputTokens cap on the agent: tool-call arguments (e.g. a full
-      // page body for the write tools) are emitted as OUTPUT tokens, so a fixed
-      // cap would truncate complex tool calls mid-argument. Let the model use its
-      // natural per-step budget. (Cost/credit limits are an account concern, not
-      // something to enforce by silently breaking the agent.)
-      stopWhen: stepCountIs(MAX_AGENT_STEPS),
-      // Forced finalization: reserve the LAST allowed step for a text-only
-      // answer. Without this, a turn that spends all its steps on tool calls
-      // ends with no assistant text (an empty turn). prepareAgentStep forbids
-      // further tool calls and appends a synthesis instruction on that step,
-      // concatenated onto the original `system` so the persona is preserved.
-      prepareStep: ({ stepNumber }) => prepareAgentStep(stepNumber, system),
-      abortSignal: signal,
-      onChunk: ({ chunk }) => {
-        // 'text-delta' is the assistant's prose; tool-call args are separate chunk
-        // types — so this mirrors exactly what streams to the client.
-        if (chunk.type === 'text-delta') inProgressText += chunk.text;
-      },
-      onStepFinish: (step) => {
-        // The finished step's full text is now in `step.text`; fold it in and reset
-        // the in-progress accumulator for the next step.
-        capturedSteps.push(step as StepLike);
-        inProgressText = '';
-      },
-      onFinish: async ({ text, finishReason, totalUsage, usage, steps }) => {
-        await persistAssistant({
-          text,
-          toolCalls: serializeSteps(steps),
-          metadata: {
-            finishReason,
-            // Persist the turn's cumulative usage WITH reasoning tokens resolved
-            // from either the new `outputTokenDetails` or the deprecated top-level
-            // field, so reopened history / the Markdown export show the thinking
-            // token cost too.
-            usage: normalizeStreamUsage(totalUsage as StreamUsage) ?? totalUsage,
-            // Final-step usage = the context actually fed to the model on the last LLM
-            // call (full history + tool results) plus the answer it just generated.
-            // input+output of the FINAL step ≈ the conversation's CURRENT context size,
-            // distinct from totalUsage which sums every step (cumulative tokens spent).
-            contextTokens:
-              (usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0) || undefined,
-            // Persist the FULL set of UIMessage parts for the turn (text +
-            // tool-call/result), so the rebuilt history replays prior tool
-            // context to the model on later turns.
-            parts: assistantParts(steps, text),
-          },
-        });
-        // Lifecycle: release the external MCP clients leased for this turn.
-        await closeExternalClients();
-
-        // Generate the chat title for a freshly created chat AFTER the stream's
-        // provider call has completed — NOT concurrently with it. The z.ai coding
-        // endpoint stalls one of two concurrent requests to the same plan, which
-        // black-holed the chat stream (~300s headers timeout) when title
-        // generation raced it. Running it here (solo, fire-and-forget) avoids the
-        // race; never block the turn on it, swallow any error.
-        if (isNewChat && incomingText) {
-          void this.generateTitle(chatId, workspace.id, incomingText).catch(
-            (err) => {
-              this.logger.warn(
-                `Title generation failed: ${(err as Error)?.message ?? err}`,
-              );
-            },
+        model,
+        system,
+        messages,
+        tools,
+        // No maxOutputTokens cap on the agent: tool-call arguments (e.g. a full
+        // page body for the write tools) are emitted as OUTPUT tokens, so a fixed
+        // cap would truncate complex tool calls mid-argument. Let the model use its
+        // natural per-step budget. (Cost/credit limits are an account concern, not
+        // something to enforce by silently breaking the agent.)
+        stopWhen: stepCountIs(MAX_AGENT_STEPS),
+        // Forced finalization: reserve the LAST allowed step for a text-only
+        // answer. Without this, a turn that spends all its steps on tool calls
+        // ends with no assistant text (an empty turn). prepareAgentStep forbids
+        // further tool calls and appends a synthesis instruction on that step,
+        // concatenated onto the original `system` so the persona is preserved.
+        prepareStep: ({ stepNumber }) => prepareAgentStep(stepNumber, system),
+        abortSignal: signal,
+        onChunk: ({ chunk }) => {
+          // DIAGNOSTIC (Safari stream-drop investigation) — temporary. Any model
+          // output chunk means the stream is actively emitting bytes; track first
+          // + most-recent activity timestamps.
+          const now = Date.now();
+          firstModelChunkAt ??= now;
+          lastModelChunkAt = now;
+          // 'text-delta' is the assistant's prose; tool-call args are separate chunk
+          // types — so this mirrors exactly what streams to the client.
+          if (chunk.type === 'text-delta') inProgressText += chunk.text;
+        },
+        onStepFinish: (step) => {
+          // The finished step's full text is now in `step.text`; fold it in and reset
+          // the in-progress accumulator for the next step.
+          capturedSteps.push(step as StepLike);
+          inProgressText = '';
+        },
+        onFinish: async ({ text, finishReason, totalUsage, usage, steps }) => {
+          // DIAGNOSTIC (Safari stream-drop investigation) — temporary: success
+          // baseline for Safari comparison.
+          const diagNow = Date.now();
+          this.logger.log(
+            `AI chat stream DIAGNOSTIC (finish): elapsed=${diagNow - streamStartedAt}ms ` +
+              `firstChunkLatency=${firstModelChunkAt ? firstModelChunkAt - streamStartedAt : 'none'}ms ` +
+              `heartbeatsSent=${heartbeatsSent} steps=${steps.length}`,
           );
-        }
-      },
-      onError: async ({ error }) => {
-        // NestJS Logger.error(message, stack?, context?): pass the real message
-        // (with statusCode when present) + the stack string, not the Error
-        // object, so the actual provider cause is clearly logged. Reuse the
-        // shared formatter so provider error formatting stays unified.
-        const e = error as { stack?: string };
-        const errorText = describeProviderError(error, String(error));
-        this.logger.error(`AI chat stream error: ${errorText}`, e?.stack);
-        // Persist the PARTIAL answer streamed before the failure (text + any
-        // finished tool steps) WITH the error in metadata, so the turn shows what
-        // the user already saw plus the cause — not just a bare error.
-        await persistAssistant(
-          buildPartialAssistantRecord(
-            capturedSteps,
-            inProgressText,
-            'error',
-            errorText,
-          ),
-        );
-        await closeExternalClients();
-      },
-      onAbort: async ({ steps }) => {
-        const partialChars =
-          capturedSteps.reduce((n, s) => n + (s.text?.length ?? 0), 0) +
-          inProgressText.length;
-        // Unlike onError/onFinish, this terminal path otherwise writes nothing, so
-        // an aborted turn (client disconnect / proxy drop / stop()) would be
-        // invisible in the logs. Log it (warn) so the abort is traceable.
-        this.logger.warn(
-          `AI chat stream aborted (chat ${chatId}) after ${steps.length} ` +
-            `step(s), ${partialChars} chars partial text; persisting partial turn.`,
-        );
-        await persistAssistant(
-          buildPartialAssistantRecord(capturedSteps, inProgressText, 'aborted'),
-        );
-        await closeExternalClients();
-      },
+          await persistAssistant({
+            text,
+            toolCalls: serializeSteps(steps),
+            metadata: {
+              finishReason,
+              // Persist the turn's cumulative usage WITH reasoning tokens resolved
+              // from either the new `outputTokenDetails` or the deprecated top-level
+              // field, so reopened history / the Markdown export show the thinking
+              // token cost too.
+              usage:
+                normalizeStreamUsage(totalUsage as StreamUsage) ?? totalUsage,
+              // Final-step usage = the context actually fed to the model on the last LLM
+              // call (full history + tool results) plus the answer it just generated.
+              // input+output of the FINAL step ≈ the conversation's CURRENT context size,
+              // distinct from totalUsage which sums every step (cumulative tokens spent).
+              contextTokens:
+                (usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0) ||
+                undefined,
+              // Persist the FULL set of UIMessage parts for the turn (text +
+              // tool-call/result), so the rebuilt history replays prior tool
+              // context to the model on later turns.
+              parts: assistantParts(steps, text),
+            },
+          });
+          // Lifecycle: release the external MCP clients leased for this turn.
+          await closeExternalClients();
+
+          // Generate the chat title for a freshly created chat AFTER the stream's
+          // provider call has completed — NOT concurrently with it. The z.ai coding
+          // endpoint stalls one of two concurrent requests to the same plan, which
+          // black-holed the chat stream (~300s headers timeout) when title
+          // generation raced it. Running it here (solo, fire-and-forget) avoids the
+          // race; never block the turn on it, swallow any error.
+          if (isNewChat && incomingText) {
+            void this.generateTitle(chatId, workspace.id, incomingText).catch(
+              (err) => {
+                this.logger.warn(
+                  `Title generation failed: ${(err as Error)?.message ?? err}`,
+                );
+              },
+            );
+          }
+        },
+        onError: async ({ error }) => {
+          // NestJS Logger.error(message, stack?, context?): pass the real message
+          // (with statusCode when present) + the stack string, not the Error
+          // object, so the actual provider cause is clearly logged. Reuse the
+          // shared formatter so provider error formatting stays unified.
+          const e = error as { stack?: string };
+          const errorText = describeProviderError(error, String(error));
+          this.logger.error(`AI chat stream error: ${errorText}`, e?.stack);
+          // DIAGNOSTIC (Safari stream-drop investigation) — temporary: timing of
+          // an error-terminated stream.
+          const diagNow = Date.now();
+          this.logger.warn(
+            `AI chat stream DIAGNOSTIC (error): elapsed=${diagNow - streamStartedAt}ms ` +
+              `firstChunkLatency=${firstModelChunkAt ? firstModelChunkAt - streamStartedAt : 'none'}ms ` +
+              `silentGapBeforeDrop=${diagNow - lastModelChunkAt}ms heartbeatsSent=${heartbeatsSent}`,
+          );
+          // Persist the PARTIAL answer streamed before the failure (text + any
+          // finished tool steps) WITH the error in metadata, so the turn shows what
+          // the user already saw plus the cause — not just a bare error.
+          await persistAssistant(
+            buildPartialAssistantRecord(
+              capturedSteps,
+              inProgressText,
+              'error',
+              errorText,
+            ),
+          );
+          await closeExternalClients();
+        },
+        onAbort: async ({ steps }) => {
+          const partialChars =
+            capturedSteps.reduce((n, s) => n + (s.text?.length ?? 0), 0) +
+            inProgressText.length;
+          // Unlike onError/onFinish, this terminal path otherwise writes nothing, so
+          // an aborted turn (client disconnect / proxy drop / stop()) would be
+          // invisible in the logs. Log it (warn) so the abort is traceable.
+          this.logger.warn(
+            `AI chat stream aborted (chat ${chatId}) after ${steps.length} ` +
+              `step(s), ${partialChars} chars partial text; persisting partial turn.`,
+          );
+          // DIAGNOSTIC (Safari stream-drop investigation) — temporary: THE key
+          // line — classifies the Safari drop.
+          const diagNow = Date.now();
+          this.logger.warn(
+            `AI chat stream DIAGNOSTIC (abort/disconnect): elapsed=${diagNow - streamStartedAt}ms ` +
+              `firstChunkLatency=${firstModelChunkAt ? firstModelChunkAt - streamStartedAt : 'none'}ms ` +
+              `silentGapBeforeDrop=${diagNow - lastModelChunkAt}ms heartbeatsSent=${heartbeatsSent} ` +
+              `steps=${steps.length}`,
+          );
+          await persistAssistant(
+            buildPartialAssistantRecord(
+              capturedSteps,
+              inProgressText,
+              'aborted',
+            ),
+          );
+          await closeExternalClients();
+        },
       });
 
+      // Drain the stream independently of the client socket so the turn always
+      // runs to completion (or to its abort) and the terminal callbacks
+      // (onFinish/onError/onAbort) fire — releasing the per-turn object graph
+      // (history, the per-request toolset closures, captured steps, SDK buffers)
+      // and closing leased MCP clients. WITHOUT this, a client disconnect leaves
+      // the pipe's dead socket as the only reader; backpressure stalls the stream,
+      // the callbacks never run, and every dropped turn stays rooted in memory —
+      // the heap-OOM leak. consumeStream removes that backpressure (AI SDK v6
+      // "Handling client disconnects"). NOT awaited (fire-and-forget); the stream
+      // errors are already logged by the streamText `onError` callback above, so
+      // swallow here to avoid an unhandledRejection.
+      void result.consumeStream({ onError: () => undefined });
+
       // Stream the UI-message protocol straight to the hijacked Node response.
       // Without onError the AI SDK masks the cause ('An error occurred.') and the
       // UI shows a generic failure. Surface the real provider message instead.
@@ -566,7 +659,11 @@ export class AiChatService {
       // headers are sent, and is guarded for response-likes that lack it.
       res.raw.flushHeaders?.();
       // Heartbeat: keep the SSE stream progressing during silent tool/think gaps (Safari/proxy idle timeout).
-      startSseHeartbeat(res.raw);
+      // DIAGNOSTIC (Safari stream-drop investigation) — temporary: count beats so a disconnect log can show
+      // how many pings were written before Safari dropped.
+      startSseHeartbeat(res.raw, 15_000, () => {
+        heartbeatsSent += 1;
+      });
     } catch (err) {
       // Synchronous failure before/while wiring the stream: the terminal
       // callbacks will not run, so release the leased external clients here and
@@ -595,7 +692,10 @@ export class AiChatService {
         'punctuation at the end.',
       prompt: firstMessage.slice(0, 2000),
     });
-    const title = text.trim().replace(/^["']|["']$/g, '').slice(0, 120);
+    const title = text
+      .trim()
+      .replace(/^["']|["']$/g, '')
+      .slice(0, 120);
     if (title) {
       await this.aiChatRepo.update(chatId, { title }, workspaceId);
     }

apps/server/src/core/ai-chat/external-mcp/dto/create-mcp-server.dto.ts

@@ -42,6 +42,15 @@ export class CreateMcpServerDto {
   @IsString({ each: true })
   toolAllowlist?: string[];
 
+  // Admin-authored guidance ("how/when to use this server's tools") injected
+  // into the agent system prompt next to the tool descriptions (#180). Trusted,
+  // NON-secret (so it IS returned). Capped to bound prompt/token size (the
+  // built-in guide is ~1.5KB). Blank => stored as null.
+  @IsOptional()
+  @IsString()
+  @MaxLength(4000)
+  instructions?: string;
+
   @IsOptional()
   @IsBoolean()
   enabled?: boolean;

apps/server/src/core/ai-chat/external-mcp/dto/mcp-server-instructions.dto.spec.ts

@@ -0,0 +1,75 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validateSync } from 'class-validator';
+import { CreateMcpServerDto } from './create-mcp-server.dto';
+import { UpdateMcpServerDto } from './update-mcp-server.dto';
+
+/**
+ * API-boundary validation for the per-server `instructions` field (#180): a free
+ * text guide injected into the agent system prompt. It is optional, must be a
+ * string, and is bounded by @MaxLength(4000) to cap prompt/token size.
+ */
+describe('MCP server DTO instructions validation', () => {
+  function validateCreate(payload: unknown) {
+    const dto = plainToInstance(CreateMcpServerDto, payload);
+    return validateSync(dto as object);
+  }
+  function validateUpdate(payload: unknown) {
+    const dto = plainToInstance(UpdateMcpServerDto, payload);
+    return validateSync(dto as object);
+  }
+
+  const base = {
+    name: 'Tavily',
+    transport: 'http',
+    url: 'https://example.com/mcp',
+  };
+
+  it('accepts an omitted instructions field on create', () => {
+    expect(validateCreate({ ...base })).toHaveLength(0);
+  });
+
+  it('accepts a reasonable instructions string on create', () => {
+    expect(
+      validateCreate({ ...base, instructions: 'Use search for fresh facts.' }),
+    ).toHaveLength(0);
+  });
+
+  it('rejects instructions over MaxLength(4000) on create', () => {
+    const errors = validateCreate({
+      ...base,
+      instructions: 'a'.repeat(4001),
+    });
+    expect(
+      errors.some(
+        (e) =>
+          e.property === 'instructions' &&
+          e.constraints !== undefined &&
+          'maxLength' in e.constraints,
+      ),
+    ).toBe(true);
+  });
+
+  it('accepts instructions of exactly 4000 chars on create', () => {
+    expect(
+      validateCreate({ ...base, instructions: 'a'.repeat(4000) }),
+    ).toHaveLength(0);
+  });
+
+  it('rejects a non-string instructions value', () => {
+    const errors = validateCreate({ ...base, instructions: 123 });
+    expect(errors.some((e) => e.property === 'instructions')).toBe(true);
+  });
+
+  it('rejects instructions over MaxLength(4000) on update', () => {
+    const errors = validateUpdate({ instructions: 'a'.repeat(4001) });
+    expect(
+      errors.some(
+        (e) =>
+          e.property === 'instructions' &&
+          e.constraints !== undefined &&
+          'maxLength' in e.constraints,
+      ),
+    ).toBe(true);
+  });
+});

apps/server/src/core/ai-chat/external-mcp/dto/update-mcp-server.dto.ts

@@ -43,6 +43,13 @@ export class UpdateMcpServerDto {
   @IsString({ each: true })
   toolAllowlist?: string[];
 
+  // Admin-authored prompt guidance (#180). Absent => unchanged; blank => cleared
+  // (stored as null by the repo). Capped to bound prompt/token size.
+  @IsOptional()
+  @IsString()
+  @MaxLength(4000)
+  instructions?: string;
+
   @IsOptional()
   @IsBoolean()
   enabled?: boolean;

apps/server/src/core/ai-chat/external-mcp/mcp-call-timeout.spec.ts

@@ -0,0 +1,205 @@
+import { type Tool, type ToolCallOptions } from 'ai';
+import {
+  wrapToolWithCallTimeout,
+  wrapToolsWithCallTimeout,
+} from './mcp-clients.service';
+import {
+  mcpStreamTimeoutMs,
+  mcpCallTimeoutMs,
+} from '../../../integrations/ai/ai-streaming-fetch';
+
+/**
+ * Per-call total-timeout guard for external MCP tools (mcp-clients.service).
+ *
+ * `@ai-sdk/mcp`'s tool execute has NO built-in per-call timeout — a tool that
+ * keeps the connection warm but never returns is otherwise unbounded. The
+ * wrapper attaches a fresh AbortController + timer per CALL and composes it with
+ * the turn's abortSignal via AbortSignal.any, so EITHER the per-call timeout OR a
+ * client disconnect aborts the in-flight call.
+ *
+ * Fake timers prove the timeout fires WITHOUT real waiting; no leaked timer keeps
+ * the process alive after a fast resolve.
+ */
+const CALL_TIMEOUT_MS = 900_000;
+
+/** Build a Tool around an `execute` impl, mirroring the SDK's minimal shape. */
+function toolWith(
+  execute: (args: unknown, options: ToolCallOptions) => unknown,
+): Tool {
+  return { description: 'x', inputSchema: undefined, execute } as unknown as Tool;
+}
+
+/** Invoke a (possibly wrapped) tool's execute with an optional turn signal. */
+function callExecute(
+  tool: Tool,
+  args: unknown,
+  abortSignal?: AbortSignal,
+): unknown {
+  const execute = tool.execute as (
+    args: unknown,
+    options: ToolCallOptions,
+  ) => unknown;
+  return execute(args, { abortSignal } as ToolCallOptions);
+}
+
+describe('wrapToolWithCallTimeout', () => {
+  beforeEach(() => jest.useFakeTimers());
+  afterEach(() => {
+    jest.clearAllTimers();
+    jest.useRealTimers();
+  });
+
+  it('aborts a tool that only rejects when its abortSignal fires, after ms elapses', async () => {
+    // The tool resolves NEVER on its own — it only settles when the abortSignal
+    // it is handed aborts. So a resolution proves the per-call timer fired and
+    // aborted the call (not the tool finishing by itself).
+    let received: AbortSignal | undefined;
+    const tool = toolWith((_args, options) => {
+      received = options.abortSignal;
+      return new Promise((_resolve, reject) => {
+        options.abortSignal?.addEventListener('abort', () => {
+          reject(options.abortSignal?.reason ?? new Error('aborted'));
+        });
+      });
+    });
+
+    const wrapped = wrapToolWithCallTimeout(tool, CALL_TIMEOUT_MS);
+    const promise = callExecute(wrapped, { q: 'x' }) as Promise<unknown>;
+    // Attach the rejection handler synchronously so advancing timers cannot mark
+    // it an unhandled rejection.
+    const settled = promise.then(
+      () => ({ ok: true as const }),
+      (err: unknown) => ({ ok: false as const, err }),
+    );
+
+    // Nothing fired yet.
+    jest.advanceTimersByTime(CALL_TIMEOUT_MS - 1);
+    // Past the cap -> the per-call timer aborts the composed signal.
+    jest.advanceTimersByTime(2);
+
+    const result = await settled;
+    expect(result.ok).toBe(false);
+    expect(received).toBeInstanceOf(AbortSignal);
+    // The abort reason / rejection mentions the timeout.
+    const message =
+      (result as { err: unknown }).err instanceof Error
+        ? ((result as { err: Error }).err.message)
+        : String((result as { err: unknown }).err);
+    expect(message).toMatch(/timed out after 900000ms/);
+  });
+
+  it('aborts a REAL-client-style tool that never settles and ignores abort (race fix)', async () => {
+    // Models the ACTUAL @ai-sdk/mcp semantics: its in-flight promise does NOT
+    // reject on abort (it only checks the signal when a response arrives), so a
+    // warm-but-stuck call NEVER settles on its own and does NOT listen to the
+    // abort signal. The wrapper must still reject after `ms` via the race — an
+    // implementation that merely `await original(...)` would hang here forever.
+    // This test FAILS against the old await-only code and PASSES with the race.
+    const tool = toolWith(() => new Promise(() => {})); // never settles, no abort
+    const wrapped = wrapToolWithCallTimeout(tool, CALL_TIMEOUT_MS);
+    const promise = callExecute(wrapped, { q: 'x' }) as Promise<unknown>;
+    // Assert the rejection without hanging: drive fake time async so the timer's
+    // abort -> race rejection microtasks flush, then await the rejection.
+    const expectation = expect(promise).rejects.toThrow(/timed out after 900000ms/);
+    await jest.advanceTimersByTimeAsync(CALL_TIMEOUT_MS + 1);
+    await expectation;
+  });
+
+  it('passes a fast tool through and leaks no timer (advancing later does not throw)', async () => {
+    const tool = toolWith(() => Promise.resolve('fast-result'));
+    const wrapped = wrapToolWithCallTimeout(tool, CALL_TIMEOUT_MS);
+
+    const value = await (callExecute(wrapped, {}) as Promise<unknown>);
+    expect(value).toBe('fast-result');
+
+    // The timer was cleared in the finally — advancing past the cap aborts
+    // nothing and throws nothing.
+    expect(() => jest.advanceTimersByTime(CALL_TIMEOUT_MS * 2)).not.toThrow();
+  });
+
+  it('aborts when the caller turn signal aborts before the timeout (disconnect path)', async () => {
+    // Real-client semantics: the tool never settles and does NOT listen to abort,
+    // so the wrapper must reject via the race when the caller's turn signal (a
+    // client disconnect) aborts BEFORE the per-call cap. The race propagates the
+    // caller's abort reason.
+    const tool = toolWith(() => new Promise(() => {})); // never settles, no abort
+    const wrapped = wrapToolWithCallTimeout(tool, CALL_TIMEOUT_MS);
+    const turn = new AbortController();
+    const promise = callExecute(wrapped, {}, turn.signal) as Promise<unknown>;
+    const settled = promise.then(
+      () => ({ ok: true as const }),
+      (err: unknown) => ({ ok: false as const, err }),
+    );
+
+    // Disconnect well before the cap; the per-call timer never fires here.
+    turn.abort(new Error('client disconnected'));
+    const result = await settled;
+    expect(result.ok).toBe(false);
+    const message =
+      (result as { err: unknown }).err instanceof Error
+        ? (result as { err: Error }).err.message
+        : String((result as { err: unknown }).err);
+    // The caller's abort reason propagates through the race.
+    expect(message).toMatch(/client disconnected/);
+  });
+
+  it('passes a tool with no execute through unchanged', () => {
+    const noExecute = { description: 'x', inputSchema: undefined } as unknown as Tool;
+    const wrapped = wrapToolWithCallTimeout(noExecute, CALL_TIMEOUT_MS);
+    // Same object back, execute still absent.
+    expect(wrapped).toBe(noExecute);
+    expect((wrapped as { execute?: unknown }).execute).toBeUndefined();
+  });
+});
+
+describe('wrapToolsWithCallTimeout', () => {
+  beforeEach(() => jest.useFakeTimers());
+  afterEach(() => {
+    jest.clearAllTimers();
+    jest.useRealTimers();
+  });
+
+  it('wraps every tool in the map (each call gets its own guard)', async () => {
+    const tools: Record<string, Tool> = {
+      a: toolWith(() => Promise.resolve('A')),
+      b: toolWith(() => Promise.resolve('B')),
+    };
+    const out = wrapToolsWithCallTimeout(tools, CALL_TIMEOUT_MS);
+    expect(Object.keys(out)).toEqual(['a', 'b']);
+    expect(await (callExecute(out.a, {}) as Promise<unknown>)).toBe('A');
+    expect(await (callExecute(out.b, {}) as Promise<unknown>)).toBe('B');
+  });
+});
+
+describe('mcp timeout env helpers', () => {
+  const ORIG_SILENCE = process.env.AI_MCP_STREAM_TIMEOUT_MS;
+  const ORIG_CALL = process.env.AI_MCP_CALL_TIMEOUT_MS;
+  afterEach(() => {
+    if (ORIG_SILENCE === undefined) delete process.env.AI_MCP_STREAM_TIMEOUT_MS;
+    else process.env.AI_MCP_STREAM_TIMEOUT_MS = ORIG_SILENCE;
+    if (ORIG_CALL === undefined) delete process.env.AI_MCP_CALL_TIMEOUT_MS;
+    else process.env.AI_MCP_CALL_TIMEOUT_MS = ORIG_CALL;
+  });
+
+  it('mcpStreamTimeoutMs defaults to 5 min and honors a positive override', () => {
+    delete process.env.AI_MCP_STREAM_TIMEOUT_MS;
+    expect(mcpStreamTimeoutMs()).toBe(300_000);
+    process.env.AI_MCP_STREAM_TIMEOUT_MS = '60000';
+    expect(mcpStreamTimeoutMs()).toBe(60_000);
+    for (const bad of ['0', '-1', 'x', '']) {
+      process.env.AI_MCP_STREAM_TIMEOUT_MS = bad;
+      expect(mcpStreamTimeoutMs()).toBe(300_000);
+    }
+  });
+
+  it('mcpCallTimeoutMs defaults to 15 min and honors a positive override', () => {
+    delete process.env.AI_MCP_CALL_TIMEOUT_MS;
+    expect(mcpCallTimeoutMs()).toBe(900_000);
+    process.env.AI_MCP_CALL_TIMEOUT_MS = '120000';
+    expect(mcpCallTimeoutMs()).toBe(120_000);
+    for (const bad of ['0', '-1', 'x', '']) {
+      process.env.AI_MCP_CALL_TIMEOUT_MS = bad;
+      expect(mcpCallTimeoutMs()).toBe(900_000);
+    }
+  });
+});

apps/server/src/core/ai-chat/external-mcp/mcp-clients.service.ts

@@ -1,11 +1,16 @@
 import { isIP } from 'node:net';
 import { lookup as dnsLookup, type LookupAddress } from 'node:dns';
 import { Injectable, Logger } from '@nestjs/common';
-import { type Tool } from 'ai';
+import { type Tool, type ToolCallOptions } from 'ai';
 import { createMCPClient } from '@ai-sdk/mcp';
 import { Agent, type Dispatcher } from 'undici';
 import { AiMcpServerRepo } from '@docmost/db/repos/ai-chat/ai-mcp-server.repo';
 import { AiMcpServer } from '@docmost/db/types/entity.types';
+import {
+  streamingDispatcherOptions,
+  mcpStreamTimeoutMs,
+  mcpCallTimeoutMs,
+} from '../../../integrations/ai/ai-streaming-fetch';
 import { SecretBoxService } from '../../../integrations/crypto/secret-box';
 import { isUrlAllowed, isIpAllowed } from './ssrf-guard';
 
@@ -28,6 +33,26 @@ interface ServerOutcome {
   reason?: string;
 }
 
+/**
+ * One server's admin-authored guidance for the agent system prompt (#180).
+ * Built ONLY for a server that actually connected AND contributed ≥1 tool
+ * (after the allowlist filter) AND has non-blank guidance — so a guide never
+ * appears for a server whose tools the agent cannot actually call.
+ */
+export interface McpServerInstruction {
+  /** Display name of the server (for the prompt section header). */
+  serverName: string;
+  /**
+   * The tool-name namespace prefix the server's tools were merged under
+   * (sanitized name, e.g. `tavily`). The prompt renders this as `tavily_*` so
+   * the model can connect the guidance to the actual tool names. Advisory:
+   * individual tools may carry a disambiguating suffix on rare collisions.
+   */
+  toolPrefix: string;
+  /** The trusted, non-blank guidance text. */
+  instructions: string;
+}
+
 export interface ExternalToolset {
   /** Namespaced external tools, merge-ready into the agent toolset. */
   tools: Record<string, Tool>;
@@ -35,6 +60,11 @@ export interface ExternalToolset {
   clients: Closable[];
   /** Per-server connect outcomes so the UI can show unavailable servers. */
   outcomes: ServerOutcome[];
+  /**
+   * Per-server prompt guidance for connected servers that contributed ≥1 tool
+   * and have non-blank instructions. Empty when no server qualifies.
+   */
+  instructions: McpServerInstruction[];
 }
 
 /** Connect+tools() timeout per server — a slow server must not stall the turn. */
@@ -55,6 +85,8 @@ interface CacheEntry {
   tools: Record<string, Tool>;
   clients: McpClient[];
   outcomes: ServerOutcome[];
+  /** Prompt guidance for qualifying servers (see McpServerInstruction). */
+  instructions: McpServerInstruction[];
   expiresAt: number;
   /** Active leases (turns currently using these clients). */
   refCount: number;
@@ -136,6 +168,7 @@ export class McpClientsService {
       tools: entry.tools,
       clients: [release],
       outcomes: entry.outcomes,
+      instructions: entry.instructions,
     };
   }
 
@@ -218,6 +251,9 @@ export class McpClientsService {
     const tools: Record<string, Tool> = {};
     const clients: McpClient[] = [];
     const outcomes: ServerOutcome[] = [];
+    // Per-call total wall-clock cap, read once for this build (env-overridable).
+    const callTimeoutMs = mcpCallTimeoutMs();
+    const instructions: McpServerInstruction[] = [];
 
     for (const server of servers) {
       try {
@@ -226,14 +262,33 @@ export class McpClientsService {
         clients.push(client);
         const allow = server.toolAllowlist;
         const picked =
-          Array.isArray(allow) && allow.length > 0
-            ? pick(raw, allow)
-            : raw;
+          Array.isArray(allow) && allow.length > 0 ? pick(raw, allow) : raw;
+        // Bound each tool's execute with a per-call total-timeout guard before
+        // merging, so a single chatty-but-stuck call is aborted after the cap.
+        const guarded = wrapToolsWithCallTimeout(picked, callTimeoutMs);
         // Namespace each tool with the sanitized server name AND disambiguate
         // against names already merged from earlier servers, so no external
-        // tool is silently overwritten on collision.
-        this.mergeNamespaced(tools, picked, server.name, server.id);
+        // tool is silently overwritten on collision. The returned count drives
+        // whether this server's prompt guidance is included (≥1 tool merged).
+        const merged = this.mergeNamespaced(
+          tools,
+          guarded,
+          server.name,
+          server.id,
+        );
         outcomes.push({ name: server.name, ok: true });
+        // Include this server's guidance ONLY when it actually contributed at
+        // least one tool the agent can call (allowlist may have filtered all of
+        // them out) AND the admin authored non-blank instructions. The header
+        // prefix is the sanitized server name (= the tool namespace prefix).
+        const guide = server.instructions?.trim();
+        if (merged.count > 0 && guide) {
+          instructions.push({
+            serverName: server.name,
+            toolPrefix: merged.prefix,
+            instructions: guide,
+          });
+        }
       } catch (err) {
         // A failed server is skipped — the turn proceeds with the rest. Log a
         // short warning (never the URL/headers) so ops can see degradation, and
@@ -250,6 +305,7 @@ export class McpClientsService {
       tools,
       clients,
       outcomes,
+      instructions,
       expiresAt: Date.now() + CACHE_TTL_MS,
       refCount: 0,
       evicted: false,
@@ -266,16 +322,19 @@ export class McpClientsService {
    * renaming any key that would collide with an already-merged tool (different
    * servers with the same sanitized name, or duplicates after truncation), so
    * no external tool is silently dropped via overwrite.
+   *
+   * Returns how many tools this server actually contributed and the namespace
+   * prefix used (the sanitized server name) so the caller can attach the
+   * server's prompt guidance only when ≥1 tool was merged.
    */
   private mergeNamespaced(
     target: Record<string, Tool>,
     picked: Record<string, Tool>,
     serverName: string,
     serverId: string,
-  ): void {
-    for (const [name, tool] of Object.entries(
-      namespace(picked, serverName),
-    )) {
+  ): { count: number; prefix: string } {
+    let count = 0;
+    for (const [name, tool] of Object.entries(namespace(picked, serverName))) {
       let key = name;
       if (key in target) {
         const original = key;
@@ -285,7 +344,9 @@ export class McpClientsService {
         );
       }
       target[key] = tool;
+      count += 1;
     }
+    return { count, prefix: namespacePrefix(serverName) };
   }
 
   /**
@@ -361,9 +422,7 @@ export class McpClientsService {
 
   /** Close clients, swallowing close errors so they never break a response. */
   private async closeClients(clients: McpClient[]): Promise<void> {
-    await Promise.all(
-      clients.map((c) => c.close().catch(() => undefined)),
-    );
+    await Promise.all(clients.map((c) => c.close().catch(() => undefined)));
   }
 }
 
@@ -376,9 +435,10 @@ export class McpClientsService {
  * lookup hands net/tls.connect ONLY a set that passed this check, so the kernel
  * can never connect to an address that did not pass the guard. Pure — no I/O.
  */
-export function validateResolvedAddresses(
-  addrs: readonly LookupAddress[],
-): { ok: boolean; blockedHost?: string } {
+export function validateResolvedAddresses(addrs: readonly LookupAddress[]): {
+  ok: boolean;
+  blockedHost?: string;
+} {
   if (addrs.length === 0) {
     return { ok: false };
   }
@@ -399,7 +459,21 @@ export function validateResolvedAddresses(
  * to an IP literal).
  */
 function buildPinnedDispatcher(): Agent {
+  // External-MCP traffic uses a DEDICATED, shorter silence timeout
+  // (`AI_MCP_STREAM_TIMEOUT_MS`, default 5 min) — deliberately tighter than the
+  // chat provider's 15-min `streamTimeoutMs()` — so a byte-silent/hung MCP
+  // upstream is broken in ~5 min instead of 15. We keep the keep-alive options
+  // from `streamingDispatcherOptions()` but OVERRIDE headers/body timeouts.
+  // Accepted trade-off: a legitimately long but byte-silent single tool call,
+  // and an SSE transport idling >5 min BETWEEN tool calls, are also cut here; the
+  // per-call total cap (wrapToolsWithCallTimeout, `AI_MCP_CALL_TIMEOUT_MS`) is the
+  // complementary guard for chatty-but-stuck calls that keep the socket warm yet
+  // never return.
+  const mcpSilenceMs = mcpStreamTimeoutMs();
   return new Agent({
+    ...streamingDispatcherOptions(),
+    headersTimeout: mcpSilenceMs,
+    bodyTimeout: mcpSilenceMs,
     connect: {
       lookup: (hostname, _options, callback) => {
         // Always resolve ALL addresses ourselves; do not trust the caller's
@@ -500,7 +574,7 @@ function namespace(
   tools: Record<string, Tool>,
   serverName: string,
 ): Record<string, Tool> {
-  const prefix = sanitizeName(serverName) || 'mcp';
+  const prefix = namespacePrefix(serverName);
   const out: Record<string, Tool> = {};
   for (const [name, t] of Object.entries(tools)) {
     const safe = sanitizeName(name);
@@ -515,6 +589,15 @@ function namespace(
   return out;
 }
 
+/**
+ * The tool-name namespace prefix for a server: its sanitized name, or `mcp`
+ * when the name sanitizes to empty. Tools are merged as `${prefix}_${tool}`, so
+ * the prompt guidance refers to the server's tools as `${prefix}_*`.
+ */
+function namespacePrefix(serverName: string): string {
+  return sanitizeName(serverName) || 'mcp';
+}
+
 /** Reduce an arbitrary string to ^[a-zA-Z0-9_-]+, collapsing runs to '_'. */
 function sanitizeName(value: string): string {
   return value
@@ -561,6 +644,78 @@ function disambiguate(
   return capName(`${name.slice(0, MAX_TOOL_NAME_LENGTH - 14)}_${Date.now()}`);
 }
 
+/**
+ * Wrap every tool's execute with a per-call total-timeout guard so a single
+ * external MCP tool call that keeps the connection warm but never returns is
+ * aborted after `ms` wall-clock (complements the transport silence timeout).
+ */
+export function wrapToolsWithCallTimeout(
+  tools: Record<string, Tool>,
+  ms: number,
+): Record<string, Tool> {
+  const out: Record<string, Tool> = {};
+  for (const [name, t] of Object.entries(tools)) {
+    out[name] = wrapToolWithCallTimeout(t, ms);
+  }
+  return out;
+}
+
+/**
+ * Per-call total-timeout wrapper for one MCP tool. A fresh AbortController +
+ * timer bounds the call; it is composed with the turn's abortSignal via
+ * AbortSignal.any so EITHER the per-call timeout OR a client disconnect aborts
+ * the call. We RACE the call against the composed abort signal rather than just
+ * awaiting it, because @ai-sdk/mcp does NOT settle its in-flight promise on abort
+ * (verified in @ai-sdk/mcp@1.0.52: request() only does throwIfAborted() once
+ * before send and only re-checks the signal inside the response-message handler,
+ * which runs ONLY when a response arrives). So for a warm-but-stuck call awaiting
+ * `original` alone would hang forever even after the timer aborts.
+ */
+export function wrapToolWithCallTimeout(tool: Tool, ms: number): Tool {
+  const original = tool.execute;
+  if (typeof original !== 'function') return tool;
+  const execute = async (args: unknown, options: ToolCallOptions) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+      controller.abort(new Error(`MCP tool call timed out after ${ms}ms`));
+    }, ms);
+    timer.unref?.();
+    const abortSignal = options?.abortSignal
+      ? AbortSignal.any([options.abortSignal, controller.signal])
+      : controller.signal;
+    // Reject as soon as the composed signal fires, independent of whether
+    // `original` ever settles. The losing `original` promise is left pending; it
+    // is cleaned up when the client is closed at turn end, and Promise.race
+    // attaches a rejection handler to BOTH inputs so a late rejection of either
+    // is never an unhandled rejection (do NOT add an extra .catch — it could
+    // swallow the real result and would break the race semantics).
+    const aborted = new Promise<never>((_, reject) => {
+      const fail = () => reject(abortReason(abortSignal));
+      if (abortSignal.aborted) fail();
+      else abortSignal.addEventListener('abort', fail, { once: true });
+    });
+    try {
+      return await Promise.race([
+        original(args, { ...options, abortSignal }),
+        aborted,
+      ]);
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  // `Tool` is a union whose `execute` overloads conflict; cast narrowly so the
+  // wrapped tool keeps every other field while swapping only `execute`.
+  return { ...tool, execute } as unknown as Tool;
+}
+
+/** The signal's reason as an Error (informative thrown value on abort/timeout). */
+function abortReason(signal: AbortSignal): Error {
+  const r = signal.reason;
+  return r instanceof Error
+    ? r
+    : new Error(typeof r === 'string' ? r : 'MCP tool call aborted');
+}
+
 /** Reject a promise after `ms`, so a hung connect/tools() never stalls a turn. */
 function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
   return new Promise<T>((resolve, reject) => {

apps/server/src/core/ai-chat/external-mcp/mcp-instructions.spec.ts

@@ -0,0 +1,168 @@
+import { type Tool } from 'ai';
+import { McpClientsService } from './mcp-clients.service';
+
+/**
+ * Tests for the per-server prompt guidance (#180) assembled by buildEntry and
+ * surfaced via toolsFor().instructions.
+ *
+ * REACHABILITY NOTE: buildEntry is a PRIVATE method; the smallest reachable
+ * public path is toolsFor() -> getOrBuildEntry -> buildEntry -> connect/tools()
+ * -> mergeNamespaced. We drive that path: stub the repo's `listEnabled` and spy
+ * on the private `connect` to return fake MCP clients whose `tools()` we control.
+ *
+ * Contract (all checked here): a server's guidance is included ONLY when the
+ * server actually connected AND contributed ≥1 callable tool (after the
+ * allowlist filter) AND its instructions are non-blank. The header carries the
+ * tool namespace prefix (the sanitized server name).
+ */
+function fakeTool(): Tool {
+  return { description: 'x', inputSchema: undefined } as unknown as Tool;
+}
+
+interface FakeServer {
+  id: string;
+  name: string;
+  transport: string;
+  url: string;
+  headersEnc: string | null;
+  toolAllowlist: string[] | null;
+  instructions: string | null;
+}
+
+function server(
+  over: Partial<FakeServer> & { id: string; name: string },
+): FakeServer {
+  return {
+    transport: 'http',
+    url: 'https://example.com/mcp',
+    headersEnc: null,
+    toolAllowlist: null,
+    instructions: null,
+    ...over,
+  };
+}
+
+async function instructionsFor(
+  servers: FakeServer[],
+  toolsByServerId: Record<string, Record<string, Tool>>,
+  // Server ids whose connect should THROW (simulating an unavailable server).
+  failingIds: Set<string> = new Set(),
+): Promise<
+  {
+    serverName: string;
+    toolPrefix: string;
+    instructions: string;
+  }[]
+> {
+  const repoStub = {
+    listEnabled: jest.fn().mockResolvedValue(servers),
+  };
+  const service = new McpClientsService(repoStub as never, {} as never);
+
+  jest
+    .spyOn(
+      service as unknown as { connect: (s: FakeServer) => unknown },
+      'connect',
+    )
+    .mockImplementation((s: FakeServer) => {
+      if (failingIds.has(s.id)) {
+        return Promise.reject(new Error('connection failed'));
+      }
+      return Promise.resolve({
+        tools: () => Promise.resolve(toolsByServerId[s.id] ?? {}),
+        close: () => Promise.resolve(),
+      });
+    });
+
+  const toolset = await service.toolsFor('ws-1');
+  await Promise.all(toolset.clients.map((c) => c.close()));
+  return toolset.instructions;
+}
+
+describe('external MCP per-server prompt guidance (via toolsFor)', () => {
+  afterEach(() => jest.restoreAllMocks());
+
+  it('includes guidance for a connected server with non-empty text and ≥1 tool', async () => {
+    const instructions = await instructionsFor(
+      [
+        server({
+          id: 'id-tavily',
+          name: 'Tavily',
+          instructions: 'Use tavily_search for fresh facts.',
+        }),
+      ],
+      { 'id-tavily': { search: fakeTool() } },
+    );
+
+    // sanitizeName preserves case (charset [a-zA-Z0-9_-]), so the prefix is the
+    // server name as-is for an already-clean name.
+    expect(instructions).toEqual([
+      {
+        serverName: 'Tavily',
+        toolPrefix: 'Tavily',
+        instructions: 'Use tavily_search for fresh facts.',
+      },
+    ]);
+  });
+
+  it('omits guidance when the server has no instructions', async () => {
+    const instructions = await instructionsFor(
+      [server({ id: 'id-1', name: 'Tavily', instructions: null })],
+      { 'id-1': { search: fakeTool() } },
+    );
+    expect(instructions).toEqual([]);
+  });
+
+  it('omits guidance when the instructions are only whitespace', async () => {
+    const instructions = await instructionsFor(
+      [server({ id: 'id-1', name: 'Tavily', instructions: '   ' })],
+      { 'id-1': { search: fakeTool() } },
+    );
+    expect(instructions).toEqual([]);
+  });
+
+  it('omits guidance for a server that contributed ZERO tools (allowlist filtered all out)', async () => {
+    const instructions = await instructionsFor(
+      [
+        server({
+          id: 'id-1',
+          name: 'Tavily',
+          instructions: 'guide',
+          // Allowlist names a tool the server does not expose -> 0 picked.
+          toolAllowlist: ['nonexistent'],
+        }),
+      ],
+      { 'id-1': { search: fakeTool() } },
+    );
+    expect(instructions).toEqual([]);
+  });
+
+  it('omits guidance for an unavailable (failed-connect) server', async () => {
+    const instructions = await instructionsFor(
+      [server({ id: 'id-1', name: 'Tavily', instructions: 'guide' })],
+      { 'id-1': { search: fakeTool() } },
+      new Set(['id-1']),
+    );
+    expect(instructions).toEqual([]);
+  });
+
+  it('includes only the qualifying servers among several', async () => {
+    const instructions = await instructionsFor(
+      [
+        server({ id: 'ok', name: 'Tavily', instructions: 'web guide' }),
+        server({ id: 'blank', name: 'Crawl', instructions: '' }),
+        server({ id: 'down', name: 'Down', instructions: 'never shown' }),
+      ],
+      {
+        ok: { search: fakeTool() },
+        blank: { crawl: fakeTool() },
+        down: { x: fakeTool() },
+      },
+      new Set(['down']),
+    );
+
+    expect(instructions).toEqual([
+      { serverName: 'Tavily', toolPrefix: 'Tavily', instructions: 'web guide' },
+    ]);
+  });
+});

apps/server/src/core/ai-chat/external-mcp/mcp-servers-to-view.spec.ts

@@ -17,6 +17,7 @@ function row(overrides: Partial<AiMcpServer>): AiMcpServer {
     enabled: true,
     toolAllowlist: null,
     headersEnc: null,
+    instructions: null,
     ...overrides,
   } as unknown as AiMcpServer;
 }
@@ -28,11 +29,7 @@ describe('McpServersService.toView (via list) — encrypted-header leak guard',
     };
     // secretBox + clients are unused by the list/toView path; pass stubs to
     // satisfy the constructor.
-    return new McpServersService(
-      repoStub as never,
-      {} as never,
-      {} as never,
-    );
+    return new McpServersService(repoStub as never, {} as never, {} as never);
   }
 
   it('exposes hasHeaders:true and NO headersEnc when auth headers are set', async () => {
@@ -67,6 +64,7 @@ describe('McpServersService.toView (via list) — encrypted-header leak guard',
         enabled: false,
         toolAllowlist: ['search'],
         headersEnc: 'BLOB',
+        instructions: 'Use search for fresh web facts.',
       }),
     ]);
 
@@ -80,6 +78,19 @@ describe('McpServersService.toView (via list) — encrypted-header leak guard',
       enabled: false,
       toolAllowlist: ['search'],
       hasHeaders: true,
+      instructions: 'Use search for fresh web facts.',
     });
   });
+
+  it('returns instructions (NON-secret) in the view, null when unset', async () => {
+    const service = buildService([
+      row({ id: 'a', instructions: 'How to use these tools.' }),
+      row({ id: 'b', instructions: null }),
+    ]);
+
+    const [withText, withoutText] = await service.list('ws-1');
+
+    expect(withText.instructions).toBe('How to use these tools.');
+    expect(withoutText.instructions).toBeNull();
+  });
 });

apps/server/src/core/ai-chat/external-mcp/mcp-servers.service.ts

@@ -20,6 +20,9 @@ export interface McpServerView {
   enabled: boolean;
   toolAllowlist: string[] | null;
   hasHeaders: boolean;
+  // Admin-authored prompt guidance (#180). NON-secret, so returned in the view.
+  // Null when no guidance is configured.
+  instructions: string | null;
 }
 
 /**
@@ -56,6 +59,8 @@ export class McpServersService {
       url: dto.url,
       headersEnc,
       toolAllowlist: dto.toolAllowlist ?? null,
+      // Blank/whitespace guidance is normalized to null by the repo.
+      instructions: dto.instructions ?? null,
       enabled: dto.enabled ?? true,
     });
     this.clients.invalidate(workspaceId);
@@ -97,6 +102,8 @@ export class McpServersService {
       headersEnc,
       // undefined => unchanged; [] / value handled by repo (empty => null).
       toolAllowlist: dto.toolAllowlist,
+      // undefined => unchanged; blank => cleared (null) by the repo.
+      instructions: dto.instructions,
       enabled: dto.enabled,
     });
     this.clients.invalidate(workspaceId);
@@ -167,6 +174,7 @@ export class McpServersService {
       enabled: row.enabled,
       toolAllowlist: row.toolAllowlist ?? null,
       hasHeaders: Boolean(row.headersEnc),
+      instructions: row.instructions ?? null,
     };
   }
 }

apps/server/src/core/ai-chat/public-share-chat.service.ts

@@ -244,6 +244,15 @@ export class PublicShareChatService {
         },
       });
 
+      // Drain the stream independently of the client socket so the turn always
+      // runs to completion (or to its abort) even when the anonymous client
+      // disconnects — otherwise the dead socket is the only reader, backpressure
+      // stalls the stream, and the per-turn object graph stays rooted (heap-OOM
+      // leak). consumeStream removes that backpressure (AI SDK v6 "Handling
+      // client disconnects"). Fire-and-forget; stream errors are already logged
+      // by the streamText `onError` callback above.
+      void result.consumeStream({ onError: () => undefined });
+
       // Stream the UI-message protocol straight to the hijacked Node response.
       // Surface the real provider message (AI SDK error bodies never carry the
       // API key, so this is safe; we never dump the resolved config).

apps/server/src/core/ai-chat/roles/jsonb-object.spec.ts

@@ -1,30 +0,0 @@
-import { jsonbObject } from '@docmost/db/repos/ai-agent-roles/ai-agent-roles.repo';
-
-/**
- * Unit tests for jsonbObject: the repo helper that encodes a model_config object
- * as a jsonb bind (or null when there is nothing to persist). It is the last
- * line of defence before the column write, so the null-vs-bind decision is what
- * matters here. We assert only null vs non-null because the non-null value is a
- * kysely `sql` template fragment whose internal shape is an implementation
- * detail of the SQL tag.
- */
-describe('jsonbObject', () => {
-  it('returns null for null', () => {
-    expect(jsonbObject(null)).toBeNull();
-  });
-
-  it('returns null for undefined', () => {
-    expect(jsonbObject(undefined)).toBeNull();
-  });
-
-  it('returns null for an empty object (nothing to persist)', () => {
-    expect(jsonbObject({})).toBeNull();
-  });
-
-  it('returns a (non-null) jsonb bind for a non-empty object', () => {
-    const out = jsonbObject({ driver: 'gemini', chatModel: 'gemini-2.0-flash' });
-    // A real sql fragment is produced, never null/undefined.
-    expect(out).not.toBeNull();
-    expect(out).toBeDefined();
-  });
-});

apps/server/src/core/ai-chat/sse-resilience.ts

@@ -28,15 +28,24 @@ import type { ServerResponse } from 'node:http';
  * the response finishes or the socket closes. The interval is unref()'d so it
  * never keeps the process alive, and writes are guarded so we never write to an
  * already-ended/destroyed socket.
+ *
+ * `onBeat` is an OPTIONAL diagnostic hook invoked once after each heartbeat that
+ * was actually written (only when the write did not throw). It is purely for
+ * telemetry/counters and never affects the heartbeat behavior.
  */
 export function startSseHeartbeat(
   res: ServerResponse,
   intervalMs = 15_000,
+  onBeat?: () => void,
 ): () => void {
   const timer = setInterval(() => {
     if (res.writableEnded || res.destroyed) return;
     try {
       res.write(': ping\n\n');
+      // DIAGNOSTIC (Safari stream-drop investigation) — temporary. Notify the
+      // optional hook only after a successful write, so beat counters reflect
+      // pings that actually reached the socket.
+      onBeat?.();
     } catch {
       // Socket vanished between the guard and the write; nothing to do.
     }

apps/server/src/core/share/share-seo.controller.routing.spec.ts

@@ -0,0 +1,133 @@
+import * as fs from 'node:fs';
+import { ShareSeoController } from './share-seo.controller';
+
+/**
+ * Routing guard for ShareSeoController.getShare (red-team finding #3).
+ *
+ * The SEO route must NOT leak a shared page's <title>/og:title to anonymous
+ * visitors / crawlers when the page is not publicly readable. It previously
+ * called the raw `getShareForPage`, which skips the restricted-ancestor gate, so
+ * a permission-restricted descendant of an includeSubPages share leaked its
+ * title. The fix funnels through `resolveReadableSharePage` (the canonical gate)
+ * AND honours `isSharingAllowed`. These tests pin that routing: a non-readable
+ * page or sharing-disabled space serves the plain SPA index (no title); only a
+ * readable, still-shared page gets meta tags.
+ */
+
+const SECRET_TITLE = 'Restricted Quarterly Numbers';
+const INDEX_HTML = `<!doctype html><html><head><title>App</title><!--meta-tags--></head><body></body></html>`;
+const STREAM_SENTINEL = { __isStream: true } as unknown as fs.ReadStream;
+
+// Stub fs at CALL time (jest.spyOn), NOT module load (jest.mock): the controller
+// transitively pulls bcrypt, whose native module is located by node-gyp-build
+// reading the filesystem at import time — a module-level fs mock breaks that.
+beforeEach(() => {
+  jest.spyOn(fs, 'existsSync').mockReturnValue(true);
+  jest.spyOn(fs, 'readFileSync').mockReturnValue(INDEX_HTML);
+  jest.spyOn(fs, 'createReadStream').mockReturnValue(STREAM_SENTINEL);
+});
+afterEach(() => jest.restoreAllMocks());
+
+function makeRes() {
+  const res: any = {
+    sent: undefined as unknown,
+    type: jest.fn(() => res),
+    send: jest.fn((v: unknown) => {
+      res.sent = v;
+    }),
+  };
+  return res;
+}
+
+function makeController(opts: {
+  resolved: { share: any; page: any } | null;
+  sharingAllowed?: boolean;
+}) {
+  const shareService = {
+    resolveReadableSharePage: jest.fn(async () => opts.resolved),
+    isSharingAllowed: jest.fn(async () => opts.sharingAllowed ?? true),
+    // Must NEVER be used by the SEO path anymore (the bypass is the bug).
+    getShareForPage: jest.fn(async () => {
+      throw new Error('getShareForPage must not be called by the SEO path');
+    }),
+  };
+  const workspaceRepo = {
+    findFirst: async () => ({ id: 'ws-1', settings: {} }),
+  };
+  const environmentService = { isSelfHosted: () => true };
+  const controller = new ShareSeoController(
+    shareService as any,
+    workspaceRepo as any,
+    environmentService as any,
+  );
+  return { controller, shareService };
+}
+
+const req: any = { raw: { headers: { host: 'self' } } };
+
+describe('ShareSeoController.getShare routing (#3 title-leak gate)', () => {
+  it('serves the plain index (NO title) when the page is not publicly readable', async () => {
+    const { controller, shareService } = makeController({ resolved: null });
+    const res = makeRes();
+
+    await controller.getShare(res, req, 'share-key', `slug-pageB`);
+
+    // The restricted-ancestor gate ran; the raw bypass did not.
+    expect(shareService.resolveReadableSharePage).toHaveBeenCalled();
+    expect(shareService.getShareForPage).not.toHaveBeenCalled();
+    // The plain index stream was sent — NOT the title-bearing meta HTML.
+    expect(res.sent).toBe(STREAM_SENTINEL);
+  });
+
+  it('serves the plain index when sharing was disabled at the workspace/space level', async () => {
+    const { controller } = makeController({
+      resolved: {
+        share: { spaceId: 'sp-1', searchIndexing: true },
+        page: { title: SECRET_TITLE },
+      },
+      sharingAllowed: false,
+    });
+    const res = makeRes();
+
+    await controller.getShare(res, req, 'share-key', 'slug-pageB');
+
+    // The plain index stream was sent, so the restricted title never reached
+    // the response (it is only ever interpolated into the meta HTML string).
+    expect(res.sent).toBe(STREAM_SENTINEL);
+    expect(res.sent).not.toBe(SECRET_TITLE);
+  });
+
+  it('injects the title + meta for a readable, still-shared page', async () => {
+    const { controller } = makeController({
+      resolved: {
+        share: { spaceId: 'sp-1', searchIndexing: true },
+        page: { title: 'Public Handbook' },
+      },
+      sharingAllowed: true,
+    });
+    const res = makeRes();
+
+    await controller.getShare(res, req, 'share-key', 'slug-pageA');
+
+    expect(typeof res.sent).toBe('string');
+    expect(res.sent as string).toContain('<title>Public Handbook</title>');
+    expect(res.sent as string).toContain('og:title');
+    // searchIndexing on => crawlable (no noindex).
+    expect(res.sent as string).not.toContain('content="noindex"');
+  });
+
+  it('adds robots=noindex when the share opted out of search indexing', async () => {
+    const { controller } = makeController({
+      resolved: {
+        share: { spaceId: 'sp-1', searchIndexing: false },
+        page: { title: 'Internal Notes' },
+      },
+      sharingAllowed: true,
+    });
+    const res = makeRes();
+
+    await controller.getShare(res, req, 'share-key', 'slug-pageA');
+
+    expect(res.sent as string).toContain('content="noindex"');
+  });
+});

apps/server/src/core/share/share-seo.controller.ts

@@ -63,19 +63,38 @@ export class ShareSeoController {
 
       const pageId = this.extractPageSlugId(pageSlug);
 
-      const share = await this.shareService.getShareForPage(
+      // Funnel through the canonical readable-share boundary (NOT the raw
+      // getShareForPage) so the restricted-ancestor gate runs: a permission-
+      // restricted descendant of an includeSubPages share must NOT leak its
+      // title to anonymous visitors / crawlers (red-team finding #3). null =>
+      // not publicly readable => serve the plain SPA index with no meta.
+      const resolved = await this.shareService.resolveReadableSharePage(
+        undefined,
         pageId,
         workspace.id,
       );
 
-      if (!share) {
+      if (!resolved) {
+        return this.sendIndex(indexFilePath, res);
+      }
+
+      // Honour a workspace/space-level sharing toggle flipped off AFTER this
+      // share was created: the content API gates on isSharingAllowed, so the SEO
+      // path must too or it keeps serving the title for a no-longer-shared page.
+      const sharingAllowed = await this.shareService.isSharingAllowed(
+        workspace.id,
+        resolved.share.spaceId,
+      );
+      if (!sharingAllowed) {
         return this.sendIndex(indexFilePath, res);
       }
 
       const html = fs.readFileSync(indexFilePath, 'utf8');
+      // Title of the PAGE being viewed (server-resolved), and noindex unless the
+      // share opted into search indexing (buildShareMetaHtml injects it).
       let transformedHtml = buildShareMetaHtml(html, {
-        title: share?.sharedPage.title,
-        searchIndexing: share.searchIndexing,
+        title: resolved.page.title,
+        searchIndexing: resolved.share.searchIndexing,
       });
 
       // Deliberate same-origin tracker surface: this is the ONE place where an

apps/server/src/database/jsonb-bind.spec.ts

@@ -0,0 +1,38 @@
+import { jsonbBind } from './utils';
+
+/**
+ * Unit tests for jsonbBind: THE shared helper that encodes a JS array/object as
+ * a jsonb bind (or null when there is nothing to persist). It is the last line
+ * of defence before a jsonb column write, so the null-vs-bind decision is what
+ * matters here. We assert only null vs non-null because the non-null value is a
+ * kysely `sql` template fragment whose internal shape is an implementation
+ * detail of the SQL tag (the `::text::jsonb` double-encoding fix is verified
+ * end-to-end by the repo integration specs, where a real DB round-trip can
+ * actually observe `jsonb_typeof`).
+ */
+describe('jsonbBind', () => {
+  it('returns null for null / undefined', () => {
+    expect(jsonbBind(null)).toBeNull();
+    expect(jsonbBind(undefined)).toBeNull();
+  });
+
+  it('returns null for an empty array (nothing to persist)', () => {
+    expect(jsonbBind([])).toBeNull();
+  });
+
+  it('returns null for an empty object (nothing to persist)', () => {
+    expect(jsonbBind({})).toBeNull();
+  });
+
+  it('returns a (non-null) bind for a non-empty array', () => {
+    const out = jsonbBind(['search', 'crawl']);
+    expect(out).not.toBeNull();
+    expect(out).toBeDefined();
+  });
+
+  it('returns a (non-null) bind for a non-empty object', () => {
+    const out = jsonbBind({ driver: 'gemini', chatModel: 'gemini-2.0-flash' });
+    expect(out).not.toBeNull();
+    expect(out).toBeDefined();
+  });
+});

apps/server/src/database/migrations/20260625T120000-ai-mcp-servers-instructions.ts

@@ -0,0 +1,19 @@
+import { type Kysely } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  // Per-server, admin-authored instruction text injected into the agent system
+  // prompt next to the server's tool descriptions (#180). NON-secret (unlike
+  // headers_enc): it IS returned in admin views/forms. Nullable: a server may
+  // have no guidance. Trusted text — it goes inside the prompt safety sandwich.
+  await db.schema
+    .alterTable('ai_mcp_servers')
+    .addColumn('instructions', 'text', (col) => col)
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .alterTable('ai_mcp_servers')
+    .dropColumn('instructions')
+    .execute();
+}

apps/server/src/database/repos/ai-agent-roles/ai-agent-roles.repo.spec.ts

@@ -35,7 +35,13 @@ describe('AiAgentRoleRepo.findLiveEnabled', () => {
 
     const result = await repo.findLiveEnabled('r-1', 'ws-1');
 
-    expect(result).toBe(role);
+    // The repo normalizes the row (modelConfig parse), so it returns a COPY, not
+    // the same reference; assert the row's fields are carried through.
+    expect(result).toMatchObject({
+      id: 'r-1',
+      workspaceId: 'ws-1',
+      enabled: true,
+    });
     expect(db.selectFrom).toHaveBeenCalledWith('aiAgentRoles');
     // Every security filter must be present.
     expect(where).toHaveBeenCalledWith('id', '=', 'r-1');

apps/server/src/database/repos/ai-agent-roles/ai-agent-roles.repo.ts

@@ -1,8 +1,7 @@
 import { Injectable } from '@nestjs/common';
 import { InjectKysely } from 'nestjs-kysely';
-import { sql } from 'kysely';
 import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
-import { dbOrTx } from '../../utils';
+import { dbOrTx, jsonbBind } from '../../utils';
 import { AiAgentRole } from '@docmost/db/types/entity.types';
 
 /** The jsonb shape persisted in `model_config` (loosely typed for the column). */
@@ -23,13 +22,14 @@ export class AiAgentRoleRepo {
     id: string,
     workspaceId: string,
   ): Promise<AiAgentRole | undefined> {
-    return this.db
+    const row = await this.db
       .selectFrom('aiAgentRoles')
       .selectAll('aiAgentRoles')
       .where('id', '=', id)
       .where('workspaceId', '=', workspaceId)
       .where('deletedAt', 'is', null)
       .executeTakeFirst();
+    return row ? normalizeRow(row) : row;
   }
 
   /**
@@ -45,7 +45,7 @@ export class AiAgentRoleRepo {
     id: string,
     workspaceId: string,
   ): Promise<AiAgentRole | undefined> {
-    return this.db
+    const row = await this.db
       .selectFrom('aiAgentRoles')
       .selectAll('aiAgentRoles')
       .where('id', '=', id)
@@ -53,17 +53,19 @@ export class AiAgentRoleRepo {
       .where('deletedAt', 'is', null)
       .where('enabled', '=', true)
       .executeTakeFirst();
+    return row ? normalizeRow(row) : row;
   }
 
   /** All live roles for the workspace (management list + chat picker). */
   async listByWorkspace(workspaceId: string): Promise<AiAgentRole[]> {
-    return this.db
+    const rows = await this.db
       .selectFrom('aiAgentRoles')
       .selectAll('aiAgentRoles')
       .where('workspaceId', '=', workspaceId)
       .where('deletedAt', 'is', null)
       .orderBy('createdAt', 'asc')
       .execute();
+    return rows.map(normalizeRow);
   }
 
   async insert(
@@ -83,7 +85,7 @@ export class AiAgentRoleRepo {
     trx?: KyselyTransaction,
   ): Promise<AiAgentRole> {
     const db = dbOrTx(this.db, trx);
-    return db
+    const row = await db
       .insertInto('aiAgentRoles')
       .values({
         workspaceId: values.workspaceId,
@@ -92,7 +94,11 @@ export class AiAgentRoleRepo {
         emoji: values.emoji ?? null,
         description: values.description ?? null,
         instructions: values.instructions,
-        modelConfig: jsonbObject(values.modelConfig),
+        // Cast: the generated `model_config` column type is the broad JsonValue
+        // union, which the concrete RawBuilder<Record> is not structurally
+        // assignable to (same reason the old jsonbObject cast to any).
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        modelConfig: jsonbBind(values.modelConfig) as any,
         enabled: values.enabled ?? true,
         autoStart: values.autoStart ?? true,
         // Empty string is treated as "no custom text" => null.
@@ -100,6 +106,7 @@ export class AiAgentRoleRepo {
       })
       .returningAll()
       .executeTakeFirst();
+    return normalizeRow(row);
   }
 
   async update(
@@ -127,7 +134,7 @@ export class AiAgentRoleRepo {
     if (patch.description !== undefined) set.description = patch.description;
     if (patch.instructions !== undefined) set.instructions = patch.instructions;
     if (patch.modelConfig !== undefined) {
-      set.modelConfig = jsonbObject(patch.modelConfig);
+      set.modelConfig = jsonbBind(patch.modelConfig);
     }
     if (patch.enabled !== undefined) set.enabled = patch.enabled;
     if (patch.autoStart !== undefined) set.autoStart = patch.autoStart;
@@ -163,16 +170,40 @@ export class AiAgentRoleRepo {
 }
 
 /**
- * Encode an object as a jsonb bind for the `model_config` column. The postgres
- * driver would otherwise need an explicit cast; bind the JSON text and cast it.
- * Returns null for null/undefined/empty objects. Cast to `any` because the
- * generated column type is the broad `JsonValue` union, which a concrete object
- * type is not structurally assignable to.
+ * Parse the `model_config` value read from the DB into the object the entity
+ * type promises. Rows written by the old double-encoding bind (`::jsonb` instead
+ * of `::text::jsonb`) round-trip as a JSON STRING, so the driver hands back e.g.
+ * `'{"driver":"gemini"}'` rather than an object; the read-path check
+ * `typeof cfg === 'object'` then failed and the model override was SILENTLY
+ * dropped (the role fell back to the default model). Be tolerant: a JSON string
+ * is parsed; an already-parsed object passes through; null / a non-object (incl.
+ * an array) / unparseable value becomes null (= no override). This self-heals
+ * already-corrupted rows on read, no migration required.
  */
-export function jsonbObject(value: ModelConfigValue | undefined) {
-  if (value === null || value === undefined || Object.keys(value).length === 0) {
-    return null;
+export function parseModelConfig(
+  value: unknown,
+): Record<string, unknown> | null {
+  let v: unknown = value;
+  if (typeof v === 'string') {
+    try {
+      v = JSON.parse(v); // legacy double-encoded read
+    } catch {
+      return null;
+    }
   }
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  return sql`${JSON.stringify(value)}::jsonb` as any;
+  return v !== null && typeof v === 'object' && !Array.isArray(v)
+    ? (v as Record<string, unknown>)
+    : null;
+}
+
+/** Normalize a DB row so `modelConfig` is always an object or null. The cast
+ *  bridges parseModelConfig's concrete `Record | null` to the column's broad
+ *  generated `JsonValue` type (an object is a valid JsonValue at runtime). */
+function normalizeRow(row: AiAgentRole): AiAgentRole {
+  return {
+    ...row,
+    modelConfig: parseModelConfig(
+      row.modelConfig,
+    ) as AiAgentRole['modelConfig'],
+  };
 }

apps/server/src/database/repos/ai-agent-roles/parse-model-config.spec.ts

@@ -0,0 +1,46 @@
+import { parseModelConfig } from './ai-agent-roles.repo';
+
+/**
+ * Unit tests for parseModelConfig: the read-side normalizer that repairs the
+ * jsonb double-encoding regression on `model_config`. Rows written by the old
+ * `::jsonb` bind round-trip as a JSON STRING, which the read path's
+ * `typeof === 'object'` check rejected — silently dropping the model override.
+ * parseModelConfig accepts an already-parsed object, parses a legacy JSON
+ * string, and rejects everything that is not an object (null = no override).
+ */
+describe('parseModelConfig', () => {
+  it('passes an already-parsed object through', () => {
+    expect(parseModelConfig({ driver: 'gemini' })).toEqual({
+      driver: 'gemini',
+    });
+  });
+
+  it('parses a legacy double-encoded JSON string into an object', () => {
+    expect(parseModelConfig('{"driver":"gemini","chatModel":"x"}')).toEqual({
+      driver: 'gemini',
+      chatModel: 'x',
+    });
+  });
+
+  it('returns null for null / undefined', () => {
+    expect(parseModelConfig(null)).toBeNull();
+    expect(parseModelConfig(undefined)).toBeNull();
+  });
+
+  it('returns null for a non-object JSON value (string/number/array)', () => {
+    expect(parseModelConfig('"justastring"')).toBeNull();
+    expect(parseModelConfig('42')).toBeNull();
+    // An array is an object in JS but not a valid model_config shape.
+    expect(parseModelConfig('["a","b"]')).toBeNull();
+    expect(parseModelConfig(['a', 'b'])).toBeNull();
+  });
+
+  it('returns null for an unparseable string', () => {
+    expect(parseModelConfig('not json at all')).toBeNull();
+  });
+
+  it('returns null for a raw non-object primitive', () => {
+    expect(parseModelConfig(42 as unknown)).toBeNull();
+    expect(parseModelConfig(true as unknown)).toBeNull();
+  });
+});

apps/server/src/database/repos/ai-chat/ai-mcp-server.repo.spec.ts

@@ -0,0 +1,74 @@
+import { parseToolAllowlist, blankToNull } from './ai-mcp-server.repo';
+
+/**
+ * The `tool_allowlist` jsonb column historically round-trips as a JSON STRING
+ * (rows written by the old double-encoding `jsonbArray`), so the driver hands
+ * back `'["a","b"]'` instead of an array. `parseToolAllowlist` normalizes both
+ * shapes to the `string[] | null` the entity type promises — fixing the settings
+ * UI crash (TagsInput `.map` on a string) and the tool-allowlist enforcement
+ * (which did `Array.isArray(allow)` and silently allowed ALL tools for a string).
+ */
+describe('parseToolAllowlist', () => {
+  it('passes a real string array through unchanged', () => {
+    expect(parseToolAllowlist(['search', 'crawl'])).toEqual([
+      'search',
+      'crawl',
+    ]);
+  });
+
+  it('parses a JSON-string array (the double-encoded read) into an array', () => {
+    // This is exactly what the DB returns for an old row: a jsonb string scalar.
+    expect(parseToolAllowlist('["alpha","beta"]')).toEqual(['alpha', 'beta']);
+  });
+
+  it('returns null for null / undefined (unrestricted)', () => {
+    expect(parseToolAllowlist(null)).toBeNull();
+    expect(parseToolAllowlist(undefined)).toBeNull();
+  });
+
+  it('returns [] for an empty array (no items, but a present allowlist)', () => {
+    expect(parseToolAllowlist([])).toEqual([]);
+  });
+
+  it('returns null for a JSON string that is not an array', () => {
+    expect(parseToolAllowlist('"justastring"')).toBeNull();
+    expect(parseToolAllowlist('{"a":1}')).toBeNull();
+  });
+
+  it('returns null for an unparseable string', () => {
+    expect(parseToolAllowlist('not json at all')).toBeNull();
+  });
+
+  it('returns null when elements are not all strings (defensive)', () => {
+    expect(parseToolAllowlist([1, 2, 3] as unknown)).toBeNull();
+    expect(parseToolAllowlist('[1,2,3]')).toBeNull();
+  });
+
+  it('returns null for a non-string, non-array primitive', () => {
+    expect(parseToolAllowlist(42 as unknown)).toBeNull();
+    expect(parseToolAllowlist(true as unknown)).toBeNull();
+  });
+});
+
+/**
+ * `blankToNull` normalizes the per-server `instructions` free text before it is
+ * stored (#180): a missing/blank/whitespace-only value becomes null (so an empty
+ * guide is never persisted), any other value is trimmed.
+ */
+describe('blankToNull', () => {
+  it('returns null for null / undefined', () => {
+    expect(blankToNull(null)).toBeNull();
+    expect(blankToNull(undefined)).toBeNull();
+  });
+
+  it('returns null for an empty / whitespace-only string', () => {
+    expect(blankToNull('')).toBeNull();
+    expect(blankToNull('   ')).toBeNull();
+    expect(blankToNull('\n\t ')).toBeNull();
+  });
+
+  it('trims and returns a non-blank string', () => {
+    expect(blankToNull('  use the search tool  ')).toBe('use the search tool');
+    expect(blankToNull('guide')).toBe('guide');
+  });
+});

apps/server/src/database/repos/ai-chat/ai-mcp-server.repo.ts

@@ -1,10 +1,11 @@
-import { Injectable } from '@nestjs/common';
+import { Injectable, Logger } from '@nestjs/common';
 import { InjectKysely } from 'nestjs-kysely';
-import { sql } from 'kysely';
 import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
-import { dbOrTx } from '../../utils';
+import { dbOrTx, jsonbBind } from '../../utils';
 import { AiMcpServer } from '@docmost/db/types/entity.types';
 
+const logger = new Logger('AiMcpServerRepo');
+
 /**
  * Repository for per-workspace external MCP servers the agent may use (§5.4).
  *
@@ -21,32 +22,35 @@ export class AiMcpServerRepo {
     id: string,
     workspaceId: string,
   ): Promise<AiMcpServer | undefined> {
-    return this.db
+    const row = await this.db
       .selectFrom('aiMcpServers')
       .selectAll('aiMcpServers')
       .where('id', '=', id)
       .where('workspaceId', '=', workspaceId)
       .executeTakeFirst();
+    return row ? normalizeRow(row) : row;
   }
 
   async listByWorkspace(workspaceId: string): Promise<AiMcpServer[]> {
-    return this.db
+    const rows = await this.db
       .selectFrom('aiMcpServers')
       .selectAll('aiMcpServers')
       .where('workspaceId', '=', workspaceId)
       .orderBy('createdAt', 'asc')
       .execute();
+    return rows.map(normalizeRow);
   }
 
   /** Enabled servers only — used by the agent loop to build the toolset. */
   async listEnabled(workspaceId: string): Promise<AiMcpServer[]> {
-    return this.db
+    const rows = await this.db
       .selectFrom('aiMcpServers')
       .selectAll('aiMcpServers')
       .where('workspaceId', '=', workspaceId)
       .where('enabled', '=', true)
       .orderBy('createdAt', 'asc')
       .execute();
+    return rows.map(normalizeRow);
   }
 
   async insert(
@@ -57,6 +61,8 @@ export class AiMcpServerRepo {
       url: string;
       headersEnc?: string | null;
       toolAllowlist?: string[] | null;
+      // Admin-authored prompt guidance; blank/whitespace normalizes to null.
+      instructions?: string | null;
       enabled?: boolean;
     },
     trx?: KyselyTransaction,
@@ -72,7 +78,9 @@ export class AiMcpServerRepo {
         headersEnc: values.headersEnc ?? null,
         // jsonb column: the postgres driver would otherwise encode a JS array as
         // a Postgres array literal. Bind the JSON text and cast it to jsonb.
-        toolAllowlist: jsonbArray(values.toolAllowlist),
+        toolAllowlist: jsonbBind(values.toolAllowlist),
+        // Plain text column: blank/whitespace-only guidance is stored as null.
+        instructions: blankToNull(values.instructions),
         enabled: values.enabled ?? true,
       })
       .returningAll()
@@ -90,6 +98,8 @@ export class AiMcpServerRepo {
       headersEnc?: string | null;
       // undefined => leave unchanged; null => clear; string[] => set.
       toolAllowlist?: string[] | null;
+      // undefined => leave unchanged; null/blank => clear; string => set.
+      instructions?: string | null;
       enabled?: boolean;
     },
     trx?: KyselyTransaction,
@@ -101,7 +111,11 @@ export class AiMcpServerRepo {
     if (patch.url !== undefined) set.url = patch.url;
     if (patch.headersEnc !== undefined) set.headersEnc = patch.headersEnc;
     if (patch.toolAllowlist !== undefined) {
-      set.toolAllowlist = jsonbArray(patch.toolAllowlist);
+      set.toolAllowlist = jsonbBind(patch.toolAllowlist);
+    }
+    if (patch.instructions !== undefined) {
+      // Blank/whitespace-only guidance clears the column (stored as null).
+      set.instructions = blankToNull(patch.instructions);
     }
     if (patch.enabled !== undefined) set.enabled = patch.enabled;
     await db
@@ -127,17 +141,53 @@ export class AiMcpServerRepo {
 }
 
 /**
- * Encode a string[] as a jsonb bind for the `tool_allowlist` column. Passing a
- * plain JS array to the postgres driver would serialize it as a Postgres array
- * literal (incompatible with jsonb), so we bind the JSON text and cast it.
- * Returns null for null/empty arrays (an empty allowlist means "no restriction"
- * is not intended — callers pass null to clear; an empty array is normalized to
- * null here so it never round-trips as `[]`).
+ * Normalize an optional free-text field to a stored value: a missing/blank/
+ * whitespace-only string becomes null (so an "empty" guide is never persisted),
+ * any other string is trimmed. Returns null for null/undefined input.
  */
-function jsonbArray(value: string[] | null | undefined) {
-  if (value === null || value === undefined || value.length === 0) {
-    return null;
-  }
-  // Typed as string[] so it is assignable to the toolAllowlist column.
-  return sql<string[]>`${JSON.stringify(value)}::jsonb`;
+export function blankToNull(value: string | null | undefined): string | null {
+  if (value == null) return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+/**
+ * Parse the `toolAllowlist` value read from the DB into the `string[] | null`
+ * the entity type promises. The jsonb column historically round-trips as a JSON
+ * STRING (rows written by the old double-encoding bind before the `::text::jsonb`
+ * fix), so the driver hands back a string like `'["a","b"]'` rather than an
+ * array. Be tolerant: normalize a JSON string to its value, then accept it only
+ * if it is an array of strings; null / a non-array / unparseable value / an
+ * array with a non-string element all become null (unrestricted).
+ */
+export function parseToolAllowlist(value: unknown): string[] | null {
+  let v: unknown = value;
+  if (typeof v === 'string') {
+    try {
+      v = JSON.parse(v); // legacy double-encoded read
+    } catch {
+      return null;
+    }
+  }
+  return Array.isArray(v) && v.every((x) => typeof x === 'string')
+    ? (v as string[])
+    : null;
+}
+
+/**
+ * Normalize a DB row so `toolAllowlist` is always `string[] | null`.
+ *
+ * FAIL-OPEN logging: a stored value that is present but cannot be parsed into a
+ * string[] (corrupt JSON, a non-array, non-string elements) degrades to `null` =
+ * "no restriction", so the agent silently gets ALL of the server's tools. Log
+ * one line (server id only, never the contents) so that widening is not silent.
+ */
+function normalizeRow(row: AiMcpServer): AiMcpServer {
+  const parsed = parseToolAllowlist(row.toolAllowlist);
+  if (parsed === null && row.toolAllowlist != null) {
+    logger.warn(
+      `Corrupt tool_allowlist for MCP server ${row.id}; ignoring it (no tool restriction applied)`,
+    );
+  }
+  return { ...row, toolAllowlist: parsed };
 }

apps/server/src/database/repos/workspace/workspace.repo.ts

@@ -10,6 +10,29 @@ import {
 import { ExpressionBuilder, sql } from 'kysely';
 import { DB, Workspaces } from '@docmost/db/types/db';
 
+/**
+ * Writable `settings.ai.provider` keys, enforced at this generic SQL layer. This
+ * repo cannot import AI-feature types, so this list is its own copy; a parity
+ * test (ai-provider-settings-keys.spec.ts) asserts it equals
+ * PROVIDER_SETTINGS_KEYS in ai.types so a future drift fails in CI rather than
+ * silently dropping a field at this boundary.
+ */
+export const AI_PROVIDER_SETTINGS_ALLOWED: readonly string[] = [
+  'driver',
+  'chatModel',
+  'chatApiStyle',
+  'embeddingModel',
+  'baseUrl',
+  'embeddingBaseUrl',
+  'sttModel',
+  'sttBaseUrl',
+  'sttApiStyle',
+  'sttLanguage',
+  'systemPrompt',
+  'publicShareChatModel',
+  'publicShareAssistantRoleId',
+];
+
 @Injectable()
 export class WorkspaceRepo {
   public baseFields: Array<keyof Workspaces> = [
@@ -239,9 +262,8 @@ export class WorkspaceRepo {
     // is a real jsonb object, never a double-encoded string. The CASE self-heals
     // workspaces whose settings.ai.provider was previously corrupted into an
     // array/string.
-    const ALLOWED = ['driver', 'chatModel', 'embeddingModel', 'baseUrl', 'embeddingBaseUrl', 'sttModel', 'sttBaseUrl', 'sttApiStyle', 'sttLanguage', 'systemPrompt', 'publicShareChatModel', 'publicShareAssistantRoleId'];
     const entries = Object.entries(provider).filter(
-      ([k, v]) => v !== undefined && ALLOWED.includes(k),
+      ([k, v]) => v !== undefined && AI_PROVIDER_SETTINGS_ALLOWED.includes(k),
     );
     const patch = entries.length
       ? sql`jsonb_build_object(${sql.join(

apps/server/src/database/types/ai-mcp-servers.types.ts

@@ -20,8 +20,15 @@ export interface AiMcpServers {
   // Encrypted JSON of the auth headers. Nullable (a server may need no auth).
   headersEnc: string | null;
   // Optional allowlist of remote tool names to expose; null = expose all.
-  // Stored as jsonb; reads come back as a string[] from the postgres driver.
+  // Stored as jsonb. The postgres driver may return a JSON string for legacy
+  // double-encoded rows; `AiMcpServerRepo` normalizes every read to
+  // `string[] | null` via `parseToolAllowlist`.
   toolAllowlist: string[] | null;
+  // Admin-authored guidance ("how/when to use this server's tools") injected
+  // into the agent system prompt (#180). Unlike `headersEnc` this is NON-secret
+  // and IS returned in admin views/forms. Plain text column (no jsonb). Null =
+  // no guidance. Trusted text — it goes inside the prompt safety sandwich.
+  instructions: string | null;
   enabled: Generated<boolean>;
   createdAt: Generated<Timestamp>;
   updatedAt: Generated<Timestamp>;

apps/server/src/database/utils.ts

@@ -1,3 +1,4 @@
+import { sql, RawBuilder } from 'kysely';
 import { KyselyDB, KyselyTransaction } from './types/kysely.types';
 
 /*
@@ -31,3 +32,35 @@ export function dbOrTx(
     return db; // Use normal database instance
   }
 }
+
+/**
+ * Bind a JS array/object as a `jsonb` column value, working around a postgres
+ * driver double-encoding quirk. THE single implementation — repos that persist
+ * jsonb (`tool_allowlist`, `model_config`, ...) call this instead of re-deriving
+ * the cast.
+ *
+ * THE QUIRK: with the `kysely-postgres-js` / postgres.js driver, casting a bound
+ * parameter straight to `::jsonb` makes the driver infer the param type as jsonb
+ * and JSON-stringify the (already-JSON) text a SECOND time, so the column ends
+ * up holding a jsonb STRING SCALAR (`"[\"a\"]"` / `"{\"k\":1}"`) instead of a
+ * real jsonb array/object. Read paths then see a string, not the structure, and
+ * silently fall back (an allowlist becomes "unrestricted", a model override is
+ * ignored). Forcing the param through `::text` first binds it as text (sent
+ * verbatim); `::jsonb` then parses it into a real array/object. Read-side
+ * parsers repair rows written the old buggy way without a migration.
+ *
+ * Returns `null` for null/undefined and for "empty" values (an empty array, or
+ * an object with no own enumerable keys) — callers treat empty as "clear/unset",
+ * so an empty allowlist/config never round-trips as `[]`/`{}`.
+ */
+export function jsonbBind<T>(
+  value: T | null | undefined,
+): RawBuilder<T> | null {
+  if (value === null || value === undefined) return null;
+  if (Array.isArray(value)) {
+    if (value.length === 0) return null;
+  } else if (typeof value === 'object') {
+    if (Object.keys(value as object).length === 0) return null;
+  }
+  return sql<T>`${JSON.stringify(value)}::text::jsonb`;
+}

apps/server/src/integrations/ai/ai-provider-http.spec.ts

@@ -0,0 +1,40 @@
+import { createInstrumentedFetch } from './ai-provider-http';
+
+/**
+ * createInstrumentedFetch must be behavior-neutral: it delegates to the supplied
+ * baseFetch with the SAME input/init, returns the Response object untouched (so
+ * the streamed SSE body is never read/cloned), and rethrows the same error. The
+ * baseFetch injection is the seam that carries the streaming fetch (#175) onto
+ * the chat provider, so it is tested directly.
+ */
+describe('createInstrumentedFetch', () => {
+  it('delegates to the injected baseFetch with the same input/init', async () => {
+    const fakeResponse = new Response('ok', { status: 200 });
+    const baseFetch = jest.fn().mockResolvedValue(fakeResponse);
+    const instrumented = createInstrumentedFetch('test', baseFetch as never);
+
+    const init = { method: 'POST', body: '{"q":1}' };
+    const res = await instrumented('https://example.com/v1/chat', init);
+
+    expect(baseFetch).toHaveBeenCalledTimes(1);
+    expect(baseFetch).toHaveBeenCalledWith('https://example.com/v1/chat', init);
+    // The Response is returned UNTOUCHED (same reference — never read/cloned).
+    expect(res).toBe(fakeResponse);
+  });
+
+  it('rethrows the base fetch error unchanged (pre-response failure)', async () => {
+    const err = Object.assign(new TypeError('fetch failed'), {
+      cause: { code: 'ECONNRESET' },
+    });
+    const baseFetch = jest.fn().mockRejectedValue(err);
+    const instrumented = createInstrumentedFetch('test', baseFetch as never);
+
+    await expect(instrumented('https://example.com/')).rejects.toBe(err);
+  });
+
+  it('defaults to the global fetch when no baseFetch is given', () => {
+    // Constructing without a baseFetch must not throw — it simply wraps global
+    // fetch (the non-chat default).
+    expect(() => createInstrumentedFetch('test')).not.toThrow();
+  });
+});

apps/server/src/integrations/ai/ai-provider-http.ts

@@ -0,0 +1,87 @@
+import { Logger } from '@nestjs/common';
+
+/**
+ * The provider HTTP fetch used by the chat path: a thin, behavior-neutral
+ * instrumentation wrapper around a supplied `fetch`.
+ *
+ * It defaults to the global `fetch`, but the chat provider passes the streaming
+ * fetch (which RAISES undici's 300s stream timeouts to a generous-but-finite
+ * silence timeout so a long agent turn is not severed mid-stream — #175). So this
+ * wrapper observes the EXACT transport a turn uses. It NEVER retries, times out,
+ * swaps the dispatcher, or reads/clones the response body — the Response is
+ * returned untouched (streaming unaffected) and any error is rethrown unchanged.
+ *
+ * Per provider HTTP call it logs: time-to-response-headers + status + request
+ * body size on success; and on a pre-response rejection the failure latency +
+ * error code/cause + request body size + the idle gap since the previous call.
+ * This telemetry is intentional and kept (it diagnoses provider connection
+ * resets / mid-stream cuts), and it is load-bearing: the streaming fetch reaches
+ * the chat provider THROUGH this wrapper, so the two are one construct.
+ *
+ * How to read the result (a long agentic turn makes one provider call per step):
+ *  - a failed turn whose last provider line is "PRE-RESPONSE FAILED ... ECONNRESET"
+ *    => the reset is in the CONNECTION phase of a step's request (the provider
+ *    never replied) — usually a poisoned keep-alive socket or the provider/middle
+ *    box resetting that request (large body / idle gap are the suspects, hence
+ *    reqBytes + idleSincePrevCall below).
+ *  - the last line is "OK status=200" and the turn still errors with NO
+ *    "PRE-RESPONSE FAILED" => the cut happened MID-STREAM (after headers), a
+ *    different failure mode.
+ *
+ * The seq/last-call timestamps are module-level, so under concurrent turns the
+ * idle-gap figure is approximate (fine for single-user diagnosis).
+ */
+export function createInstrumentedFetch(
+  context: string,
+  // The underlying fetch to instrument. Defaults to the global fetch; the chat
+  // provider passes the streaming fetch (raised, finite undici stream timeouts,
+  // #175) so the telemetry observes the SAME transport the long agent turn uses.
+  baseFetch: typeof fetch = fetch,
+): typeof fetch {
+  const logger = new Logger(context);
+  let callSeq = 0;
+  let lastCallStartedAt: number | undefined;
+
+  return async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]): Promise<Response> => {
+    const callId = ++callSeq;
+    const startedAt = Date.now();
+    const idleSincePrev =
+      lastCallStartedAt === undefined ? undefined : startedAt - lastCallStartedAt;
+    lastCallStartedAt = startedAt;
+    // Request body size: the chat payload is a JSON string. Used to test whether
+    // failures correlate with the large accumulated context on later agent steps.
+    const body = init?.body as unknown;
+    const bodyBytes =
+      typeof body === 'string'
+        ? body.length
+        : body instanceof Uint8Array
+          ? body.byteLength
+          : undefined;
+    try {
+      // Delegate to the base fetch; return the Response UNTOUCHED (never read/
+      // clone the body) so the streamed SSE response is unaffected.
+      const res = await baseFetch(input, init);
+      logger.log(
+        `provider HTTP: call#${callId} OK ` +
+          `headersAfter=${Date.now() - startedAt}ms status=${res.status} ` +
+          `reqBytes=${bodyBytes ?? 'n/a'} idleSincePrevCall=${idleSincePrev ?? 'n/a'}ms`,
+      );
+      return res;
+    } catch (err) {
+      // fetch() rejected => PRE-RESPONSE failure (no headers/body received yet):
+      // the connection/request phase. Log it and rethrow the SAME error.
+      const e = err as {
+        name?: string;
+        message?: string;
+        cause?: { code?: string; message?: string };
+      };
+      logger.warn(
+        `provider HTTP: call#${callId} PRE-RESPONSE FAILED ` +
+          `after=${Date.now() - startedAt}ms code=${e?.cause?.code ?? 'none'} ` +
+          `name=${e?.name ?? 'Error'} cause=${e?.cause?.message ?? e?.message ?? 'unknown'} ` +
+          `reqBytes=${bodyBytes ?? 'n/a'} idleSincePrevCall=${idleSincePrev ?? 'n/a'}ms`,
+      );
+      throw err;
+    }
+  };
+}

apps/server/src/integrations/ai/ai-provider-settings-keys.spec.ts

@@ -0,0 +1,43 @@
+import { validate } from 'class-validator';
+import { plainToInstance } from 'class-transformer';
+import { PROVIDER_SETTINGS_KEYS } from './ai.types';
+import { AI_PROVIDER_SETTINGS_ALLOWED } from '@docmost/db/repos/workspace/workspace.repo';
+import { UpdateAiSettingsDto } from './dto/update-ai-settings.dto';
+
+/**
+ * Drift guard: the writable provider-settings keys are maintained in two layers
+ * that TypeScript cannot cross-check — PROVIDER_SETTINGS_KEYS (ai.types, used by
+ * the settings service) and AI_PROVIDER_SETTINGS_ALLOWED (the generic workspace
+ * repo's SQL boundary). A key missing from the repo copy silently drops the field
+ * on persist (exactly what happened to chatApiStyle), so this asserts they match.
+ */
+describe('provider-settings key allowlist parity', () => {
+  it('the repo SQL allowlist equals PROVIDER_SETTINGS_KEYS', () => {
+    expect([...AI_PROVIDER_SETTINGS_ALLOWED].sort()).toEqual(
+      [...PROVIDER_SETTINGS_KEYS].sort(),
+    );
+  });
+});
+
+/** DTO validation for the new chatApiStyle field (@IsIn(CHAT_API_STYLES)). */
+describe('UpdateAiSettingsDto.chatApiStyle', () => {
+  const errorsFor = async (chatApiStyle: unknown) =>
+    validate(plainToInstance(UpdateAiSettingsDto, { chatApiStyle }));
+
+  it('accepts both valid values', async () => {
+    for (const v of ['openai-compatible', 'openai']) {
+      const errs = await errorsFor(v);
+      expect(errs.find((e) => e.property === 'chatApiStyle')).toBeUndefined();
+    }
+  });
+
+  it('rejects an unknown value', async () => {
+    const errs = await errorsFor('definitely-not-a-style');
+    expect(errs.find((e) => e.property === 'chatApiStyle')).toBeDefined();
+  });
+
+  it('accepts the field being omitted (optional)', async () => {
+    const errs = await validate(plainToInstance(UpdateAiSettingsDto, {}));
+    expect(errs.find((e) => e.property === 'chatApiStyle')).toBeUndefined();
+  });
+});

apps/server/src/integrations/ai/ai-settings.service.ts

@@ -14,6 +14,8 @@ import {
   MaskedAiSettings,
   ResolvedAiConfig,
   SttApiStyle,
+  ChatApiStyle,
+  PROVIDER_SETTINGS_KEYS,
 } from './ai.types';
 
 /**
@@ -24,6 +26,7 @@ import {
 export interface UpdateAiSettingsInput {
   driver?: AiDriver;
   chatModel?: string;
+  chatApiStyle?: ChatApiStyle;
   embeddingModel?: string;
   baseUrl?: string;
   embeddingBaseUrl?: string;
@@ -157,6 +160,8 @@ export class AiSettingsService {
     const config: ResolvedAiConfig = {
       driver: provider.driver,
       chatModel: provider.chatModel,
+      // Plain passthrough; getChatModel defaults unset to 'openai-compatible'.
+      chatApiStyle: provider.chatApiStyle,
       // Cheap model id for the anonymous public-share assistant; reuses the chat
       // driver/baseUrl/apiKey. Empty/unset → callers fall back to chatModel.
       publicShareChatModel: provider.publicShareChatModel,
@@ -238,6 +243,7 @@ export class AiSettingsService {
     return {
       driver: provider.driver,
       chatModel: provider.chatModel,
+      chatApiStyle: provider.chatApiStyle,
       embeddingModel: provider.embeddingModel,
       baseUrl: provider.baseUrl,
       embeddingBaseUrl: provider.embeddingBaseUrl,
@@ -275,20 +281,8 @@ export class AiSettingsService {
 
     // Persist non-secret provider fields (only those present in the partial).
     const providerPatch: Partial<AiProviderSettings> = {};
-    for (const key of [
-      'driver',
-      'chatModel',
-      'embeddingModel',
-      'baseUrl',
-      'embeddingBaseUrl',
-      'sttModel',
-      'sttBaseUrl',
-      'sttApiStyle',
-      'sttLanguage',
-      'systemPrompt',
-      'publicShareChatModel',
-      'publicShareAssistantRoleId',
-    ] as const) {
+    // Single source of truth for the writable provider keys (see ai.types).
+    for (const key of PROVIDER_SETTINGS_KEYS) {
       if (nonSecret[key] !== undefined) {
         (providerPatch as Record<string, unknown>)[key] = nonSecret[key];
       }

apps/server/src/integrations/ai/ai-streaming-fetch.spec.ts

@@ -0,0 +1,235 @@
+import * as http from 'node:http';
+import {
+  createStreamingFetch,
+  withPreResponseRetry,
+  streamTimeoutMs,
+  streamKeepAliveMs,
+  streamingDispatcherOptions,
+  isRetryableConnectError,
+} from './ai-streaming-fetch';
+
+/**
+ * #175: undici's default 300s headers/body timeouts severed long agent turns.
+ * The streaming fetch raises them to a generous-but-FINITE silence timeout (not
+ * 0 — a true hang must still break). We pin: the configured value + env override,
+ * that both dispatcher timeouts use it, and that a delayed response streams.
+ */
+describe('streamTimeoutMs', () => {
+  const ORIG = process.env.AI_STREAM_TIMEOUT_MS;
+  afterEach(() => {
+    if (ORIG === undefined) delete process.env.AI_STREAM_TIMEOUT_MS;
+    else process.env.AI_STREAM_TIMEOUT_MS = ORIG;
+  });
+
+  it('defaults to a generous-but-finite 15 minutes', () => {
+    delete process.env.AI_STREAM_TIMEOUT_MS;
+    expect(streamTimeoutMs()).toBe(900_000);
+    // Finite — NOT disabled (0 would let a hung provider leak forever).
+    expect(streamTimeoutMs()).toBeGreaterThan(0);
+    expect(Number.isFinite(streamTimeoutMs())).toBe(true);
+  });
+
+  it('honours a positive AI_STREAM_TIMEOUT_MS override', () => {
+    process.env.AI_STREAM_TIMEOUT_MS = '120000';
+    expect(streamTimeoutMs()).toBe(120000);
+  });
+
+  it('ignores an invalid / non-positive override (falls back to default)', () => {
+    for (const bad of ['0', '-5', 'abc', '']) {
+      process.env.AI_STREAM_TIMEOUT_MS = bad;
+      expect(streamTimeoutMs()).toBe(900_000);
+    }
+  });
+
+  it('applies the silence timeout + keep-alive recycle window to the dispatcher', () => {
+    delete process.env.AI_STREAM_TIMEOUT_MS;
+    delete process.env.AI_STREAM_KEEPALIVE_MS;
+    expect(streamingDispatcherOptions()).toEqual({
+      headersTimeout: 900_000,
+      bodyTimeout: 900_000,
+      keepAliveTimeout: 10_000,
+      keepAliveMaxTimeout: 10_000,
+    });
+  });
+});
+
+describe('streamKeepAliveMs', () => {
+  const ORIG = process.env.AI_STREAM_KEEPALIVE_MS;
+  afterEach(() => {
+    if (ORIG === undefined) delete process.env.AI_STREAM_KEEPALIVE_MS;
+    else process.env.AI_STREAM_KEEPALIVE_MS = ORIG;
+  });
+
+  it('defaults to 10s (recycle idle sockets so a NAT/proxy drop cannot poison reuse)', () => {
+    delete process.env.AI_STREAM_KEEPALIVE_MS;
+    expect(streamKeepAliveMs()).toBe(10_000);
+  });
+
+  it('honours a positive override and ignores invalid/non-positive', () => {
+    process.env.AI_STREAM_KEEPALIVE_MS = '4000';
+    expect(streamKeepAliveMs()).toBe(4000);
+    for (const bad of ['0', '-1', 'x', '']) {
+      process.env.AI_STREAM_KEEPALIVE_MS = bad;
+      expect(streamKeepAliveMs()).toBe(10_000);
+    }
+  });
+});
+
+describe('isRetryableConnectError', () => {
+  it('matches connection-level codes on the error or its cause', () => {
+    expect(isRetryableConnectError({ cause: { code: 'ECONNRESET' } })).toBe(true);
+    expect(isRetryableConnectError({ cause: { code: 'UND_ERR_SOCKET' } })).toBe(true);
+    expect(isRetryableConnectError({ code: 'ECONNREFUSED' })).toBe(true);
+  });
+  it('does NOT match aborts / unrelated errors', () => {
+    expect(isRetryableConnectError({ name: 'AbortError', cause: { code: 'ABORT_ERR' } })).toBe(false);
+    expect(isRetryableConnectError({ cause: { code: 'UND_ERR_HEADERS_TIMEOUT' } })).toBe(false);
+    expect(isRetryableConnectError(new Error('plain'))).toBe(false);
+    expect(isRetryableConnectError(undefined)).toBe(false);
+  });
+});
+
+describe('createStreamingFetch — against a delayed server', () => {
+  const ORIG = process.env.AI_STREAM_TIMEOUT_MS;
+  let server: http.Server;
+  let url: string;
+  // The server waits before sending ANY byte (a long time-to-first-token). It is
+  // > undici's ~1s timeout-timer granularity so a sub-second configured timeout
+  // fires deterministically in the load-bearing test below.
+  const DELAY = 1500;
+
+  beforeAll(async () => {
+    server = http.createServer((_req, res) => {
+      setTimeout(() => {
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end('ok');
+      }, DELAY);
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const addr = server.address() as import('node:net').AddressInfo;
+    url = `http://127.0.0.1:${addr.port}/`;
+  });
+
+  afterAll(async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+
+  afterEach(() => {
+    if (ORIG === undefined) delete process.env.AI_STREAM_TIMEOUT_MS;
+    else process.env.AI_STREAM_TIMEOUT_MS = ORIG;
+  });
+
+  it('streams the delayed response at the default (generous) timeout', async () => {
+    delete process.env.AI_STREAM_TIMEOUT_MS; // default 15 min >> DELAY
+    const streamingFetch = createStreamingFetch();
+    const res = await streamingFetch(url);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe('ok');
+  });
+
+  it('LOAD-BEARING: a sub-DELAY AI_STREAM_TIMEOUT_MS actually severs the response', async () => {
+    // Proves the configured dispatcher is wired into the fetch: with the timeout
+    // set below DELAY the call must reject with undici's headers-timeout. If the
+    // dispatcher were lost (fallback to global fetch's 300s default), the 1.5s
+    // response would slip through and this would NOT throw.
+    process.env.AI_STREAM_TIMEOUT_MS = '500';
+    const streamingFetch = createStreamingFetch();
+    let caught: unknown;
+    const startedAt = Date.now();
+    try {
+      await streamingFetch(url).then((r) => r.text());
+    } catch (e) {
+      caught = e;
+    }
+    // It rejected (a lost dispatcher -> global 300s default would NOT reject on a
+    // 1.5s response) and it did so BEFORE the response would have arrived (DELAY).
+    // Use `.name` (realm-safe) — undici's TypeError fails cross-realm instanceof.
+    expect(caught).toBeDefined();
+    expect((caught as Error)?.name).toBe('TypeError');
+    expect(Date.now() - startedAt).toBeLessThan(DELAY);
+    // When present, the undici cause is the headers timeout.
+    const code = (caught as { cause?: { code?: string } })?.cause?.code;
+    if (code) expect(code).toBe('UND_ERR_HEADERS_TIMEOUT');
+  });
+});
+
+describe('withPreResponseRetry', () => {
+  // The retry is the OUTERMOST layer (over the dispatcher-bound streaming fetch),
+  // matching ai.service's withPreResponseRetry(instrument(createStreamingFetch())).
+  // PRE_RESPONSE_CONNECT_RETRIES is 2 -> at most 3 total attempts.
+  const MAX_ATTEMPTS = 3;
+  let server: http.Server;
+  let url: string;
+  let requests = 0;
+  // 'first' resets only the first connection; 'all' resets every connection.
+  let resetMode: 'first' | 'all' = 'first';
+
+  const retryingFetch = () => withPreResponseRetry(createStreamingFetch());
+
+  beforeAll(async () => {
+    server = http.createServer((req, res) => {
+      requests += 1;
+      const shouldReset = resetMode === 'all' || requests === 1;
+      if (shouldReset) {
+        // Reset before any response byte (a poisoned/stale keep-alive socket).
+        const sock = req.socket as import('node:net').Socket & {
+          resetAndDestroy?: () => void;
+        };
+        if (typeof sock.resetAndDestroy === 'function') sock.resetAndDestroy();
+        else sock.destroy();
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': 'text/plain' });
+      res.end('ok');
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const addr = server.address() as import('node:net').AddressInfo;
+    url = `http://127.0.0.1:${addr.port}/`;
+  });
+
+  afterAll(async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+
+  beforeEach(() => {
+    requests = 0;
+    resetMode = 'first';
+  });
+
+  it('retries a pre-response reset on a fresh connection and succeeds', async () => {
+    resetMode = 'first';
+    const res = await retryingFetch()(url);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe('ok');
+    // first request reset -> retry -> second request served.
+    expect(requests).toBe(2);
+  });
+
+  it('gives up after the retry bound and rethrows the original reset', async () => {
+    resetMode = 'all'; // every attempt resets -> retries exhaust
+    let caught: unknown;
+    try {
+      await retryingFetch()(url);
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeDefined();
+    // A retryable connection error reached the caller (not swallowed).
+    expect(isRetryableConnectError(caught)).toBe(true);
+    // Bounded: exactly PRE_RESPONSE_CONNECT_RETRIES + 1 attempts hit the server
+    // (pins both the limit and that the final error propagates — guards an
+    // off-by-one or an infinite loop).
+    expect(requests).toBe(MAX_ATTEMPTS);
+  });
+
+  it('does NOT retry an aborted request (no retry storm)', async () => {
+    resetMode = 'all';
+    const ctrl = new AbortController();
+    ctrl.abort();
+    await expect(
+      retryingFetch()(url, { signal: ctrl.signal }),
+    ).rejects.toBeDefined();
+    // Pre-aborted: the request never reached the server, so nothing was retried.
+    expect(requests).toBe(0);
+  });
+});

apps/server/src/integrations/ai/ai-streaming-fetch.ts

@@ -0,0 +1,197 @@
+import { Agent } from 'undici';
+
+/**
+ * Default SILENCE timeout for streaming AI calls (15 min). Generous, but FINITE.
+ *
+ * Node's global fetch (undici) defaults headersTimeout and bodyTimeout to
+ * 300_000ms, which severed legitimate long agent turns mid-stream — surfacing as
+ * "Lost connection to the AI provider" (#175): a late step with a huge context
+ * pushes the model's time-to-first-token past 5 min, or a reasoning model pauses
+ * >5 min between chunks. We do NOT disable the timeout (0) — that would let a
+ * genuinely hung provider, with the client still connected, hang forever
+ * (abortSignal only fires on client disconnect). Instead we raise it well above
+ * any realistic gap while keeping it finite so a true hang is eventually broken.
+ *
+ * This bounds SILENCE (time-to-first-byte and the gap BETWEEN chunks), NOT total
+ * turn duration — so an arbitrarily long turn that keeps streaming bytes is never
+ * cut; only a stream that goes quiet for longer than this is treated as a hang.
+ */
+const DEFAULT_STREAM_TIMEOUT_MS = 900_000;
+
+/**
+ * Default keep-alive recycle window (10s). A pooled connection idle longer than
+ * this is CLOSED rather than reused.
+ *
+ * Long agent turns leave gaps of tens of seconds between provider calls (one
+ * call per step; a crawl/search tool runs in between). A NAT / reverse proxy /
+ * conntrack in front of the deployment silently drops an idle connection after
+ * its own timeout; undici, not knowing, then reuses that dead socket and the
+ * next request fails PRE-RESPONSE with `read ECONNRESET` (#175 prod telemetry:
+ * the resets correlate with idleSincePrevCall ~42s, while a direct path to the
+ * provider does NOT reset). Recycling idle sockets well below such a drop window
+ * means a long-gap call opens a fresh connection instead of reusing a stale one.
+ * `keepAliveMaxTimeout` also caps a server-advertised keep-alive so the provider
+ * cannot push the reuse window back up.
+ */
+const DEFAULT_STREAM_KEEPALIVE_MS = 10_000;
+
+/**
+ * How many times to retry a PRE-RESPONSE connection failure (a reset/timeout
+ * before ANY response byte) on a fresh connection. Safe because `fetch()` only
+ * rejects before the Response resolves — a started stream is never replayed.
+ */
+const PRE_RESPONSE_CONNECT_RETRIES = 2;
+
+/** undici cause codes for a connection-level failure that occurred PRE-RESPONSE. */
+const RETRYABLE_CONNECT_CODES = new Set([
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'EPIPE',
+  'ETIMEDOUT',
+  'UND_ERR_SOCKET',
+  'UND_ERR_CONNECT_TIMEOUT',
+]);
+
+function positiveEnv(name: string, fallback: number): number {
+  const raw = Number(process.env[name]);
+  return Number.isFinite(raw) && raw > 0 ? raw : fallback;
+}
+
+/**
+ * The configured silence timeout (ms). Override with `AI_STREAM_TIMEOUT_MS`; a
+ * missing/invalid/non-positive value falls back to {@link DEFAULT_STREAM_TIMEOUT_MS}.
+ */
+export function streamTimeoutMs(): number {
+  return positiveEnv('AI_STREAM_TIMEOUT_MS', DEFAULT_STREAM_TIMEOUT_MS);
+}
+
+/** Keep-alive recycle window (ms). Override with `AI_STREAM_KEEPALIVE_MS`. */
+export function streamKeepAliveMs(): number {
+  return positiveEnv('AI_STREAM_KEEPALIVE_MS', DEFAULT_STREAM_KEEPALIVE_MS);
+}
+
+/** Default SILENCE timeout for EXTERNAL-MCP transport (5 min). */
+const DEFAULT_MCP_STREAM_TIMEOUT_MS = 300_000;
+
+/** Default total wall-clock cap for ONE external MCP tool call (15 min). */
+const DEFAULT_MCP_CALL_TIMEOUT_MS = 900_000;
+
+/**
+ * SILENCE timeout (ms) for EXTERNAL-MCP transport ONLY. Override with
+ * `AI_MCP_STREAM_TIMEOUT_MS`; a missing/invalid/non-positive value falls back to
+ * {@link DEFAULT_MCP_STREAM_TIMEOUT_MS} (5 min).
+ *
+ * Deliberately tighter than the chat provider's {@link streamTimeoutMs} (15 min)
+ * so a byte-silent/hung MCP upstream is broken in ~5 min instead of 15. This is
+ * the undici `headersTimeout`/`bodyTimeout` for the external-MCP dispatcher only
+ * — it must NOT change the chat provider, which legitimately needs 15 min between
+ * reasoning chunks (#175).
+ *
+ * Trade-off: a legitimately long but byte-silent single tool call (a slow crawl
+ * that emits nothing until done) and an SSE transport that idles >5 min BETWEEN
+ * tool calls are also cut here. The per-call total cap ({@link mcpCallTimeoutMs},
+ * applied in mcp-clients.service) is the complementary guard for chatty-but-stuck
+ * calls that keep the socket warm yet never return.
+ */
+export function mcpStreamTimeoutMs(): number {
+  return positiveEnv('AI_MCP_STREAM_TIMEOUT_MS', DEFAULT_MCP_STREAM_TIMEOUT_MS);
+}
+
+/**
+ * Total wall-clock cap (ms) for ONE external MCP tool call — APP-LEVEL, not
+ * transport. Override with `AI_MCP_CALL_TIMEOUT_MS`; a missing/invalid/
+ * non-positive value falls back to {@link DEFAULT_MCP_CALL_TIMEOUT_MS} (15 min).
+ *
+ * Catches a tool that keeps the connection warm (SSE heartbeats / trickle) but
+ * never returns a result — which the transport silence timeout
+ * ({@link mcpStreamTimeoutMs}) would never break because the socket never goes
+ * byte-silent.
+ */
+export function mcpCallTimeoutMs(): number {
+  return positiveEnv('AI_MCP_CALL_TIMEOUT_MS', DEFAULT_MCP_CALL_TIMEOUT_MS);
+}
+
+/**
+ * undici `Agent` options for streaming AI traffic — the (generous, finite)
+ * silence timeouts plus the keep-alive recycle window. Shared by the chat
+ * provider fetch and the external-MCP dispatcher so they behave identically.
+ */
+export function streamingDispatcherOptions(): {
+  headersTimeout: number;
+  bodyTimeout: number;
+  keepAliveTimeout: number;
+  keepAliveMaxTimeout: number;
+} {
+  const t = streamTimeoutMs();
+  const ka = streamKeepAliveMs();
+  return {
+    headersTimeout: t,
+    bodyTimeout: t,
+    keepAliveTimeout: ka,
+    keepAliveMaxTimeout: ka,
+  };
+}
+
+/** True for a connection-level error worth retrying on a fresh connection. */
+export function isRetryableConnectError(err: unknown): boolean {
+  const e = err as { code?: string; cause?: { code?: string } } | undefined;
+  const code = e?.cause?.code ?? e?.code;
+  return typeof code === 'string' && RETRYABLE_CONNECT_CODES.has(code);
+}
+
+/**
+ * Build a `fetch` for long-lived streaming AI calls (the agent chat turn) backed
+ * by a dedicated undici dispatcher (finite silence timeouts + keep-alive
+ * recycling, #175). A single shared dispatcher is returned (callers hold it for
+ * the service lifetime) so its connection pool is reused.
+ *
+ * This is the BASE transport — no retry. The chat path wraps it as
+ * `withPreResponseRetry(createInstrumentedFetch(ctx, createStreamingFetch()))`
+ * so the retry is the OUTERMOST layer and the instrumentation observes EVERY
+ * attempt (a recovered reset is still logged — see withPreResponseRetry).
+ */
+export function createStreamingFetch(): typeof fetch {
+  const dispatcher = new Agent(streamingDispatcherOptions());
+  return ((input: Parameters<typeof fetch>[0], init?: RequestInit) =>
+    fetch(input, {
+      ...(init ?? {}),
+      // `dispatcher` is an undici-specific init field (not in the DOM
+      // RequestInit type); Node's global fetch reads it. Cast to satisfy it.
+      dispatcher,
+    } as RequestInit & { dispatcher: Agent })) as typeof fetch;
+}
+
+/**
+ * Wrap a fetch so a PRE-RESPONSE connection reset (`baseFetch` rejects before the
+ * Response resolves — so nothing has streamed) is retried a few times on a fresh
+ * connection (#175). A poisoned keep-alive socket is destroyed by undici on the
+ * reset, so the retry lands on a new connection. An abort (client disconnect) is
+ * never retried.
+ *
+ * This is the OUTERMOST transport layer by design: composing it as
+ * `withPreResponseRetry(instrumentedFetch)` means every attempt — including the
+ * resets that the retry recovers from — flows through the instrumentation, so the
+ * "PRE-RESPONSE FAILED ... ECONNRESET ... idleSincePrevCall" telemetry stays
+ * visible precisely when the fix is working (and AI_STREAM_KEEPALIVE_MS can be
+ * tuned from real data). A retry INSIDE the transport would hide it.
+ */
+export function withPreResponseRetry(baseFetch: typeof fetch): typeof fetch {
+  return (async (input: Parameters<typeof fetch>[0], init?: RequestInit) => {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await baseFetch(input, init);
+      } catch (err) {
+        const aborted = init?.signal?.aborted === true;
+        if (
+          aborted ||
+          attempt >= PRE_RESPONSE_CONNECT_RETRIES ||
+          !isRetryableConnectError(err)
+        ) {
+          throw err;
+        }
+        // Brief backoff before the fresh-connection retry.
+        await new Promise((resolve) => setTimeout(resolve, 150 * (attempt + 1)));
+      }
+    }
+  }) as typeof fetch;
+}

apps/server/src/integrations/ai/ai.service.include-usage.spec.ts

@@ -0,0 +1,58 @@
+// `.provider` alone cannot prove the openai-compatible factory was called with
+// `includeUsage: true` — a regression dropping it (which zeroes streamed token
+// usage / reasoning-token metadata) would still pass. So mock the factory and
+// assert the exact args. jest.mock is module-scoped, hence a dedicated file.
+
+const mockCompatibleModel = { provider: 'openai-compatible.chat', modelId: 'm' };
+// jest allows `mock`-prefixed vars inside a jest.mock factory.
+const mockCreateOpenAICompatible = jest.fn(
+  (_settings: unknown) => () => mockCompatibleModel,
+);
+
+jest.mock('@ai-sdk/openai-compatible', () => ({
+  createOpenAICompatible: (settings: unknown) =>
+    mockCreateOpenAICompatible(settings),
+}));
+
+import { AiService } from './ai.service';
+
+describe('AiService.getChatModel openai-compatible factory args', () => {
+  function serviceWith(chatApiStyle?: 'openai-compatible' | 'openai') {
+    const aiSettings = {
+      resolve: jest.fn().mockResolvedValue({
+        driver: 'openai',
+        chatModel: 'glm-5.2',
+        apiKey: 'the-key',
+        baseUrl: 'https://api.z.ai/v4',
+        chatApiStyle,
+      }),
+    };
+    return new AiService(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      aiSettings as any,
+      { find: jest.fn() } as never,
+      { decryptSecret: jest.fn() } as never,
+    );
+  }
+
+  beforeEach(() => mockCreateOpenAICompatible.mockClear());
+
+  it('passes includeUsage:true plus baseURL/apiKey/fetch (default style)', async () => {
+    await serviceWith().getChatModel('ws-1'); // unset -> openai-compatible
+    expect(mockCreateOpenAICompatible).toHaveBeenCalledTimes(1);
+    expect(mockCreateOpenAICompatible).toHaveBeenCalledWith(
+      expect.objectContaining({
+        name: 'openai-compatible',
+        baseURL: 'https://api.z.ai/v4',
+        apiKey: 'the-key',
+        includeUsage: true,
+        fetch: expect.any(Function),
+      }),
+    );
+  });
+
+  it("does NOT use the openai-compatible factory for chatApiStyle 'openai'", async () => {
+    await serviceWith('openai').getChatModel('ws-1');
+    expect(mockCreateOpenAICompatible).not.toHaveBeenCalled();
+  });
+});

apps/server/src/integrations/ai/ai.service.spec.ts

@@ -285,3 +285,64 @@ describe('AiService.getChatModel role model override', () => {
     );
   });
 });
+
+/**
+ * Chat provider selection by the EXPLICIT `chatApiStyle` (NOT inferred from
+ * baseUrl): 'openai-compatible' (default) uses @ai-sdk/openai-compatible, which
+ * maps streamed reasoning_content to reasoning parts; 'openai' uses the official
+ * provider; and openai-compatible without a baseURL safely falls back to the
+ * official provider (it has no default endpoint). Asserted via `.provider`.
+ */
+describe('AiService.getChatModel chatApiStyle provider selection', () => {
+  function serviceWith(opts: {
+    baseUrl?: string;
+    chatApiStyle?: 'openai-compatible' | 'openai';
+  }) {
+    const aiSettings = {
+      resolve: jest.fn().mockResolvedValue({
+        driver: 'openai',
+        chatModel: 'glm-5.2',
+        apiKey: 'key',
+        baseUrl: opts.baseUrl,
+        chatApiStyle: opts.chatApiStyle,
+      }),
+    };
+    return new AiService(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      aiSettings as any,
+      { find: jest.fn() } as never,
+      { decryptSecret: jest.fn() } as never,
+    );
+  }
+
+  const providerOf = async (svc: AiService) =>
+    (
+      (await svc.getChatModel('ws-1')) as { provider: string }
+    ).provider;
+
+  it("'openai-compatible' + baseURL -> openai-compatible provider", async () => {
+    expect(
+      await providerOf(
+        serviceWith({ baseUrl: 'https://api.z.ai/v4', chatApiStyle: 'openai-compatible' }),
+      ),
+    ).toContain('openai-compatible');
+  });
+
+  it("'openai' + baseURL -> official openai provider", async () => {
+    expect(
+      await providerOf(serviceWith({ baseUrl: 'https://api.z.ai/v4', chatApiStyle: 'openai' })),
+    ).toBe('openai.chat');
+  });
+
+  it('unset + baseURL -> defaults to openai-compatible', async () => {
+    expect(
+      await providerOf(serviceWith({ baseUrl: 'https://api.z.ai/v4' })),
+    ).toContain('openai-compatible');
+  });
+
+  it("'openai-compatible' WITHOUT baseURL -> safe fallback to official openai", async () => {
+    expect(
+      await providerOf(serviceWith({ chatApiStyle: 'openai-compatible' })),
+    ).toBe('openai.chat');
+  });
+});

apps/server/src/integrations/ai/ai.service.ts

@@ -7,6 +7,7 @@ import {
   type LanguageModel,
 } from 'ai';
 import { createOpenAI } from '@ai-sdk/openai';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
 import { createGoogleGenerativeAI } from '@ai-sdk/google';
 import { createOllama } from 'ai-sdk-ollama';
 import { AiSettingsService } from './ai-settings.service';
@@ -14,6 +15,11 @@ import { AiNotConfiguredException } from './ai-not-configured.exception';
 import { AiEmbeddingNotConfiguredException } from './ai-embedding-not-configured.exception';
 import { AiSttNotConfiguredException } from './ai-stt-not-configured.exception';
 import { describeProviderError } from './ai-error.util';
+import { createInstrumentedFetch } from './ai-provider-http';
+import {
+  createStreamingFetch,
+  withPreResponseRetry,
+} from './ai-streaming-fetch';
 import { AiProviderCredentialsRepo } from '@docmost/db/repos/ai-chat/ai-provider-credentials.repo';
 import { SecretBoxService } from '../crypto/secret-box';
 import { AiDriver } from './ai.types';
@@ -43,6 +49,17 @@ export interface ChatModelOverride {
 export class AiService {
   private readonly logger = new Logger(AiService.name);
 
+  // Provider HTTP fetch for the chat path, layered so each transport concern is
+  // observed (#175). Inside-out: the streaming fetch (finite silence timeouts +
+  // keep-alive recycling) → provider-HTTP instrumentation (logs every attempt) →
+  // pre-response connection-reset retry as the OUTERMOST layer. Retry-outer means
+  // a reset the retry recovers from is still logged with its idle-gap, instead of
+  // collapsing into a clean "OK". Held for the service lifetime to reuse the
+  // streaming dispatcher's connection pool.
+  private readonly aiProviderFetch = withPreResponseRetry(
+    createInstrumentedFetch('AiService:provider-http', createStreamingFetch()),
+  );
+
   constructor(
     private readonly aiSettings: AiSettingsService,
     private readonly aiProviderCredentialsRepo: AiProviderCredentialsRepo,
@@ -83,6 +100,10 @@ export class AiService {
 
     let apiKey = cfg.apiKey;
     let baseUrl = cfg.baseUrl;
+    // Chat provider implementation, chosen EXPLICITLY by the admin (not inferred
+    // from baseUrl). Unset → 'openai-compatible' so reasoning is surfaced by
+    // default for this fork's openai+baseUrl setups.
+    const chatApiStyle = cfg.chatApiStyle ?? 'openai-compatible';
 
     // A driver override that differs from the workspace driver needs that
     // driver's own creds (the workspace driver's key would be wrong/absent).
@@ -133,14 +154,41 @@ export class AiService {
     }
 
     switch (driver) {
-      case 'openai':
-        // baseURL (when set) covers openai-compatible endpoints. Use Chat
-        // Completions (/chat/completions) — the portable OpenAI-compatible
-        // endpoint. The default callable createOpenAI(...)(model) targets the
-        // Responses API (/responses), which OpenAI-compatible gateways
-        // (OpenRouter, etc.) reject on multi-turn requests (history with
-        // assistant messages) → 400.
-        return createOpenAI({ apiKey, baseURL: baseUrl }).chat(chatModel);
+      case 'openai': {
+        // The provider implementation is chosen by the admin's `chatApiStyle`
+        // (NOT inferred from baseUrl — a custom URL can front real OpenAI too).
+        // Both branches hit Chat Completions (/chat/completions); the provider
+        // fetch is the instrumented streaming fetch (finite-but-generous stream
+        // timeouts, #175).
+        //
+        // 'openai-compatible' (default) maps the third-party provider's streamed
+        // `reasoning_content` to reasoning parts (z.ai/GLM, DeepSeek, ...) — the
+        // point of #175. It has no default endpoint, so it requires a baseURL;
+        // when there is none (real OpenAI, or a role's cross-driver override that
+        // cleared baseUrl) we fall back to the official provider.
+        if (chatApiStyle === 'openai-compatible' && baseUrl) {
+          return createOpenAICompatible({
+            name: 'openai-compatible',
+            apiKey,
+            baseURL: baseUrl,
+            // Keep streamed token usage (stream_options.include_usage): without
+            // it @ai-sdk/openai-compatible omits usage, zeroing the live token
+            // counter and reasoning-token metadata. The official provider always
+            // sent it, so this preserves parity.
+            includeUsage: true,
+            fetch: this.aiProviderFetch,
+          })(chatModel);
+        }
+        // Official @ai-sdk/openai: real-OpenAI reasoning-model request shaping;
+        // `.chat()` targets Chat Completions (the default callable targets the
+        // Responses API, which openai-compatible gateways 400 on multi-turn
+        // history). In this fork baseUrl is normally set; undefined = real OpenAI.
+        return createOpenAI({
+          apiKey,
+          baseURL: baseUrl,
+          fetch: this.aiProviderFetch,
+        }).chat(chatModel);
+      }
       case 'gemini':
         return createGoogleGenerativeAI({ apiKey })(chatModel);
       case 'ollama':

apps/server/src/integrations/ai/ai.types.ts

@@ -16,6 +16,15 @@ export const AI_DRIVERS: AiDriver[] = ['openai', 'gemini', 'ollama'];
 export type SttApiStyle = 'multipart' | 'json';
 export const STT_API_STYLES: SttApiStyle[] = ['multipart', 'json'];
 
+// Chat provider implementation for the `openai` driver. Chosen explicitly by the
+// admin (NOT inferred from baseUrl — a custom URL can front real OpenAI too).
+// 'openai-compatible' = @ai-sdk/openai-compatible: maps streamed
+//   `reasoning_content` to reasoning parts (z.ai/GLM, DeepSeek, OpenRouter, ...).
+// 'openai' = official @ai-sdk/openai: real-OpenAI reasoning-model request shaping
+//   (max_completion_tokens, the 'developer' role), no third-party reasoning map.
+export type ChatApiStyle = 'openai-compatible' | 'openai';
+export const CHAT_API_STYLES: ChatApiStyle[] = ['openai-compatible', 'openai'];
+
 /**
  * Non-secret provider settings persisted under `settings.ai.provider`.
  * The API key is intentionally absent here.
@@ -23,6 +32,9 @@ export const STT_API_STYLES: SttApiStyle[] = ['multipart', 'json'];
 export interface AiProviderSettings {
   driver: AiDriver;
   chatModel: string;
+  // Chat provider implementation for the `openai` driver. Unset → defaults to
+  // 'openai-compatible' (so reasoning is surfaced by default). See ChatApiStyle.
+  chatApiStyle?: ChatApiStyle;
   embeddingModel?: string;
   baseUrl?: string;
   // Embedding-specific base URL. Falls back to `baseUrl` when empty/unset.
@@ -45,6 +57,34 @@ export interface AiProviderSettings {
   publicShareAssistantRoleId?: string;
 }
 
+/**
+ * The persisted, non-secret provider setting keys — the SINGLE source of truth
+ * for which fields a settings update may write through to `settings.ai.provider`.
+ * `satisfies readonly (keyof AiProviderSettings)[]` makes the compiler reject a
+ * typo or a key that is not a real provider setting.
+ *
+ * The settings service consumes this directly. The generic workspace repo cannot
+ * import AI types, so it keeps its own copy of the same keys, guarded by a parity
+ * test against this constant (so any future drift fails in CI, not silently in
+ * prod — a missing key there validates fine, passes the service, and is then
+ * dropped at the SQL boundary with no error).
+ */
+export const PROVIDER_SETTINGS_KEYS = [
+  'driver',
+  'chatModel',
+  'chatApiStyle',
+  'embeddingModel',
+  'baseUrl',
+  'embeddingBaseUrl',
+  'sttModel',
+  'sttBaseUrl',
+  'sttApiStyle',
+  'sttLanguage',
+  'systemPrompt',
+  'publicShareChatModel',
+  'publicShareAssistantRoleId',
+] as const satisfies readonly (keyof AiProviderSettings)[];
+
 /**
  * Fully resolved provider config, including the decrypted API key for the
  * stored driver. Returned by `AiSettingsService.resolve`. The keys are held in
@@ -76,6 +116,7 @@ export interface ResolvedAiConfig extends Partial<AiProviderSettings> {
 export interface MaskedAiSettings {
   driver?: AiDriver;
   chatModel?: string;
+  chatApiStyle?: ChatApiStyle;
   embeddingModel?: string;
   baseUrl?: string;
   embeddingBaseUrl?: string;

apps/server/src/integrations/ai/dto/update-ai-settings.dto.ts

@@ -1,5 +1,12 @@
 import { IsIn, IsOptional, IsString } from 'class-validator';
-import { AI_DRIVERS, AiDriver, STT_API_STYLES, SttApiStyle } from '../ai.types';
+import {
+  AI_DRIVERS,
+  AiDriver,
+  CHAT_API_STYLES,
+  ChatApiStyle,
+  STT_API_STYLES,
+  SttApiStyle,
+} from '../ai.types';
 
 /**
  * Admin update payload for the workspace AI provider settings.
@@ -18,6 +25,10 @@ export class UpdateAiSettingsDto {
   @IsString()
   chatModel?: string;
 
+  @IsOptional()
+  @IsIn(CHAT_API_STYLES)
+  chatApiStyle?: ChatApiStyle;
+
   @IsOptional()
   @IsString()
   embeddingModel?: string;

apps/server/test/integration/ai-agent-roles-repo.int-spec.ts

@@ -1,4 +1,5 @@
-import { Kysely } from 'kysely';
+import { Kysely, sql } from 'kysely';
+import { randomUUID } from 'node:crypto';
 import { AiAgentRoleRepo } from '@docmost/db/repos/ai-agent-roles/ai-agent-roles.repo';
 import { getTestDb, destroyTestDb, createWorkspace } from './db';
 
@@ -25,8 +26,16 @@ describe('AiAgentRoleRepo isolation + partial unique index [integration]', () =>
   });
 
   it('findById / listByWorkspace exclude soft-deleted rows', async () => {
-    const live = await repo.insert({ workspaceId: w1, name: 'Live', instructions: 'x' });
-    const dead = await repo.insert({ workspaceId: w1, name: 'Dead', instructions: 'x' });
+    const live = await repo.insert({
+      workspaceId: w1,
+      name: 'Live',
+      instructions: 'x',
+    });
+    const dead = await repo.insert({
+      workspaceId: w1,
+      name: 'Dead',
+      instructions: 'x',
+    });
     await repo.softDelete(dead.id, w1);
 
     expect(await repo.findById(live.id, w1)).toBeDefined();
@@ -38,7 +47,11 @@ describe('AiAgentRoleRepo isolation + partial unique index [integration]', () =>
   });
 
   it('findById of a W2 role from W1 context returns undefined (tenant isolation)', async () => {
-    const w2role = await repo.insert({ workspaceId: w2, name: 'W2Role', instructions: 'x' });
+    const w2role = await repo.insert({
+      workspaceId: w2,
+      name: 'W2Role',
+      instructions: 'x',
+    });
 
     expect(await repo.findById(w2role.id, w2)).toBeDefined();
     // Same id, wrong workspace context -> not visible.
@@ -58,21 +71,100 @@ describe('AiAgentRoleRepo isolation + partial unique index [integration]', () =>
   });
 
   it('same name is reusable after softDelete (partial unique index WHERE deleted_at IS NULL)', async () => {
-    const first = await repo.insert({ workspaceId: w1, name: 'Reusable', instructions: 'x' });
+    const first = await repo.insert({
+      workspaceId: w1,
+      name: 'Reusable',
+      instructions: 'x',
+    });
     await repo.softDelete(first.id, w1);
 
     // Now inserting the same name must succeed because the soft-deleted row is
     // excluded from the partial unique index.
-    const second = await repo.insert({ workspaceId: w1, name: 'Reusable', instructions: 'x' });
+    const second = await repo.insert({
+      workspaceId: w1,
+      name: 'Reusable',
+      instructions: 'x',
+    });
     expect(second.id).toBeDefined();
     expect(second.id).not.toBe(first.id);
   });
 
   it('same name in W1 and W2 is allowed (unique is per-workspace)', async () => {
-    const a = await repo.insert({ workspaceId: w1, name: 'CrossTenant', instructions: 'x' });
-    const b = await repo.insert({ workspaceId: w2, name: 'CrossTenant', instructions: 'x' });
+    const a = await repo.insert({
+      workspaceId: w1,
+      name: 'CrossTenant',
+      instructions: 'x',
+    });
+    const b = await repo.insert({
+      workspaceId: w2,
+      name: 'CrossTenant',
+      instructions: 'x',
+    });
     expect(a.id).toBeDefined();
     expect(b.id).toBeDefined();
     expect(a.id).not.toBe(b.id);
   });
+
+  // model_config jsonb round-trip (issue #173 §1): the same double-encoding bug
+  // PR #172 fixed for tool_allowlist lived in jsonbObject. A DB round-trip is the
+  // only way to observe it — the write must land as a real jsonb OBJECT, and a
+  // legacy string-scalar row must self-heal on read (else the model override is
+  // silently dropped and the role falls back to the default model).
+  const jsonbTypeof = async (id: string): Promise<string | null> => {
+    const res = await sql<{ t: string | null }>`
+      SELECT jsonb_typeof(model_config) AS t
+      FROM ai_agent_roles WHERE id = ${id}
+    `.execute(db);
+    return res.rows[0]?.t ?? null;
+  };
+
+  it('insert stores model_config as a jsonb OBJECT and reads it back as an object', async () => {
+    const role = await repo.insert({
+      workspaceId: w1,
+      name: `Model-${randomUUID()}`,
+      instructions: 'x',
+      modelConfig: { driver: 'gemini', chatModel: 'gemini-2.0-flash' },
+    });
+    expect(await jsonbTypeof(role.id)).toBe('object');
+    // The returned row is already normalized to an object.
+    expect(role.modelConfig).toEqual({
+      driver: 'gemini',
+      chatModel: 'gemini-2.0-flash',
+    });
+    const found = await repo.findById(role.id, w1);
+    expect(found?.modelConfig).toEqual({
+      driver: 'gemini',
+      chatModel: 'gemini-2.0-flash',
+    });
+  });
+
+  it('an empty model_config is normalized to null (no override)', async () => {
+    const role = await repo.insert({
+      workspaceId: w1,
+      name: `Empty-${randomUUID()}`,
+      instructions: 'x',
+      modelConfig: {},
+    });
+    // The column is SQL NULL, so jsonb_typeof returns SQL NULL (JS null).
+    expect(await jsonbTypeof(role.id)).toBeNull();
+    expect((await repo.findById(role.id, w1))?.modelConfig).toBeNull();
+  });
+
+  it('repairs a legacy double-encoded (string scalar) model_config on read', async () => {
+    const id = randomUUID();
+    // Seed the corrupt string-scalar shape the old `::jsonb` bind produced.
+    await sql`
+      INSERT INTO ai_agent_roles (id, workspace_id, name, instructions, model_config)
+      VALUES (
+        ${id}, ${w1}, ${`Legacy-${id}`}, 'x',
+        to_jsonb(${'{"driver":"openai","chatModel":"gpt"}'}::text)
+      )
+    `.execute(db);
+    expect(await jsonbTypeof(id)).toBe('string'); // sanity: really corrupt
+
+    expect((await repo.findById(id, w1))?.modelConfig).toEqual({
+      driver: 'openai',
+      chatModel: 'gpt',
+    });
+  });
 });

apps/server/test/integration/ai-mcp-server-repo.int-spec.ts

@@ -0,0 +1,175 @@
+import { Kysely, sql } from 'kysely';
+import { randomUUID } from 'node:crypto';
+import { AiMcpServerRepo } from '@docmost/db/repos/ai-chat/ai-mcp-server.repo';
+import { getTestDb, destroyTestDb, createWorkspace } from './db';
+
+/**
+ * AiMcpServerRepo `tool_allowlist` jsonb round-trip (PR #172 / issue #173 §3).
+ *
+ * The fix under test is a DB round-trip, so a unit test cannot observe it: the
+ * write must land as a real jsonb ARRAY (not a double-encoded string scalar),
+ * and the read must repair any legacy string-scalar rows. The read-side
+ * `parseToolAllowlist` MASKS a write regression (it parses the string back), so
+ * without this integration check, reverting `::text::jsonb` to `::jsonb` would
+ * keep every unit test green while silently corrupting the column again.
+ */
+describe('AiMcpServerRepo tool_allowlist jsonb round-trip [integration]', () => {
+  let db: Kysely<any>;
+  let repo: AiMcpServerRepo;
+  let ws: string;
+
+  beforeAll(async () => {
+    db = getTestDb();
+    repo = new AiMcpServerRepo(db as any);
+    ws = (await createWorkspace(db)).id;
+  });
+
+  afterAll(async () => {
+    await destroyTestDb();
+  });
+
+  const jsonbTypeof = async (id: string): Promise<string | null> => {
+    const res = await sql<{ t: string | null }>`
+      SELECT jsonb_typeof(tool_allowlist) AS t
+      FROM ai_mcp_servers WHERE id = ${id}
+    `.execute(db);
+    return res.rows[0]?.t ?? null;
+  };
+
+  it('insert stores the allowlist as a jsonb ARRAY (not a string scalar)', async () => {
+    const row = await repo.insert({
+      workspaceId: ws,
+      name: `srv-${randomUUID()}`,
+      transport: 'http',
+      url: 'https://example.com/mcp',
+      toolAllowlist: ['search', 'crawl'],
+    });
+
+    // The column holds a real jsonb array — the whole point of ::text::jsonb.
+    expect(await jsonbTypeof(row.id)).toBe('array');
+
+    // And the read returns a genuine string[], not a JSON string.
+    const found = await repo.findById(row.id, ws);
+    expect(found?.toolAllowlist).toEqual(['search', 'crawl']);
+    expect(Array.isArray(found?.toolAllowlist)).toBe(true);
+  });
+
+  it('an empty allowlist is normalized to null (no restriction), not []', async () => {
+    const row = await repo.insert({
+      workspaceId: ws,
+      name: `srv-${randomUUID()}`,
+      transport: 'http',
+      url: 'https://example.com/mcp',
+      toolAllowlist: [],
+    });
+    // The column is SQL NULL, so jsonb_typeof returns SQL NULL (JS null).
+    expect(await jsonbTypeof(row.id)).toBeNull();
+    expect((await repo.findById(row.id, ws))?.toolAllowlist).toBeNull();
+  });
+
+  it('repairs a legacy double-encoded (string scalar) row on read (self-heal)', async () => {
+    // Seed a row whose tool_allowlist is a jsonb STRING SCALAR holding the JSON
+    // text — exactly what the old `::jsonb` double-encoding produced.
+    const id = randomUUID();
+    await sql`
+      INSERT INTO ai_mcp_servers (id, workspace_id, name, transport, url, tool_allowlist)
+      VALUES (
+        ${id}, ${ws}, ${`srv-${id}`}, 'http', 'https://example.com/mcp',
+        to_jsonb(${'["alpha","beta"]'}::text)
+      )
+    `.execute(db);
+
+    // Sanity: the seeded column really IS the corrupt string-scalar shape.
+    expect(await jsonbTypeof(id)).toBe('string');
+
+    // The repo read heals it back to a real string[].
+    expect((await repo.findById(id, ws))?.toolAllowlist).toEqual([
+      'alpha',
+      'beta',
+    ]);
+    const enabled = await repo.listEnabled(ws);
+    const healed = enabled.find((r) => r.id === id);
+    expect(healed?.toolAllowlist).toEqual(['alpha', 'beta']);
+  });
+});
+
+/**
+ * AiMcpServerRepo `instructions` text round-trip (#180). The column is plain
+ * text (no jsonb); blank/whitespace is normalized to null on both insert and
+ * update so an empty guide is never persisted.
+ */
+describe('AiMcpServerRepo instructions round-trip [integration]', () => {
+  let db: Kysely<any>;
+  let repo: AiMcpServerRepo;
+  let ws: string;
+
+  beforeAll(async () => {
+    db = getTestDb();
+    repo = new AiMcpServerRepo(db as any);
+    ws = (await createWorkspace(db)).id;
+  });
+
+  afterAll(async () => {
+    await destroyTestDb();
+  });
+
+  it('insert stores trimmed non-blank instructions and reads them back', async () => {
+    const row = await repo.insert({
+      workspaceId: ws,
+      name: `srv-${randomUUID()}`,
+      transport: 'http',
+      url: 'https://example.com/mcp',
+      instructions: '  Use search for fresh facts.  ',
+    });
+    expect((await repo.findById(row.id, ws))?.instructions).toBe(
+      'Use search for fresh facts.',
+    );
+  });
+
+  it('insert normalizes blank/whitespace instructions to null', async () => {
+    const row = await repo.insert({
+      workspaceId: ws,
+      name: `srv-${randomUUID()}`,
+      transport: 'http',
+      url: 'https://example.com/mcp',
+      instructions: '   ',
+    });
+    expect((await repo.findById(row.id, ws))?.instructions).toBeNull();
+  });
+
+  it('insert with omitted instructions stores null', async () => {
+    const row = await repo.insert({
+      workspaceId: ws,
+      name: `srv-${randomUUID()}`,
+      transport: 'http',
+      url: 'https://example.com/mcp',
+    });
+    expect((await repo.findById(row.id, ws))?.instructions).toBeNull();
+  });
+
+  it('update sets, clears (blank => null), and leaves unchanged when absent', async () => {
+    const row = await repo.insert({
+      workspaceId: ws,
+      name: `srv-${randomUUID()}`,
+      transport: 'http',
+      url: 'https://example.com/mcp',
+      instructions: 'initial guide',
+    });
+
+    // Set a new value.
+    await repo.update(row.id, ws, { instructions: 'updated guide' });
+    expect((await repo.findById(row.id, ws))?.instructions).toBe(
+      'updated guide',
+    );
+
+    // Absent in the patch => unchanged.
+    await repo.update(row.id, ws, { name: 'renamed' });
+    expect((await repo.findById(row.id, ws))?.instructions).toBe(
+      'updated guide',
+    );
+
+    // Blank => cleared to null.
+    await repo.update(row.id, ws, { instructions: '   ' });
+    expect((await repo.findById(row.id, ws))?.instructions).toBeNull();
+  });
+});

packages/editor-ext/src/lib/footnote/footnote-markdown.test.ts

@@ -55,10 +55,11 @@ describe("footnote markdown round-trip", () => {
     expect(html).not.toContain("data-footnote-def");
   });
 
-  it("extractFootnoteDefinitions de-duplicates colliding ids and rewrites markers", () => {
-    // Two definitions share id `d`, and the body has two `[^d]` markers. The
-    // output must keep BOTH definitions with DISTINCT ids and rewrite the second
-    // marker so the (reference, definition) pairing stays 1:1.
+  it("extractFootnoteDefinitions keeps the FIRST duplicate definition and reuses markers", () => {
+    // Two definitions share id `d`, and the body has two `[^d]` markers. Under
+    // the import model (#166) duplicate definition ids are FIRST-WINS: only the
+    // first definition is kept; markers are NEVER rewritten, so the two `[^d]`
+    // references reuse the single footnote.
     const md = [
       "See here[^d] and there[^d].",
       "",
@@ -68,30 +69,23 @@ describe("footnote markdown round-trip", () => {
 
     const { body, section } = extractFootnoteDefinitions(md);
 
-    // Pull out the def ids from the section in order.
     const defIds = Array.from(
       section.matchAll(/data-footnote-def data-id="([^"]+)"/g),
     ).map((m) => m[1]);
-    expect(defIds.length).toBe(2);
-    expect(new Set(defIds).size).toBe(2); // distinct
-    expect(defIds[0]).toBe("d"); // first definition keeps the id
-
-    // Both definition texts survive.
+    expect(defIds).toEqual(["d"]); // first-wins: one definition
     expect(section).toContain("first");
-    expect(section).toContain("second");
+    expect(section).not.toContain("second"); // duplicate dropped
 
-    // The body still has two markers, now pointing at the two distinct ids.
+    // Both markers stay `[^d]` (reuse) — no `d__2` minting.
     const refIds = Array.from(body.matchAll(/\[\^([^\]\s]+)\]/g)).map(
       (m) => m[1],
     );
-    expect(refIds.length).toBe(2);
-    expect(refIds.sort()).toEqual(defIds.sort());
+    expect(refIds).toEqual(["d", "d"]);
   });
 
-  it("extractFootnoteDefinitions dedups DETERMINISTICALLY (same input -> same ids)", () => {
-    // The derived id must be a pure function of the input markdown so importing
-    // the same source twice (or via the editor and the MCP mirror) yields
-    // identical ids — never random/time-based.
+  it("extractFootnoteDefinitions is DETERMINISTIC and stable (same input -> same output)", () => {
+    // The output must be a pure function of the input markdown so importing the
+    // same source twice (or via the editor and the MCP mirror) is identical.
     const md = [
       "See[^d] one[^d] two[^d].",
       "",
@@ -113,15 +107,13 @@ describe("footnote markdown round-trip", () => {
 
     const a = run();
     const b = run();
-    // Identical across runs (this is what would FAIL on the random-id version).
-    expect(a.defIds).toEqual(b.defIds);
-    expect(a.refIds).toEqual(b.refIds);
-    // Deterministic derived scheme: keeper "d", duplicates "d__2", "d__3".
-    expect(a.defIds).toEqual(["d", "d__2", "d__3"]);
-    expect(a.refIds.sort()).toEqual(a.defIds.sort());
+    expect(a).toEqual(b);
+    // First-wins: one kept definition `d`; all three reuse markers stay `d`.
+    expect(a.defIds).toEqual(["d"]);
+    expect(a.refIds).toEqual(["d", "d", "d"]);
   });
 
-  it("markdownToHtml with duplicate ids renders two distinct footnote defs", async () => {
+  it("markdownToHtml with a reused id renders ONE shared footnote def", async () => {
     const md = [
       "See here[^d] and there[^d].",
       "",
@@ -132,9 +124,8 @@ describe("footnote markdown round-trip", () => {
     const defIds = Array.from(
       html.matchAll(/data-footnote-def data-id="([^"]+)"/g),
     ).map((m) => m[1]);
-    expect(defIds.length).toBe(2);
-    expect(new Set(defIds).size).toBe(2);
+    expect(defIds).toEqual(["d"]); // one shared definition
     expect(html).toContain("first");
-    expect(html).toContain("second");
+    expect(html).not.toContain("second");
   });
 });

packages/editor-ext/src/lib/footnote/footnote-numbering.ts

@@ -1,14 +1,15 @@
-import { EditorState, Plugin, PluginKey } from "@tiptap/pm/state";
-import { Decoration, DecorationSet } from "@tiptap/pm/view";
-import { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { EditorState, Plugin, PluginKey } from '@tiptap/pm/state';
+import { Decoration, DecorationSet } from '@tiptap/pm/view';
+import { Node as ProseMirrorNode } from '@tiptap/pm/model';
 import {
   FOOTNOTE_DEFINITION_NAME,
   FOOTNOTE_REFERENCE_NAME,
   computeFootnoteNumbers,
-} from "./footnote-util";
+  computeFootnoteRefCounts,
+} from './footnote-util';
 
 export const footnoteNumberingPluginKey = new PluginKey<FootnoteNumberingState>(
-  "footnoteNumbering",
+  'footnoteNumbering',
 );
 
 /**
@@ -21,6 +22,9 @@ export const footnoteNumberingPluginKey = new PluginKey<FootnoteNumberingState>(
 interface FootnoteNumberingState {
   /** referenceId -> 1-based display number, for the current doc. */
   numbers: Map<string, number>;
+  /** referenceId -> number of reference occurrences (>= 1), for the definition's
+   *  multi-backlink UI (#168). */
+  refCounts: Map<string, number>;
   /** Decorations rendering those numbers (refs + definitions). */
   decorations: DecorationSet;
 }
@@ -46,6 +50,7 @@ function buildFootnoteNumberingState(
   doc: ProseMirrorNode,
 ): FootnoteNumberingState {
   const numbers = computeFootnoteNumbers(doc);
+  const refCounts = computeFootnoteRefCounts(doc);
   const decorations: Decoration[] = [];
 
   doc.descendants((node, pos) => {
@@ -54,7 +59,7 @@ function buildFootnoteNumberingState(
       if (num != null) {
         decorations.push(
           Decoration.node(pos, pos + node.nodeSize, {
-            "data-footnote-number": String(num),
+            'data-footnote-number': String(num),
             style: `--footnote-number: "${num}";`,
           }),
         );
@@ -65,7 +70,7 @@ function buildFootnoteNumberingState(
       if (num != null) {
         decorations.push(
           Decoration.node(pos, pos + node.nodeSize, {
-            "data-footnote-number": String(num),
+            'data-footnote-number': String(num),
             style: `--footnote-number: "${num}";`,
           }),
         );
@@ -73,7 +78,11 @@ function buildFootnoteNumberingState(
     }
   });
 
-  return { numbers, decorations: DecorationSet.create(doc, decorations) };
+  return {
+    numbers,
+    refCounts,
+    decorations: DecorationSet.create(doc, decorations),
+  };
 }
 
 /**
@@ -90,6 +99,16 @@ export function getFootnoteNumber(
   return footnoteNumberingPluginKey.getState(state)?.numbers.get(id);
 }
 
+/**
+ * Read the cached reference-occurrence count for `id` (how many `[^id]` links
+ * point at this definition). Drives the definition's multi-backlink UI (#168):
+ * `> 1` renders ↩ a b c …, each scrolling to its own occurrence. Returns 0 when
+ * the plugin is not installed or the id is unknown (caller treats as single).
+ */
+export function getFootnoteRefCount(state: EditorState, id: string): number {
+  return footnoteNumberingPluginKey.getState(state)?.refCounts.get(id) ?? 0;
+}
+
 /**
  * ProseMirror plugin that renders footnote numbers as decorations. It never
  * mutates the document (safe in read-only / share and in collaboration) — it

packages/editor-ext/src/lib/footnote/footnote-paste.test.ts

@@ -0,0 +1,226 @@
+import { describe, it, expect } from "vitest";
+import { Editor } from "@tiptap/core";
+import { Document } from "@tiptap/extension-document";
+import { Paragraph } from "@tiptap/extension-paragraph";
+import { Text } from "@tiptap/extension-text";
+import { Node as PMNode, Fragment, Slice } from "@tiptap/pm/model";
+import { FootnoteReference } from "./footnote-reference";
+import { FootnotesList } from "./footnotes-list";
+import { FootnoteDefinition } from "./footnote-definition";
+import { footnotePastePlugin } from "./footnote-sync";
+import {
+  FOOTNOTE_REFERENCE_NAME,
+  FOOTNOTE_DEFINITION_NAME,
+  FOOTNOTES_LIST_NAME,
+} from "./footnote-util";
+
+// transformPasted reuse semantics (#166): a pasted reference to an id that
+// already exists must KEEP the id (reuse → resolves to the existing footnote);
+// only a pasted DEFINITION that collides is re-id'd (it would otherwise clobber
+// the existing definition's text), and its paired references follow it.
+
+const extensions = [
+  Document,
+  Paragraph,
+  Text,
+  FootnoteReference,
+  FootnotesList,
+  FootnoteDefinition,
+];
+
+/** An editor whose doc already contains footnote "a" (ref + definition). */
+function makeEditorWithFootnoteA() {
+  return new Editor({
+    extensions,
+    content: {
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "x" },
+            { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: "a" } },
+          ],
+        },
+        {
+          type: FOOTNOTES_LIST_NAME,
+          content: [
+            {
+              type: FOOTNOTE_DEFINITION_NAME,
+              attrs: { id: "a" },
+              content: [
+                { type: "paragraph", content: [{ type: "text", text: "note A" }] },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  });
+}
+
+/** Run footnotePastePlugin's transformPasted against the editor's current doc. */
+function paste(editor: Editor, slice: Slice): Slice {
+  const plugin = footnotePastePlugin();
+  return plugin.props!.transformPasted!(slice, editor.view);
+}
+
+/** Collect the ids of footnote refs/defs in a slice, in order (single DFS). */
+function sliceFootnoteIds(slice: Slice): Array<{ kind: string; id: string }> {
+  const out: Array<{ kind: string; id: string }> = [];
+  const walk = (frag: Fragment) => {
+    frag.forEach((node: PMNode) => {
+      if (node.type.name === FOOTNOTE_REFERENCE_NAME)
+        out.push({ kind: "ref", id: node.attrs.id });
+      if (node.type.name === FOOTNOTE_DEFINITION_NAME)
+        out.push({ kind: "def", id: node.attrs.id });
+      walk(node.content);
+    });
+  };
+  walk(slice.content);
+  return out;
+}
+
+describe("footnotePastePlugin — reuse-aware id remap", () => {
+  it("keeps a pasted lone reference to an existing id (reuse, no remap)", () => {
+    const editor = makeEditorWithFootnoteA();
+    const { schema } = editor;
+    // Paste: a paragraph containing only a reference to the existing id "a".
+    const slice = new Slice(
+      Fragment.from(
+        schema.nodes.paragraph.create(null, [
+          schema.text("see "),
+          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "a" }),
+        ]),
+      ),
+      0,
+      0,
+    );
+    const out = paste(editor, slice);
+    // The reference keeps id "a" so it reuses the existing footnote.
+    expect(sliceFootnoteIds(out)).toEqual([{ kind: "ref", id: "a" }]);
+    editor.destroy();
+  });
+
+  it("re-ids a pasted DEFINITION (and its paired reference) that collides", () => {
+    const editor = makeEditorWithFootnoteA();
+    const { schema } = editor;
+    // Paste: a reference AND a definition both carrying the existing id "a". The
+    // definition would clobber the existing one, so both are remapped together.
+    const slice = new Slice(
+      Fragment.fromArray([
+        schema.nodes.paragraph.create(null, [
+          schema.text("dup "),
+          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "a" }),
+        ]),
+        schema.nodes[FOOTNOTES_LIST_NAME].create(null, [
+          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "a" }, [
+            schema.nodes.paragraph.create(null, [schema.text("pasted note")]),
+          ]),
+        ]),
+      ]),
+      0,
+      0,
+    );
+    const out = paste(editor, slice);
+    const ids = sliceFootnoteIds(out);
+    // Both the pasted ref and def were remapped to the SAME fresh id (paired),
+    // and it is the deterministic derived id (not "a").
+    const remappedIds = new Set(ids.map((x) => x.id));
+    expect(remappedIds.size).toBe(1);
+    expect(remappedIds.has("a")).toBe(false);
+    expect([...remappedIds][0]).toBe("a__2");
+    editor.destroy();
+  });
+
+  it("re-ids TWO colliding pasted definitions to DISTINCT ids (reservation works)", () => {
+    // Existing doc has footnotes "a" and "b". Paste a slice that defines BOTH —
+    // each must get its own fresh id; the reservation (existing.add(newId)) keeps
+    // the second from deriving onto the first's new id.
+    const editor = new Editor({
+      extensions,
+      content: {
+        type: "doc",
+        content: [
+          {
+            type: "paragraph",
+            content: [
+              { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: "a" } },
+              { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: "b" } },
+            ],
+          },
+          {
+            type: FOOTNOTES_LIST_NAME,
+            content: [
+              {
+                type: FOOTNOTE_DEFINITION_NAME,
+                attrs: { id: "a" },
+                content: [{ type: "paragraph", content: [{ type: "text", text: "A" }] }],
+              },
+              {
+                type: FOOTNOTE_DEFINITION_NAME,
+                attrs: { id: "b" },
+                content: [{ type: "paragraph", content: [{ type: "text", text: "B" }] }],
+              },
+            ],
+          },
+        ],
+      },
+    });
+    const { schema } = editor;
+    const slice = new Slice(
+      Fragment.fromArray([
+        schema.nodes.paragraph.create(null, [
+          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "a" }),
+          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "b" }),
+        ]),
+        schema.nodes[FOOTNOTES_LIST_NAME].create(null, [
+          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "a" }, [
+            schema.nodes.paragraph.create(null, [schema.text("pasted A")]),
+          ]),
+          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "b" }, [
+            schema.nodes.paragraph.create(null, [schema.text("pasted B")]),
+          ]),
+        ]),
+      ]),
+      0,
+      0,
+    );
+    const out = paste(editor, slice);
+    const ids = sliceFootnoteIds(out);
+    const distinct = new Set(ids.map((x) => x.id));
+    // Two ids, both remapped off the originals, and distinct from each other.
+    expect(distinct.size).toBe(2);
+    expect(distinct.has("a")).toBe(false);
+    expect(distinct.has("b")).toBe(false);
+    expect([...distinct].sort()).toEqual(["a__2", "b__2"]);
+    editor.destroy();
+  });
+
+  it("leaves the slice untouched when no pasted definition collides", () => {
+    const editor = makeEditorWithFootnoteA();
+    const { schema } = editor;
+    // A pasted reference+definition for a BRAND-NEW id "b" — no collision.
+    const slice = new Slice(
+      Fragment.fromArray([
+        schema.nodes.paragraph.create(null, [
+          schema.text("new "),
+          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "b" }),
+        ]),
+        schema.nodes[FOOTNOTES_LIST_NAME].create(null, [
+          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "b" }, [
+            schema.nodes.paragraph.create(null, [schema.text("note B")]),
+          ]),
+        ]),
+      ]),
+      0,
+      0,
+    );
+    const out = paste(editor, slice);
+    expect(sliceFootnoteIds(out)).toEqual([
+      { kind: "ref", id: "b" },
+      { kind: "def", id: "b" },
+    ]);
+    editor.destroy();
+  });
+});

packages/editor-ext/src/lib/footnote/footnote-reference.ts

@@ -1,14 +1,14 @@
-import { mergeAttributes, Node } from "@tiptap/core";
-import { TextSelection, Transaction } from "@tiptap/pm/state";
-import { ReactNodeViewRenderer } from "@tiptap/react";
+import { mergeAttributes, Node } from '@tiptap/core';
+import { TextSelection, Transaction } from '@tiptap/pm/state';
+import { ReactNodeViewRenderer } from '@tiptap/react';
 import {
   FOOTNOTE_DEFINITION_NAME,
   FOOTNOTE_REFERENCE_NAME,
   FOOTNOTES_LIST_NAME,
   generateFootnoteId,
-} from "./footnote-util";
-import { footnoteNumberingPlugin } from "./footnote-numbering";
-import { footnoteSyncPlugin, footnotePastePlugin } from "./footnote-sync";
+} from './footnote-util';
+import { footnoteNumberingPlugin } from './footnote-numbering';
+import { footnoteSyncPlugin, footnotePastePlugin } from './footnote-sync';
 
 export interface FootnoteReferenceOptions {
   HTMLAttributes: Record<string, any>;
@@ -27,7 +27,7 @@ export interface FootnoteReferenceOptions {
   enableSync?: boolean;
 }
 
-declare module "@tiptap/core" {
+declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     footnote: {
       /**
@@ -42,8 +42,11 @@ declare module "@tiptap/core" {
       removeFootnote: (id: string) => ReturnType;
       /** Scroll to (and focus) a footnote definition by id. */
       scrollToFootnote: (id: string) => ReturnType;
-      /** Scroll to (and select) a footnote reference by id. */
-      scrollToReference: (id: string) => ReturnType;
+      /** Scroll to a footnote reference by id. `index` selects WHICH occurrence
+       *  to scroll to when the id is referenced more than once (reuse, #166):
+       *  0-based, defaults to the first. Used by the definition's multi-backlink
+       *  UI (#168). */
+      scrollToReference: (id: string, index?: number) => ReturnType;
     };
   }
 }
@@ -66,7 +69,7 @@ export const FootnoteReference = Node.create<FootnoteReferenceOptions>({
   // Superscript mark's <sup> rule.
   priority: 101,
 
-  group: "inline",
+  group: 'inline',
   inline: true,
   atom: true,
   selectable: true,
@@ -99,10 +102,10 @@ export const FootnoteReference = Node.create<FootnoteReferenceOptions>({
     return {
       id: {
         default: null,
-        parseHTML: (element) => element.getAttribute("data-id"),
+        parseHTML: (element) => element.getAttribute('data-id'),
         renderHTML: (attributes) => {
           if (!attributes.id) return {};
-          return { "data-id": attributes.id };
+          return { 'data-id': attributes.id };
         },
       },
     };
@@ -113,7 +116,7 @@ export const FootnoteReference = Node.create<FootnoteReferenceOptions>({
       {
         // High priority so the Superscript mark (which also matches <sup>) does
         // not claim a footnote reference and drop it as empty content.
-        tag: "sup[data-footnote-ref]",
+        tag: 'sup[data-footnote-ref]',
         priority: 100,
       },
     ];
@@ -121,9 +124,9 @@ export const FootnoteReference = Node.create<FootnoteReferenceOptions>({
 
   renderHTML({ HTMLAttributes }) {
     return [
-      "sup",
+      'sup',
       mergeAttributes(
-        { "data-footnote-ref": "", class: "footnote-ref" },
+        { 'data-footnote-ref': '', class: 'footnote-ref' },
         this.options.HTMLAttributes,
         HTMLAttributes,
       ),
@@ -132,7 +135,7 @@ export const FootnoteReference = Node.create<FootnoteReferenceOptions>({
 
   // Plain-text representation (used by generateText / markdown text fallbacks).
   renderText({ node }) {
-    return `[^${node.attrs.id ?? ""}]`;
+    return `[^${node.attrs.id ?? ''}]`;
   },
 
   addNodeView() {
@@ -170,8 +173,10 @@ export const FootnoteReference = Node.create<FootnoteReferenceOptions>({
 
           // Make sure the parent accepts an inline atom here.
           const insertPos = selection.from;
-          if (!$from.parent.type.spec.content?.includes("inline") &&
-              !$from.parent.isTextblock) {
+          if (
+            !$from.parent.type.spec.content?.includes('inline') &&
+            !$from.parent.isTextblock
+          ) {
             return false;
           }
 
@@ -311,19 +316,23 @@ export const FootnoteReference = Node.create<FootnoteReferenceOptions>({
             `[data-footnote-def][data-id="${id}"]`,
           ) as HTMLElement | null;
           if (!dom) return false;
-          dom.scrollIntoView({ behavior: "smooth", block: "center" });
+          dom.scrollIntoView({ behavior: 'smooth', block: 'center' });
           return true;
         },
 
       scrollToReference:
-        (id: string) =>
+        (id: string, index = 0) =>
         ({ editor }) => {
           if (!id) return false;
-          const dom = editor.view.dom.querySelector(
+          // querySelectorAll returns the occurrences in document order, so the
+          // index maps 1:1 to the definition's a/b/c backlink (#168). Fall back
+          // to the first match for an out-of-range index.
+          const matches = editor.view.dom.querySelectorAll(
             `sup[data-footnote-ref][data-id="${id}"]`,
-          ) as HTMLElement | null;
+          );
+          const dom = (matches[index] ?? matches[0]) as HTMLElement | undefined;
           if (!dom) return false;
-          dom.scrollIntoView({ behavior: "smooth", block: "center" });
+          dom.scrollIntoView({ behavior: 'smooth', block: 'center' });
           return true;
         },
     };

packages/editor-ext/src/lib/footnote/footnote-sync.ts

@@ -29,9 +29,9 @@ interface DefOccurrence {
 
 interface FootnoteScan {
   /**
-   * Every reference occurrence in document order (NOT de-duplicated). Needed so
-   * that duplicate ids — which would otherwise be silently collapsed — can be
-   * detected and (together with their definitions) re-id'd instead of dropped.
+   * Every reference occurrence in document order (NOT de-duplicated). Repeated
+   * ids are kept so the FIRST appearance fixes definition order; later repeats
+   * are reuse (same footnote) and are never re-id'd.
    */
   refOccurrences: RefOccurrence[];
   /**
@@ -67,77 +67,66 @@ function scan(doc: ProseMirrorNode): FootnoteScan {
 }
 
 /**
- * Result of resolving id collisions: a 1:1, de-duplicated pairing plan plus the
- * concrete reference re-id edits that must be applied to the body so the doc no
- * longer contains two footnotes sharing a single id.
+ * Result of resolving the footnote id topology: the distinct reference order and
+ * one definition node per id.
  *
- * The overriding invariant is that NO definition is ever dropped here: every
- * definition occurrence ends up with a unique id and therefore survives the
- * canonical rebuild. Duplicate references are likewise re-id'd (and paired with
- * a duplicate definition when one exists) so importing/pasting `[^d]` twice with
- * two `[^d]:` definitions yields TWO distinct footnotes rather than one.
+ * References are NEVER re-id'd here — repeated ids are REUSE (one footnote). Only
+ * duplicate DEFINITIONS are re-id'd; lacking a matching reference, a re-id'd
+ * duplicate is then dropped by the orphan policy. No definition is ever dropped
+ * for COLLIDING — only for being an orphan.
  */
 interface CollisionPlan {
   /**
-   * Reference ids in document order, de-duplicated AFTER re-id. This is the
-   * source of truth for definition order/numbering, exactly as before — only
-   * now collisions have been resolved so it no longer hides duplicates.
+   * Distinct reference ids in document order (first appearance). Repeated ids
+   * are reuse and collapse to a single entry. Source of truth for definition
+   * order/numbering.
    */
   referenceIds: string[];
-  /** id -> definition node, after duplicates were re-id'd. One entry per id. */
+  /** id -> definition node, after duplicate definitions were re-id'd. One per id. */
   definitions: Map<string, ProseMirrorNode>;
-  /**
-   * Body reference re-id edits to apply (position of a reference node -> the
-   * fresh id it must carry). Empty when there are no colliding references.
-   */
-  refReids: Array<{ pos: number; node: ProseMirrorNode; newId: string }>;
-  /** True when any collision required a re-id (refs and/or defs). */
+  /** True when a duplicate definition required a re-id. */
   changed: boolean;
 }
 
 /**
- * Resolve duplicate-id collisions among references and definitions WITHOUT ever
- * dropping a definition.
+ * Resolve the footnote id topology WITHOUT ever dropping a definition.
  *
- * Strategy:
- *  - Walk references in document order. The FIRST reference for an id keeps it.
- *    Any later reference sharing that id is a duplicate and gets a fresh unique
- *    id; if a still-unclaimed duplicate definition with the original id exists,
- *    it is re-id'd to the SAME fresh id so the (ref, def) pair stays matched.
- *  - Walk definitions in document order. The FIRST definition for an id keeps
- *    it; later duplicates that were not already claimed by a duplicate reference
- *    get their own fresh unique id (surviving as a distinct footnote/orphan).
+ * Reference REUSE (Pandoc semantics, #166): repeated `[^a]` references that share
+ * an id are the SAME footnote — they get one number and one definition and are
+ * NEVER re-id'd. So the reference walk only records the FIRST occurrence of each
+ * id (de-duplicating in document order); later occurrences are reuse and produce
+ * no mutation at all.
  *
- * Re-id determinism: every fresh id is DERIVED from document state via
- * deriveFootnoteId (e.g. `X__2`, `X__3`, collision-bumped against the set of ids
- * already present) — NEVER random/time-based. Because the sync plugin runs
- * identically on every collaborating client, a deterministic re-id is the only
- * way they can converge on the SAME ids; a random id (the previous
- * implementation) made two clients editing the same duplicate-id document mint
- * DIFFERENT ids for the same duplicate, causing permanent Yjs divergence.
+ * Duplicate DEFINITIONS (two `[^d]:` nodes sharing an id reaching the LIVE editor
+ * via paste/collab merge) keep the never-lose policy: the first keeps the id, and
+ * each later duplicate is re-id'd to a DETERMINISTIC fresh id (deriveFootnoteId:
+ * `X__2`, `X__3`, collision-bumped) so it survives as a distinct footnote — which,
+ * having no matching reference, then falls under the normal orphan policy. It is
+ * only ever dropped for lacking a reference, never for colliding. The IMPORT
+ * paths (footnote.marked.ts / MCP extractFootnotes) instead apply first-wins +
+ * drop + warn for duplicate definitions; that divergence is intentional — import
+ * is an agent-authored artifact we sanitize, the editor is live user data we must
+ * not lose.
+ *
+ * Re-id determinism: every fresh id is DERIVED from document state, NEVER
+ * random/time-based, because the sync plugin runs identically on every
+ * collaborating client and a random id would make two clients mint DIFFERENT ids
+ * for the same duplicate, causing permanent Yjs divergence.
  */
 function resolveCollisions(scan: FootnoteScan): CollisionPlan {
   const definitions = new Map<string, ProseMirrorNode>();
-  const refReids: Array<{
-    pos: number;
-    node: ProseMirrorNode;
-    newId: string;
-  }> = [];
   const referenceIds: string[] = [];
   const seenRefIds = new Set<string>();
   let changed = false;
 
-  // `taken` is the set of every id that must be avoided when minting a derived
-  // id: all original reference + definition ids in the document PLUS every id we
-  // mint during this pass. It is pure document state, so the derivation stays
-  // deterministic across clients. Per-original occurrence counters make the k-th
-  // duplicate of `X` deterministically become `X__2`, `X__3`, ...
+  // `taken` is the set of every id to avoid when minting a derived id for a
+  // duplicate definition: all original reference + definition ids PLUS every id
+  // minted in this pass. Pure document state, so the derivation is deterministic
+  // across clients.
   const taken = new Set<string>();
   for (const occ of scan.refOccurrences) taken.add(occ.id);
   for (const occ of scan.defOccurrences) taken.add(occ.id);
   const occurrenceOf = new Map<string, number>();
-  // Mint a deterministic unique id for a duplicate of `originalId`. The first
-  // duplicate is occurrence 2 (the keeper is occurrence 1), then 3, 4, ...
   const mintId = (originalId: string): string => {
     const next = (occurrenceOf.get(originalId) ?? 1) + 1;
     occurrenceOf.set(originalId, next);
@@ -146,70 +135,30 @@ function resolveCollisions(scan: FootnoteScan): CollisionPlan {
     return id;
   };
 
-  // Bucket definition occurrences by their original id so a duplicate reference
-  // can claim a matching (as-yet-unclaimed) duplicate definition and re-id the
-  // pair together. defByOriginalId[id] is consumed front-to-back.
-  const defByOriginalId = new Map<string, DefOccurrence[]>();
-  for (const occ of scan.defOccurrences) {
-    const arr = defByOriginalId.get(occ.id);
-    if (arr) arr.push(occ);
-    else defByOriginalId.set(occ.id, [occ]);
-  }
-  // The FIRST definition for each id is the canonical keeper of that id.
-  const claimed = new Set<DefOccurrence>();
-
+  // References: record each DISTINCT id once, in first-appearance order. Repeated
+  // ids are reuse — nothing to mint, nothing to re-id.
   for (const ref of scan.refOccurrences) {
     if (!seenRefIds.has(ref.id)) {
-      // First reference with this id keeps it.
       seenRefIds.add(ref.id);
       referenceIds.push(ref.id);
-      continue;
-    }
-    // Duplicate reference: assign a deterministic derived id. Pair it with the
-    // next unclaimed duplicate definition (NOT the first keeper) carrying the
-    // same original id, if one exists, so the (ref, def) pairing is preserved
-    // 1:1.
-    const newId = mintId(ref.id);
-    refReids.push({ pos: ref.pos, node: ref.node, newId });
-    seenRefIds.add(newId);
-    referenceIds.push(newId);
-    changed = true;
-
-    const candidates = defByOriginalId.get(ref.id) ?? [];
-    // Skip the first occurrence (it keeps the original id); pick the first
-    // duplicate not already claimed.
-    for (let i = 1; i < candidates.length; i++) {
-      const cand = candidates[i];
-      if (!claimed.has(cand)) {
-        claimed.add(cand);
-        definitions.set(newId, cand.node);
-        break;
-      }
     }
   }
 
-  // Now place every definition under a unique id. The first occurrence of each
-  // original id keeps it; remaining duplicates either were paired with a
-  // duplicate reference above (already placed) or get a fresh standalone id.
+  // Definitions: the first occurrence of each id keeps it; a later duplicate is
+  // re-id'd deterministically so it is never silently dropped (never-lose).
   const seenDefIds = new Set<string>();
   for (const occ of scan.defOccurrences) {
-    if (claimed.has(occ)) continue; // already placed against a duplicate ref id
     if (!seenDefIds.has(occ.id)) {
       seenDefIds.add(occ.id);
       definitions.set(occ.id, occ.node);
     } else {
-      // Duplicate definition with no duplicate reference to pair with: keep it
-      // with a deterministic derived id so it is NEVER silently dropped. (It
-      // becomes an orphan and is then subject to the normal orphan policy — but
-      // only ever because it has no matching reference, never because it
-      // collided.)
       const newId = mintId(occ.id);
       definitions.set(newId, occ.node);
       changed = true;
     }
   }
 
-  return { referenceIds, definitions, refReids, changed };
+  return { referenceIds, definitions, changed };
 }
 
 /**
@@ -245,14 +194,13 @@ function resolveCollisions(scan: FootnoteScan): CollisionPlan {
  * ping-pong forever (list moved to end -> trailing paragraph appended -> list
  * no longer last -> moved again ...).
  *
- * Duplicate-id collisions (two references and/or two definitions sharing one
- * id — produced by importing `[^d]: a` / `[^d]: b`, or by pasting/duplicating a
- * reference+definition pair) are resolved up front by resolveCollisions(): the
- * duplicates are re-id'd to fresh unique ids so BOTH survive as distinct
- * footnotes. This guarantees the overriding invariant — no footnoteDefinition is
- * ever silently deleted by this automatic (addToHistory:false) transaction. A
+ * The id topology is resolved up front by resolveCollisions() (#166): repeated
+ * references sharing an id are REUSE — one footnote, never re-id'd — while a
+ * duplicate DEFINITION (from pasting/duplicating a definition, or a collab merge)
+ * is re-id'd to a fresh unique id. No footnoteDefinition is ever silently deleted
+ * by this automatic (addToHistory:false) transaction because of a COLLISION; a
  * definition is only ever removed when it has NO matching reference (orphan
- * policy), never because its id collided with another.
+ * policy) — which is also what then drops a re-id'd duplicate definition.
  */
 export function footnoteSyncPlugin(
   isRemoteTransaction?: (tr: Transaction) => boolean,
@@ -283,18 +231,16 @@ export function footnoteSyncPlugin(
 
       const info = scan(doc);
 
-      // 0) Resolve duplicate-id collisions (two references and/or two
-      //    definitions sharing one id) by re-id'ing duplicates to fresh unique
-      //    ids. This is the critical defense: the old last-wins Map silently
-      //    dropped all but the last definition for a shared id; here EVERY
-      //    definition survives with a unique id, and duplicate references are
-      //    paired with duplicate definitions so two same-id imports/pastes yield
-      //    two distinct footnotes instead of one.
+      // 0) Resolve the id topology (#166): repeated references that share an id
+      //    are REUSE — collapsed to one entry in `referenceIds`, never re-id'd —
+      //    while a duplicate DEFINITION is re-id'd to a fresh deterministic id
+      //    (and, lacking a matching reference, removed by the orphan policy
+      //    below). No definition is dropped for COLLIDING, only for being orphan.
       const plan = resolveCollisions(info);
       const referenceIds = plan.referenceIds;
 
-      // The set of ids that must have a definition, in reference order (after
-      // collision re-id). De-duplicated already by resolveCollisions.
+      // The set of ids that must have a definition, in reference order.
+      // De-duplicated already by resolveCollisions.
       const referenceIdSet = new Set(referenceIds);
 
       // 1) For each definition occurrence, compute the id it should END UP with
@@ -397,21 +343,15 @@ export function footnoteSyncPlugin(
 
       // 6) Apply the targeted, minimal mutations in ONE transaction. We never
       //    delete-and-recreate an unchanged definition subtree; we only:
-      //      (a) re-id specific colliding references and definitions (attr-only),
+      //      (a) re-id colliding definitions (attr-only),
       //      (b) delete genuine orphan definitions and extra/empty lists,
       //      (c) insert genuinely-missing empty definitions and migrate defs out
       //          of extra lists into the primary list,
       //      (d) create the primary list if references exist but none does yet.
+      //    References are never re-id'd (reuse), so there is no reference edit.
       const tr = newState.tr;
 
-      // 6a) Re-id colliding references (inline atoms: attr-only, size-stable).
-      for (const reid of plan.refReids) {
-        tr.setNodeMarkup(tr.mapping.map(reid.pos), undefined, {
-          ...reid.node.attrs,
-          id: reid.newId,
-        });
-      }
-      // 6b) Re-id colliding definitions IN PLACE (attr-only). This preserves the
+      // 6a) Re-id colliding definitions IN PLACE (attr-only). This preserves the
       //     definition's content subtree — never delete+recreate it.
       for (const reid of defReidsToApply) {
         tr.setNodeMarkup(tr.mapping.map(reid.pos), undefined, {
@@ -546,13 +486,17 @@ export const footnotePastePluginKey = new PluginKey("footnotePaste");
  * Without this, pasting a reference+definition pair copied from elsewhere — or
  * duplicating one in place — would merge with (or clobber) the existing footnote
  * of the same id. The schema-sync plugin already guarantees no definition is
- * ever silently deleted after the fact (it re-id's collisions), but regenerating
- * at paste time keeps the pasted footnote cleanly separate from the start and
- * avoids any transient merge.
+ * ever silently deleted after the fact (it re-id's duplicate definitions), but
+ * regenerating at paste time keeps the pasted footnote cleanly separate from the
+ * start and avoids any transient merge.
  *
- * Only COLLIDING ids are remapped: a self-paste of a lone reference whose id is
- * not present elsewhere is left untouched (so it still resolves to its existing
- * definition).
+ * REUSE-aware (#166): only a colliding DEFINITION forces a remap. Pasting a lone
+ * reference whose id already exists is REUSE — it must keep the id so it resolves
+ * to the existing footnote (one number, shared definition). So we remap an id
+ * only when the pasted slice itself carries a `footnoteDefinition` for it (which
+ * would otherwise clobber the existing definition's text); the matching pasted
+ * references are remapped along with it to stay paired. A self-paste of just a
+ * reference is left untouched.
  */
 export function footnotePastePlugin(): Plugin {
   return new Plugin({
@@ -572,31 +516,35 @@ export function footnotePastePlugin(): Plugin {
         });
         if (existing.size === 0) return slice;
 
-        // Build a remap (old id -> fresh id) for every COLLIDING id found in the
-        // pasted slice, shared by references and definitions so a pasted pair
-        // stays matched. A paste is a distinct local user action (not a
-        // shared-state convergence point), so determinism is not strictly
-        // required here — but we derive the new id deterministically anyway
-        // (deriveFootnoteId against the current doc's id set) for consistency
-        // with the sync/import paths and to keep Math.random off this code path.
-        const remap = new Map<string, string>();
-        const collectColliding = (node: ProseMirrorNode) => {
-          if (
-            node.type.name === FOOTNOTE_REFERENCE_NAME ||
-            node.type.name === FOOTNOTE_DEFINITION_NAME
-          ) {
+        // Ids the pasted slice DEFINES (carries a footnoteDefinition for). Only
+        // these can clobber an existing footnote's text, so only these force a
+        // remap; a pasted reference to an already-existing id is reuse and keeps
+        // its id.
+        const sliceDefIds = new Set<string>();
+        const collectDefIds = (node: ProseMirrorNode) => {
+          if (node.type.name === FOOTNOTE_DEFINITION_NAME) {
             const id = node.attrs.id;
-            if (id && existing.has(id) && !remap.has(id)) {
-              const newId = deriveFootnoteId(id, 2, existing);
-              remap.set(id, newId);
-              // Reserve it so a second colliding id deriving to the same base
-              // bumps instead of clashing.
-              existing.add(newId);
-            }
+            if (id) sliceDefIds.add(id);
           }
-          node.descendants(collectColliding);
+          node.descendants(collectDefIds);
         };
-        slice.content.descendants(collectColliding);
+        slice.content.descendants(collectDefIds);
+
+        // Build a remap (old id -> fresh id) for every colliding id the slice
+        // DEFINES, shared by references and definitions so a pasted pair stays
+        // matched. The new id is derived deterministically (deriveFootnoteId
+        // against the current doc's id set) for consistency with the sync/import
+        // paths and to keep Math.random off this code path.
+        const remap = new Map<string, string>();
+        for (const id of sliceDefIds) {
+          if (existing.has(id) && !remap.has(id)) {
+            const newId = deriveFootnoteId(id, 2, existing);
+            remap.set(id, newId);
+            // Reserve it so a second colliding id deriving to the same base
+            // bumps instead of clashing.
+            existing.add(newId);
+          }
+        }
         if (remap.size === 0) return slice;
 
         // Rewrite the colliding ids throughout the slice.

packages/editor-ext/src/lib/footnote/footnote-util.derive-id.test.ts

@@ -4,16 +4,12 @@ import { deriveFootnoteId } from "./footnote-util";
 /**
  * GOLDEN TABLE for `deriveFootnoteId` (and its private alphabetic `suffix`).
  *
- * deriveFootnoteId is DELIBERATELY duplicated in
- *   packages/mcp/src/lib/collaboration.ts
- * and the two copies MUST stay byte-for-byte equivalent in behavior so the same
- * markdown imported through the editor and through the MCP path yields identical
- * footnote ids. This table is the SHARED contract: the parity test
- *   packages/mcp/test/unit/derive-id-parity.test.mjs
- * pins the exact SAME (input -> expected) pairs against the COMPILED mcp build.
- * If either copy drifts, one of the two tests goes red.
- *
- * Keep this constant in sync with GOLDEN in the mcp parity test.
+ * `deriveFootnoteId` lives ONLY in editor-ext now — it is used by
+ * `resolveCollisions` (re-id of a duplicate definition) and `footnotePastePlugin`
+ * (re-id of a pasted colliding definition). The MCP/marked import paths no longer
+ * derive ids (duplicate definitions there are first-wins-dropped, #166), so there
+ * is no cross-package copy and no parity test to keep in sync. This table pins the
+ * deterministic scheme so a future change to it is a conscious one.
  */
 export const DERIVE_GOLDEN: Array<{
   originalId: string;
@@ -56,7 +52,7 @@ function singleLetterSuffixes(): string[] {
   return Array.from({ length: 25 }, (_, i) => String.fromCharCode(98 + i));
 }
 
-describe("deriveFootnoteId golden table (cross-package drift guard)", () => {
+describe("deriveFootnoteId golden table (deterministic-scheme pin)", () => {
   for (const row of DERIVE_GOLDEN) {
     it(`derive("${row.originalId}", ${row.occurrence}, {${row.taken.join(",")}}) === "${row.expected}" — ${row.why}`, () => {
       const got = deriveFootnoteId(

packages/editor-ext/src/lib/footnote/footnote-util.ts

@@ -1,12 +1,12 @@
-import { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { Node as ProseMirrorNode } from '@tiptap/pm/model';
 
 /**
  * Node type names for the footnote feature. Centralized so every part of the
  * feature (nodes, plugins, commands) references the same string.
  */
-export const FOOTNOTE_REFERENCE_NAME = "footnoteReference";
-export const FOOTNOTES_LIST_NAME = "footnotesList";
-export const FOOTNOTE_DEFINITION_NAME = "footnoteDefinition";
+export const FOOTNOTE_REFERENCE_NAME = 'footnoteReference';
+export const FOOTNOTES_LIST_NAME = 'footnotesList';
+export const FOOTNOTE_DEFINITION_NAME = 'footnoteDefinition';
 
 /**
  * Generate a uuidv7-style id (time-ordered). Implemented locally so editor-ext
@@ -15,10 +15,10 @@ export const FOOTNOTE_DEFINITION_NAME = "footnoteDefinition";
  */
 export function generateFootnoteId(): string {
   const now = Date.now();
-  const timeHex = now.toString(16).padStart(12, "0");
+  const timeHex = now.toString(16).padStart(12, '0');
 
   const rand = (length: number) => {
-    let out = "";
+    let out = '';
     for (let i = 0; i < length; i++) {
       out += Math.floor(Math.random() * 16).toString(16);
     }
@@ -26,19 +26,19 @@ export function generateFootnoteId(): string {
   };
 
   // version 7 nibble, then variant (8..b) nibble.
-  const versioned = "7" + rand(3);
+  const versioned = '7' + rand(3);
   const variantNibble = (8 + Math.floor(Math.random() * 4)).toString(16);
   const variant = variantNibble + rand(3);
 
   return (
     timeHex.slice(0, 8) +
-    "-" +
+    '-' +
     timeHex.slice(8, 12) +
-    "-" +
+    '-' +
     versioned +
-    "-" +
+    '-' +
     variant +
-    "-" +
+    '-' +
     rand(12)
   );
 }
@@ -62,10 +62,11 @@ export function generateFootnoteId(): string {
  * `taken` is consulted but NOT mutated here; the caller adds the returned id to
  * its own seen-set before requesting the next derived id.
  *
- * NOTE: this implementation is intentionally duplicated in
- *   packages/mcp/src/lib/collaboration.ts (deriveFootnoteId)
- * and MUST stay in sync with it so markdown imported through either path yields
- * identical ids.
+ * Used only inside editor-ext now (resolveCollisions for a re-id'd duplicate
+ * DEFINITION, and footnotePastePlugin). The MCP/marked import paths no longer
+ * derive ids — duplicate definitions there are first-wins-dropped (#166) — so
+ * there is no cross-package copy to keep in sync. The golden table in
+ * footnote-util.derive-id.test.ts pins the scheme.
  */
 export function deriveFootnoteId(
   originalId: string,
@@ -88,7 +89,7 @@ export function deriveFootnoteId(
  * Purely deterministic.
  */
 function suffix(n: number): string {
-  let out = "";
+  let out = '';
   let x = n;
   while (x > 0) {
     const rem = (x - 1) % 25;
@@ -130,3 +131,19 @@ export function computeFootnoteNumbers(
   }
   return numbers;
 }
+
+/**
+ * Build a map of `referenceId -> number of reference occurrences` (>= 1) from
+ * document order. After #166 the same id may be referenced multiple times
+ * (reuse: one number, one definition, N forward links); this count drives the
+ * definition's multi-backlink UI (↩ a b c …, #168). Pure function of the doc.
+ */
+export function computeFootnoteRefCounts(
+  doc: ProseMirrorNode,
+): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const id of collectReferenceIds(doc)) {
+    counts.set(id, (counts.get(id) ?? 0) + 1);
+  }
+  return counts;
+}

packages/editor-ext/src/lib/markdown/utils/footnote.marked.orphan.test.ts

@@ -13,36 +13,33 @@ function bodyMarkers(body: string): string[] {
   return [...body.matchAll(/\[\^([^\]\s]+)\]/g)].map((m) => m[1]);
 }
 
-describe("extractFootnoteDefinitions: more definitions than markers (orphans)", () => {
-  // Body has ONE `[^d]` reference marker but THREE `[^d]:` definitions. The
-  // surplus definitions have no marker to pair with — they must NOT be silently
-  // merged into one footnote (the editor's last-wins sync would otherwise drop
-  // two of them). The dedup gives each colliding definition a deterministic
-  // derived id so all three survive as distinct footnoteDefinition nodes.
+describe("extractFootnoteDefinitions: duplicate definition ids (first-wins)", () => {
+  // Body has ONE `[^d]` reference but THREE `[^d]:` definitions. Under the
+  // import model (#166) a duplicate definition id is FIRST-WINS: only the first
+  // definition is kept; the rest are DROPPED (and surfaced by analyzeFootnotes,
+  // not silently re-id'd into orphan footnotes as before). Reference markers are
+  // never rewritten, so repeated references would reuse the single footnote.
   const md = ["See[^d].", "", "[^d]: a", "[^d]: b", "[^d]: c"].join("\n");
 
-  it("emits 3 DISTINCT definition ids: d, d__2, d__3 (derived scheme, in order)", () => {
+  it("keeps only the FIRST definition for the id (first-wins)", () => {
     const { section } = extractFootnoteDefinitions(md);
     const ids = defIds(section);
-    expect(ids).toEqual(["d", "d__2", "d__3"]);
-    // All distinct: nothing was merged away.
-    expect(new Set(ids).size).toBe(3);
+    expect(ids).toEqual(["d"]);
   });
 
-  it("preserves each definition's text against its (possibly derived) id", () => {
+  it("keeps the first definition's text and drops the duplicates", () => {
     const { section } = extractFootnoteDefinitions(md);
-    // First definition keeps the original id and its text.
     expect(section).toContain('data-footnote-def data-id="d"><p>a</p>');
-    // The two surplus definitions survive as orphans with derived ids.
-    expect(section).toContain('data-footnote-def data-id="d__2"><p>b</p>');
-    expect(section).toContain('data-footnote-def data-id="d__3"><p>c</p>');
+    // No derived `d__2` / `d__3` ids are emitted anymore.
+    expect(section).not.toContain("d__2");
+    expect(section).not.toContain("d__3");
+    // The dropped duplicate texts are not in the section.
+    expect(section).not.toContain("<p>b</p>");
+    expect(section).not.toContain("<p>c</p>");
   });
 
-  it("leaves the SINGLE body marker as [^d] (no surplus marker to rewrite)", () => {
+  it("leaves the SINGLE body marker as [^d] (markers are never rewritten)", () => {
     const { body } = extractFootnoteDefinitions(md);
-    // There is exactly one reference marker and it is untouched: the keeper
-    // definition pairs with it. The orphan defs have no marker, so the body is
-    // unchanged except for the stripped definition lines.
     expect(bodyMarkers(body)).toEqual(["d"]);
     expect(body).toContain("See[^d].");
     // The definition lines themselves were pulled OUT of the body.
@@ -55,9 +52,21 @@ describe("extractFootnoteDefinitions: more definitions than markers (orphans)",
     const { section } = extractFootnoteDefinitions(md);
     expect(section.startsWith("<section data-footnotes>")).toBe(true);
     expect(section.endsWith("</section>")).toBe(true);
-    // Exactly three definition divs.
-    expect(
-      [...section.matchAll(/<div data-footnote-def/g)],
-    ).toHaveLength(3);
+    // Exactly one definition div (first-wins).
+    expect([...section.matchAll(/<div data-footnote-def/g)]).toHaveLength(1);
+  });
+});
+
+describe("extractFootnoteDefinitions: reuse (repeated references, one definition)", () => {
+  // Pandoc semantics: many `[^a]` references + one `[^a]:` definition = one
+  // footnote, shared. Markers are left intact so the editor numbers them as one.
+  const md = ["A[^a] B[^a] C[^a].", "", "[^a]: shared note"].join("\n");
+
+  it("emits exactly one definition and leaves every reference marker as [^a]", () => {
+    const { section, body } = extractFootnoteDefinitions(md);
+    expect(defIds(section)).toEqual(["a"]);
+    expect(section).toContain('data-footnote-def data-id="a"><p>shared note</p>');
+    // All three reference markers stay `a` (no `a__2`/`a__3` minting).
+    expect(bodyMarkers(body)).toEqual(["a", "a", "a"]);
   });
 });

packages/editor-ext/src/lib/markdown/utils/footnote.marked.ts

@@ -1,5 +1,4 @@
 import { marked } from "marked";
-import { deriveFootnoteId } from "../../footnote/footnote-util";
 
 /**
  * Pandoc/GFM footnote support for the marked (Markdown -> HTML) pipeline.
@@ -13,8 +12,12 @@ import { deriveFootnoteId } from "../../footnote/footnote-util";
  *    single <section data-footnotes> with one <div data-footnote-def> per
  *    definition, so the round-trip rebuilds footnotesList + footnoteDefinition.
  *
- * Only definitions that have a matching reference are emitted (and vice-versa
- * the sync plugin fills any gaps on the editor side), keeping the output valid.
+ * Every FIRST definition line is emitted — duplicate ids are first-wins (the
+ * rest are dropped, and surfaced via analyzeFootnotes), and reference markers are
+ * left untouched so repeated `[^a]` references reuse the one footnote (#166).
+ * Orphan definitions (no matching reference) are still emitted here; the editor's
+ * sync plugin reconciles the final reference/definition set (drops orphans,
+ * synthesizes a single empty definition for a reference that lacks one).
  */
 
 const DEFINITION_RE = /^\[\^([^\]\s]+)\]:[ \t]*(.*)$/;
@@ -53,10 +56,6 @@ function escapeAttr(value: string): string {
   return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
 }
 
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
 /**
  * Extract `[^id]: text` definition lines from the markdown body, returning the
  * cleaned body plus a rendered <section data-footnotes> (empty string when no
@@ -101,70 +100,32 @@ export function extractFootnoteDefinitions(markdown: string): {
     return { body: markdown, section: "" };
   }
 
-  // De-duplicate colliding definition ids. Two definitions sharing an id (e.g.
-  // `[^d]: first` / `[^d]: second`) would otherwise collapse into one footnote
-  // downstream (the editor's last-wins sync). Rename each colliding id to a
-  // DETERMINISTIC derived one AND rewrite the corresponding `[^id]` reference
-  // marker so the (reference, definition) pairing stays 1:1. The FIRST
-  // definition keeps the id and pairs with the FIRST `[^id]` marker; the Nth
-  // duplicate gets the derived id `${id}__${N}` and rewrites the Nth `[^id]`
-  // marker. If there are fewer markers than definitions, the surplus definition
-  // keeps a derived (orphan) id so it is never silently merged away.
-  //
-  // The id is derived (deriveFootnoteId), NOT random: importing the same
-  // markdown through two paths (here and the MCP mirror) must yield identical
-  // ids, and re-importing the same markdown twice must be stable.
-  let dedupedBody = bodyLines.join("\n");
-  // Every original definition id is reserved up front so a derived id can never
-  // collide with an unrelated original id present in the document.
-  const taken = new Set<string>(definitions.map((d) => d.id));
-  const seenDefIds = new Map<string, number>(); // original id -> how many seen
+  // Duplicate definition ids (e.g. `[^d]: first` / `[^d]: second`): FIRST WINS,
+  // the rest are DROPPED. Reference markers are left UNTOUCHED so repeated `[^a]`
+  // references reuse the single footnote (Pandoc semantics, #166). This differs
+  // from the live editor's never-lose policy (resolveCollisions re-ids a
+  // duplicate definition into an orphan) on purpose: an import is an
+  // agent-authored artifact we sanitize, and the dropped duplicate is surfaced
+  // to the caller via analyzeFootnotes' `duplicateDefinitions` warning instead.
+  const firstById = new Map<string, string>(); // id -> first definition text
   for (const def of definitions) {
-    const originalId = def.id;
-    const count = seenDefIds.get(originalId) ?? 0;
-    seenDefIds.set(originalId, count + 1);
-    if (count === 0) continue; // first definition keeps its id
-
-    // count is the 0-based number of PRIOR occurrences; this is occurrence
-    // (count + 1), i.e. 2 for the first duplicate, 3 for the next, ...
-    const newId = deriveFootnoteId(originalId, count + 1, taken);
-    taken.add(newId);
-    def.id = newId;
-
-    // Rewrite the NEXT still-unrewritten `[^originalId]` marker that does not
-    // belong to the keeper definition. After a prior duplicate rewrote its
-    // marker (to `[^someNewId]`), it no longer matches `[^originalId]`, so the
-    // remaining matches are: index 0 = the keeper's marker (left alone), index 1
-    // = this duplicate's marker. Rewrite index 1.
-    let occurrence = 0;
-    let rewritten = false;
-    const re = new RegExp(`\\[\\^${escapeRegExp(originalId)}\\]`, "g");
-    dedupedBody = dedupedBody.replace(re, (match) => {
-      const idx = occurrence++;
-      if (!rewritten && idx === 1) {
-        rewritten = true;
-        return `[^${newId}]`;
-      }
-      return match;
-    });
-    // If there was no second marker (more definitions than references), the
-    // duplicate simply survives as an orphan with its fresh id — no body change.
+    if (!firstById.has(def.id)) firstById.set(def.id, def.text);
   }
 
-  const defsHtml = definitions
-    .map((d) => {
+  const defsHtml = [...firstById.entries()]
+    .map(([id, text]) => {
       // Render the definition text as inline markdown so emphasis/links inside
       // a footnote survive the round-trip; wrap in a paragraph (the node's
       // content is paragraph+).
-      const inner = marked.parseInline(d.text || "");
+      const inner = marked.parseInline(text || "");
       return `<div data-footnote-def data-id="${escapeAttr(
-        d.id,
+        id,
       )}"><p>${inner}</p></div>`;
     })
     .join("");
 
   return {
-    body: dedupedBody,
+    body: bodyLines.join("\n"),
     section: `<section data-footnotes>${defsHtml}</section>`,
   };
 }

packages/mcp/build/client.js

@@ -7,8 +7,8 @@ import { TiptapTransformer } from "@hocuspocus/transformer";
 import * as Y from "yjs";
 import WebSocket from "ws";
 import { convertProseMirrorToMarkdown } from "./lib/markdown-converter.js";
-import { updatePageContentRealtime, replacePageContent, markdownToProseMirror, mutatePageContent, buildCollabWsUrl, assertYjsEncodable, } from "./lib/collaboration.js";
-import { docmostExtensions } from "./lib/docmost-schema.js";
+import { updatePageContentRealtime, replacePageContent, markdownToProseMirror, mutatePageContent, buildCollabWsUrl, assertYjsEncodable, applyDocToFragment, } from "./lib/collaboration.js";
+import { footnoteWarningsField } from "./lib/footnote-analyze.js";
 import { buildPageTree } from "./lib/tree.js";
 import { serializeDocmostMarkdown, parseDocmostMarkdown, } from "./lib/markdown-document.js";
 import { replaceNodeById, deleteNodeById, insertNodeRelative, buildOutline, getNodeByRef, readTable, insertTableRow, deleteTableRow, updateTableCell, } from "./lib/node-ops.js";
@@ -16,7 +16,7 @@ import { withPageLock } from "./lib/page-lock.js";
 import { applyTextEdits, } from "./lib/json-edit.js";
 import { getCollabToken, performLogin } from "./lib/auth-utils.js";
 import { diffDocs, summarizeChange } from "./lib/diff.js";
-import { applyAnchorInDoc, canAnchorInDoc, } from "./lib/comment-anchor.js";
+import { applyAnchorInDoc, canAnchorInDoc } from "./lib/comment-anchor.js";
 import { blockText, walk, getList, insertMarkerAfter, setCalloutRange, noteItem, mdToInlineNodes, commentsToFootnotes, } from "./lib/transforms.js";
 import vm from "node:vm";
 // Supported image types, kept as two lookup tables so both a local file
@@ -208,7 +208,9 @@ export class DocmostClient {
             // getCollabToken wraps the AxiosError in a plain Error but attaches the
             // HTTP status as `.status`, so detect an auth failure via either the raw
             // AxiosError shape OR the attached status.
-            const axiosStatus = axios.isAxiosError(e) ? e.response?.status : undefined;
+            const axiosStatus = axios.isAxiosError(e)
+                ? e.response?.status
+                : undefined;
             const attachedStatus = e?.status;
             const isAuthError = axiosStatus === 401 ||
                 axiosStatus === 403 ||
@@ -360,14 +362,14 @@ export class DocmostClient {
                             finish(null, mutationResult);
                             return;
                         }
-                        const tempDoc = TiptapTransformer.toYdoc(newDoc, "default", docmostExtensions);
-                        const fragment = ydoc.getXmlFragment("default");
-                        ydoc.transact(() => {
-                            if (fragment.length > 0) {
-                                fragment.delete(0, fragment.length);
-                            }
-                            Y.applyUpdate(ydoc, Y.encodeStateAsUpdate(tempDoc));
-                        });
+                        // Structural diff into the live fragment (issue #152), mirroring
+                        // the main write path: preserves the Yjs ids of unchanged nodes so
+                        // an open editor's cursor is not yanked to the end of the document.
+                        // The previous destructive rewrite (delete-all + applyUpdate of a
+                        // fresh Y.Doc) discarded every node id, so replaceImage — the only
+                        // caller of this method — still reproduced the #152 cursor jump
+                        // (#164). applyDocToFragment runs its own atomic `transact`.
+                        applyDocToFragment(ydoc, newDoc);
                     }
                     catch (e) {
                         finish(e instanceof Error ? e : new Error(String(e)));
@@ -566,7 +568,9 @@ export class DocmostClient {
         // Always fetch subpages to provide context to the agent
         let subpages = [];
         try {
-            subpages = await this.listSidebarPages(resultData.spaceId, pageId);
+            // `pageId` may be a slugId, but the sidebar-pages endpoint requires the
+            // UUID; `resultData.id` holds the resolved UUID returned by getPageRaw.
+            subpages = await this.listSidebarPages(resultData.spaceId, resultData.id);
         }
         catch (e) {
             console.warn("Failed to fetch subpages:", e);
@@ -685,7 +689,12 @@ export class DocmostClient {
         if (!inserted) {
             throw new Error(`table_insert_row: no table found for "${tableRef}" on page ${pageId} (use "#<index>" from get_outline, or a block id inside the table)`);
         }
-        return { success: true, table: tableRef, inserted: true, verify: mutation.verify };
+        return {
+            success: true,
+            table: tableRef,
+            inserted: true,
+            verify: mutation.verify,
+        };
     }
     /**
      * Delete the row at 0-based `index` from a table on the LIVE collab document.
@@ -707,7 +716,12 @@ export class DocmostClient {
         if (!deleted) {
             throw new Error(`table_delete_row: no table found for "${tableRef}" on page ${pageId} (use "#<index>" from get_outline, or a block id inside the table)`);
         }
-        return { success: true, table: tableRef, deleted: true, verify: mutation.verify };
+        return {
+            success: true,
+            table: tableRef,
+            deleted: true,
+            verify: mutation.verify,
+        };
     }
     /**
      * Set the plain-text content of cell `[row, col]` (0-based) in a table on the
@@ -731,7 +745,13 @@ export class DocmostClient {
         if (!updated) {
             throw new Error(`table_update_cell: no table found for "${tableRef}" on page ${pageId} (use "#<index>" from get_outline, or a block id inside the table)`);
         }
-        return { success: true, table: tableRef, row, col, verify: mutation.verify };
+        return {
+            success: true,
+            table: tableRef,
+            row,
+            col,
+            verify: mutation.verify,
+        };
     }
     /**
      * Create a new page with title and content.
@@ -814,7 +834,10 @@ export class DocmostClient {
         if (title) {
             await this.client.post("/pages/update", { pageId: newPageId, title });
         }
-        return this.getPage(newPageId);
+        const page = await this.getPage(newPageId);
+        // Surface non-fatal footnote problems (dangling refs, empty/duplicate
+        // definitions, markers in tables) so the agent can fix its markup (#166).
+        return { ...page, ...footnoteWarningsField(content) };
     }
     /**
      * Update a page's content from markdown and optionally its title.
@@ -823,9 +846,11 @@ export class DocmostClient {
      */
     async updatePage(pageId, content, title) {
         await this.ensureAuthenticated();
-        if (title) {
-            await this.client.post("/pages/update", { pageId, title });
-        }
+        // Write the BODY first, then the title (#159 split-brain). If the collab
+        // body write fails (e.g. a persist timeout), the title must be left
+        // UNTOUCHED so the page never ends up with a new title over its old body.
+        // A title write failing AFTER a successful body is rarer (REST is fast) and
+        // leaves correct content under a stale title — the lesser inconsistency.
         let collabToken = "";
         let mutation;
         try {
@@ -844,12 +869,18 @@ export class DocmostClient {
             }
             throw new Error(`Failed to update page content: ${error.message}`);
         }
+        // Body persisted successfully — now it is safe to set the title.
+        if (title) {
+            await this.client.post("/pages/update", { pageId, title });
+        }
         return {
             success: true,
             modified: true,
             message: "Page updated successfully.",
             pageId: pageId,
             verify: mutation.verify,
+            // Non-fatal footnote diagnostics (#166); omitted when there are none.
+            ...footnoteWarningsField(content),
         };
     }
     /**
@@ -961,7 +992,9 @@ export class DocmostClient {
         if (!node || typeof node !== "object" || typeof node.type !== "string") {
             throw new Error("invalid ProseMirror document: every node must be an object with a string `type`");
         }
-        if ("text" in node && node.type === "text" && typeof node.text !== "string") {
+        if ("text" in node &&
+            node.type === "text" &&
+            typeof node.text !== "string") {
             throw new Error("invalid ProseMirror document: a text node must have a string `text`");
         }
         if (node.marks !== undefined) {
@@ -969,7 +1002,9 @@ export class DocmostClient {
                 throw new Error("invalid ProseMirror document: `marks` must be an array");
             }
             for (const mark of node.marks) {
-                if (!mark || typeof mark !== "object" || typeof mark.type !== "string") {
+                if (!mark ||
+                    typeof mark !== "object" ||
+                    typeof mark.type !== "string") {
                     throw new Error("invalid ProseMirror document: every mark must be an object with a string `type`");
                 }
             }
@@ -1028,11 +1063,14 @@ export class DocmostClient {
         // the markdown link path (which TipTap sanitizes), raw JSON could otherwise
         // inject javascript:/data: link hrefs or media srcs straight into the doc.
         this.validateDocUrls(doc);
+        // Write the BODY first, then the title (#159 split-brain): a failed body
+        // write (e.g. persist timeout) must not leave a new title over the old body.
+        const collabToken = await this.getCollabTokenWithReauth();
+        const mutation = await replacePageContent(pageId, doc, collabToken, this.apiUrl);
+        // Body persisted successfully — now it is safe to set the title.
         if (title) {
             await this.client.post("/pages/update", { pageId, title });
         }
-        const collabToken = await this.getCollabTokenWithReauth();
-        const mutation = await replacePageContent(pageId, doc, collabToken, this.apiUrl);
         return {
             success: true,
             modified: true,
@@ -1049,9 +1087,7 @@ export class DocmostClient {
     async exportPageMarkdown(pageId) {
         await this.ensureAuthenticated();
         const page = await this.getPageRaw(pageId);
-        const body = page.content
-            ? convertProseMirrorToMarkdown(page.content)
-            : "";
+        const body = page.content ? convertProseMirrorToMarkdown(page.content) : "";
         let comments = [];
         try {
             comments = await this.listComments(pageId);
@@ -1119,6 +1155,11 @@ export class DocmostClient {
         if (meta?.pageId && meta.pageId !== pageId) {
             result.warning = `File was exported from page ${meta.pageId} but is being imported into ${pageId}.`;
         }
+        // Non-fatal footnote diagnostics (#166), analyzed on the BODY (the part after
+        // the docmost:meta / docmost:comments blocks) — so a `[^x]`-like token inside
+        // those JSON blocks never produces a false warning, while real markers in the
+        // body do. `body` comes from parseDocmostMarkdown(fullMarkdown) above.
+        Object.assign(result, footnoteWarningsField(body));
         return result;
     }
     /**
@@ -1280,13 +1321,22 @@ export class DocmostClient {
             replaced = 0;
             const { doc: nd, replaced: r } = replaceNodeById(liveDoc, nodeId, target);
             replaced = r;
-            if (replaced === 0)
-                return null; // no match -> skip the write entirely
+            // 0 matches -> skip the write. >1 matches -> the id is AMBIGUOUS: Docmost
+            // duplicates block ids on copy/paste (and copyPageContent writes them
+            // verbatim), so replacing "the node with id X" would silently clobber
+            // EVERY duplicate (#159). Refuse: skip the write and throw below so the
+            // model re-targets with a more specific anchor instead of corrupting the
+            // page. Only an unambiguous single match is written.
+            if (replaced !== 1)
+                return null;
             return nd;
         });
         if (replaced === 0) {
             throw new Error(`patch_node: no node with id "${nodeId}" found on page ${pageId}`);
         }
+        if (replaced > 1) {
+            throw new Error(`patch_node: id "${nodeId}" is ambiguous — ${replaced} nodes on page ${pageId} share it (block ids are duplicated on copy/paste). Refusing to replace all of them; nothing was changed. Re-target with a more specific anchor.`);
+        }
         return { success: true, replaced, nodeId, verify: mutation.verify };
     }
     /**
@@ -1342,7 +1392,7 @@ export class DocmostClient {
             // markdown/emoji are tolerated only as a strip-and-retry fallback, so a
             // miss usually means the text differs from what's on the page.
             const hint = opts.anchorText
-                ? ' anchorText must be the block\'s literal rendered plain text (no markdown wrappers or emoji); anchorNodeId from get_page_json is more reliable.'
+                ? " anchorText must be the block's literal rendered plain text (no markdown wrappers or emoji); anchorNodeId from get_page_json is more reliable."
                 : "";
             throw new Error(`insert_node: anchor not found (${anchorDesc}) on page ${pageId}.${hint}`);
         }
@@ -1369,13 +1419,21 @@ export class DocmostClient {
             deleted = 0;
             const { doc: nd, deleted: d } = deleteNodeById(liveDoc, nodeId);
             deleted = d;
-            if (deleted === 0)
-                return null; // no match -> skip the write entirely
+            // 0 matches -> skip the write. >1 matches -> the id is AMBIGUOUS (block
+            // ids are duplicated on copy/paste, #159): deleting "the node with id X"
+            // would silently remove EVERY duplicate. Refuse: skip the write and throw
+            // below so the model re-targets. Only an unambiguous single match is
+            // deleted.
+            if (deleted !== 1)
+                return null;
             return nd;
         });
         if (deleted === 0) {
             throw new Error(`delete_node: no node with id "${nodeId}" found on page ${pageId}`);
         }
+        if (deleted > 1) {
+            throw new Error(`delete_node: id "${nodeId}" is ambiguous — ${deleted} nodes on page ${pageId} share it (block ids are duplicated on copy/paste). Refusing to delete all of them; nothing was changed. Re-target with a more specific anchor.`);
+        }
         return { success: true, deleted, nodeId, verify: mutation.verify };
     }
     /** Build the public share URL for a page. */
@@ -2422,9 +2480,9 @@ export class DocmostClient {
             const raw = await this.getPageRaw(pageId);
             const current = raw.content || { type: "doc", content: [] };
             runTransform(current);
-            // Exercise the same Yjs encoder the apply path uses, so the preview
-            // fails with the SAME descriptive error when the doc is not encodable
-            // instead of returning a misleadingly-green diff.
+            // Run an independent Yjs-encodability check (same sanitize + schema as the
+            // apply path), so the preview fails with the same descriptive error when
+            // the doc is not encodable instead of returning a misleadingly-green diff.
             assertYjsEncodable(newDoc);
             return {
                 pushed: false,

packages/mcp/build/lib/collaboration.js

@@ -10,6 +10,7 @@ import { JSDOM } from "jsdom";
 import { docmostExtensions, docmostSchema } from "./docmost-schema.js";
 import { withPageLock } from "./page-lock.js";
 import { sanitizeForYjs, findUnstorableAttr } from "./node-ops.js";
+import { lexFootnoteLines } from "./footnote-lex.js";
 import { summarizeChange } from "./diff.js";
 /**
  * Build the descriptive error for an opaque Yjs encode failure ("Unexpected
@@ -280,49 +281,12 @@ function bridgeTaskLists(html) {
 // Mirror of packages/editor-ext footnote markdown handling. A `[^id]` inline
 // marker becomes <sup data-footnote-ref data-id="id">, and `[^id]: text`
 // definition lines are collected into a single <section data-footnotes>.
-const FOOTNOTE_DEF_RE = /^\[\^([^\]\s]+)\]:[ \t]*(.*)$/;
+// Definition detection + fence handling are shared with analyzeFootnotes via
+// lexFootnoteLines (footnote-lex.js). FOOTNOTE_REF_RE is the inline tokenizer's.
 const FOOTNOTE_REF_RE = /\[\^([^\]\s]+)\]/;
 function escapeFootnoteAttr(value) {
     return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
 }
-function escapeFootnoteRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-/**
- * Derive a DETERMINISTIC unique footnote id for the k-th (k >= 2) occurrence of
- * an original id `X` during definition dedup.
- *
- * EXACT MIRROR of editor-ext `deriveFootnoteId`
- * (packages/editor-ext/src/lib/footnote/footnote-util.ts). These two copies MUST
- * STAY IN SYNC: the same markdown imported through the editor and through this
- * MCP path has to produce identical ids, and the sync plugin (which re-ids on
- * every collaborating client) relies on the same scheme to converge. NEVER use
- * Math.random()/Date.now()/uuid here — a random id would diverge across clients.
- *
- * Scheme: base candidate `${originalId}__${occurrence}` (e.g. `X__2`), bumped
- * with a stable alphabetic suffix (`X__2b`, `X__2c`, ...) until it is not in
- * `taken` (the set of ids already present / already minted — pure doc state).
- */
-function deriveFootnoteId(originalId, occurrence, taken) {
-    let candidate = `${originalId}__${occurrence}`;
-    let n = 0;
-    while (taken.has(candidate)) {
-        n += 1;
-        candidate = `${originalId}__${occurrence}${footnoteSuffix(n)}`;
-    }
-    return candidate;
-}
-/** Map 1 -> "b", 2 -> "c", ... (mirror of editor-ext `suffix`). */
-function footnoteSuffix(n) {
-    let out = "";
-    let x = n;
-    while (x > 0) {
-        const rem = (x - 1) % 25;
-        out = String.fromCharCode(98 + rem) + out; // 98 = 'b'
-        x = Math.floor((x - 1) / 25);
-    }
-    return out;
-}
 const footnoteRefMarkedExtension = {
     name: "footnoteRef",
     level: "inline",
@@ -346,68 +310,36 @@ marked.use({ extensions: [footnoteRefMarkedExtension] });
  * <section data-footnotes> for them (or "" when there are none).
  */
 function extractFootnotes(markdown) {
-    const lines = markdown.split("\n");
     const bodyLines = [];
     const defs = [];
-    // Track fenced-code state so a `[^id]: ...` line shown inside a ``` / ~~~ code
-    // block is preserved verbatim and not treated as a footnote definition.
-    let fence = null;
-    for (const line of lines) {
-        const fenceMatch = /^(\s*)(`{3,}|~{3,})/.exec(line);
-        if (fenceMatch) {
-            const marker = fenceMatch[2][0];
-            if (fence === null)
-                fence = marker;
-            else if (marker === fence)
-                fence = null;
-            bodyLines.push(line);
-            continue;
-        }
-        const m = fence === null ? FOOTNOTE_DEF_RE.exec(line) : null;
-        if (m)
-            defs.push({ id: m[1], text: m[2] });
+    // Shared lexer (footnote-lex): a `[^id]: ...` line inside a ``` / ~~~ code
+    // block is inert and stays in the body verbatim; only real definition lines
+    // are pulled out. analyzeFootnotes() consumes the SAME lexer so its diagnostics
+    // match exactly what import keeps/strips (#166).
+    for (const tok of lexFootnoteLines(markdown)) {
+        if (!tok.inFence && tok.definition)
+            defs.push(tok.definition);
         else
-            bodyLines.push(line);
+            bodyLines.push(tok.line);
     }
     if (defs.length === 0)
         return { body: markdown, section: "" };
-    // De-duplicate colliding definition ids (mirror of editor-ext
-    // extractFootnoteDefinitions). Two definitions sharing an id would otherwise
-    // collapse into one footnote downstream; rename each colliding id to a
-    // DETERMINISTIC derived one (NOT random) and rewrite the corresponding `[^id]`
-    // marker so the (reference, definition) pairing stays 1:1. Determinism lets
-    // the same markdown imported here and via the editor produce identical ids.
-    let dedupedBody = bodyLines.join("\n");
-    const taken = new Set(defs.map((d) => d.id));
-    const seenDefIds = new Map();
+    // Duplicate definition ids: FIRST WINS, the rest are DROPPED (mirror of
+    // editor-ext extractFootnoteDefinitions). Reference markers are left untouched
+    // so repeated `[^a]` references reuse the single footnote (Pandoc semantics,
+    // #166). The dropped duplicate is surfaced to the caller via analyzeFootnotes
+    // (`duplicateDefinitions`), not silently lost. MUST stay in sync with the
+    // editor-ext mirror.
+    const firstById = new Map(); // id -> first definition text
     for (const def of defs) {
-        const originalId = def.id;
-        const count = seenDefIds.get(originalId) ?? 0;
-        seenDefIds.set(originalId, count + 1);
-        if (count === 0)
-            continue; // first definition keeps its id
-        const newId = deriveFootnoteId(originalId, count + 1, taken);
-        taken.add(newId);
-        def.id = newId;
-        // Remaining `[^originalId]` matches: index 0 = keeper's marker (left alone),
-        // index 1 = this duplicate's marker. Rewrite index 1.
-        let occurrence = 0;
-        let rewritten = false;
-        const re = new RegExp(`\\[\\^${escapeFootnoteRegExp(originalId)}\\]`, "g");
-        dedupedBody = dedupedBody.replace(re, (match) => {
-            const idx = occurrence++;
-            if (!rewritten && idx === 1) {
-                rewritten = true;
-                return `[^${newId}]`;
-            }
-            return match;
-        });
+        if (!firstById.has(def.id))
+            firstById.set(def.id, def.text);
     }
-    const inner = defs
-        .map((d) => `<div data-footnote-def data-id="${escapeFootnoteAttr(d.id)}"><p>${marked.parseInline(d.text || "")}</p></div>`)
+    const inner = [...firstById.entries()]
+        .map(([id, text]) => `<div data-footnote-def data-id="${escapeFootnoteAttr(id)}"><p>${marked.parseInline(text || "")}</p></div>`)
         .join("");
     return {
-        body: dedupedBody,
+        body: bodyLines.join("\n"),
         section: `<section data-footnotes>${inner}</section>`,
     };
 }

packages/mcp/build/lib/footnote-analyze.js

@@ -0,0 +1,101 @@
+/**
+ * Footnote diagnostics for imported Markdown (issue #166).
+ *
+ * A PURE, fence-aware text scan (independent of the Markdown->ProseMirror
+ * conversion path, so it reports the same problems for `create_page`,
+ * `update_page` and `import_page_markdown`). It never changes the document — the
+ * importer still creates the page; this only surfaces footnote problems to the
+ * caller so an agent can fix its own markup instead of shipping broken footnotes.
+ *
+ * Detected problems:
+ *  - danglingReferences: a `[^id]` reference with no `[^id]:` definition.
+ *  - emptyDefinitions:   a `[^id]:` whose (kept) text is empty/whitespace.
+ *  - duplicateDefinitions: an id defined by two or more `[^id]:` lines (only the
+ *    first is kept on import — first-wins; see extractFootnotes).
+ *  - referencesInTables: a `[^id]` marker found in a GFM table row (heuristic:
+ *    the line, trimmed, starts with `|`) — footnotes in table cells often do not
+ *    render as expected.
+ */
+import { lexFootnoteLines, forEachFootnoteReference, } from "./footnote-lex.js";
+/**
+ * Analyze the footnotes in a Markdown string. Pure; safe to call on any body.
+ */
+export function analyzeFootnotes(markdown) {
+    // Distinct reference ids in first-appearance order, plus the set of ids seen
+    // inside a table row.
+    const refIds = [];
+    const refIdSet = new Set();
+    const referencesInTables = new Set();
+    const addRef = (id, inTable) => {
+        if (!refIdSet.has(id)) {
+            refIdSet.add(id);
+            refIds.push(id);
+        }
+        if (inTable)
+            referencesInTables.add(id);
+    };
+    // Definition texts per id, in first-appearance order of the id.
+    const defTextsById = new Map();
+    // Same lexer the importer uses, so the analysis matches exactly what import
+    // keeps/strips (#166): fenced lines are inert, definition lines are pulled.
+    for (const tok of lexFootnoteLines(markdown)) {
+        if (tok.inFence)
+            continue;
+        if (tok.definition) {
+            const { id, text } = tok.definition;
+            const arr = defTextsById.get(id);
+            if (arr)
+                arr.push(text);
+            else
+                defTextsById.set(id, [text]);
+            // A definition's TEXT can itself reference another footnote (`[^a]: see
+            // [^b]`); count those so such a `[^b]` is not falsely reported dangling.
+            forEachFootnoteReference(text, (rid) => addRef(rid, false));
+            continue;
+        }
+        const inTable = tok.line.trimStart().startsWith("|");
+        forEachFootnoteReference(tok.line, (id) => addRef(id, inTable));
+    }
+    const danglingReferences = refIds.filter((id) => !defTextsById.has(id));
+    const duplicateDefinitions = [];
+    const emptyDefinitions = [];
+    for (const [id, texts] of defTextsById) {
+        if (texts.length >= 2)
+            duplicateDefinitions.push(id);
+        // First-wins: the kept definition is the first one; flag it if it is blank.
+        if ((texts[0] ?? "").trim().length === 0)
+            emptyDefinitions.push(id);
+    }
+    const tableRefs = [...referencesInTables];
+    const warnings = [];
+    const list = (ids) => ids.map((id) => `[^${id}]`).join(", ");
+    if (danglingReferences.length > 0) {
+        warnings.push(`Footnote reference(s) with no matching definition: ${list(danglingReferences)} (each will render as an empty footnote in the editor).`);
+    }
+    if (emptyDefinitions.length > 0) {
+        warnings.push(`Footnote definition(s) with empty text: ${list(emptyDefinitions)}.`);
+    }
+    if (duplicateDefinitions.length > 0) {
+        warnings.push(`Footnote id(s) defined more than once (only the first definition was kept): ${list(duplicateDefinitions)}.`);
+    }
+    if (tableRefs.length > 0) {
+        warnings.push(`Footnote marker(s) inside a table row (footnotes in table cells may not render as expected): ${list(tableRefs)}.`);
+    }
+    return {
+        danglingReferences,
+        emptyDefinitions,
+        duplicateDefinitions,
+        referencesInTables: tableRefs,
+        warnings,
+    };
+}
+/**
+ * The optional `footnoteWarnings` field for a page-write tool result: present
+ * (with the warning lines) only when `markdown` has footnote problems, omitted
+ * otherwise. One helper so all three call sites (create/update/import) attach the
+ * field identically. Spread into the result: `{ ...result, ...footnoteWarningsField(text) }`.
+ */
+export function footnoteWarningsField(markdown) {
+    const { warnings } = analyzeFootnotes(markdown);
+    return warnings.length > 0 ? { footnoteWarnings: warnings } : {};
+}

packages/mcp/build/lib/footnote-lex.js

@@ -0,0 +1,55 @@
+/**
+ * Shared, fence-aware line lexer for footnote markdown (MCP-internal).
+ *
+ * Both the importer (`extractFootnotes` in collaboration.ts, which strips
+ * definition lines and rebuilds a footnotes section) and the diagnostics
+ * (`analyzeFootnotes` in footnote-analyze.ts) must agree EXACTLY on which lines
+ * are definitions and which lines are inert (inside a code fence). Sharing one
+ * lexer makes "the analyzer sees what the importer leaves" a structural property
+ * instead of two hand-kept copies that can drift (#166 review).
+ *
+ * NOTE: this is deliberately NOT shared with editor-ext's
+ * `extractFootnoteDefinitions` — that lives in a different package and the
+ * decoupling between the editor and the MCP mirror is intentional.
+ */
+/** A footnote DEFINITION line: `[^id]: text` (id + text captured). */
+export const FOOTNOTE_DEF_RE = /^\[\^([^\]\s]+)\]:[ \t]*(.*)$/;
+/** Every footnote REFERENCE `[^id]` in a line (global; id captured). */
+export const FOOTNOTE_REF_RE_G = /\[\^([^\]\s]+)\]/g;
+/** Opening/closing code fence marker (``` or ~~~). */
+const FENCE_RE = /^(\s*)(`{3,}|~{3,})/;
+/** Classify every line of `markdown`, tracking fenced-code state. Pure. */
+export function lexFootnoteLines(markdown) {
+    const out = [];
+    let fence = null;
+    for (const line of markdown.split("\n")) {
+        const fenceMatch = FENCE_RE.exec(line);
+        if (fenceMatch) {
+            const marker = fenceMatch[2][0];
+            if (fence === null)
+                fence = marker; // opening fence
+            else if (marker === fence)
+                fence = null; // matching closing fence
+            out.push({ line, inFence: true, definition: null });
+            continue;
+        }
+        if (fence !== null) {
+            out.push({ line, inFence: true, definition: null });
+            continue;
+        }
+        const m = FOOTNOTE_DEF_RE.exec(line);
+        out.push({
+            line,
+            inFence: false,
+            definition: m ? { id: m[1], text: m[2] } : null,
+        });
+    }
+    return out;
+}
+/** Scan a line for every `[^id]` reference, invoking `onRef(id)` for each. */
+export function forEachFootnoteReference(line, onRef) {
+    FOOTNOTE_REF_RE_G.lastIndex = 0;
+    let m;
+    while ((m = FOOTNOTE_REF_RE_G.exec(line)) !== null)
+        onRef(m[1]);
+}

packages/mcp/src/client.ts

@@ -20,9 +20,10 @@ import {
   mutatePageContent,
   buildCollabWsUrl,
   assertYjsEncodable,
+  applyDocToFragment,
   MutationResult,
 } from "./lib/collaboration.js";
-import { docmostExtensions } from "./lib/docmost-schema.js";
+import { footnoteWarningsField } from "./lib/footnote-analyze.js";
 import { buildPageTree } from "./lib/tree.js";
 import {
   serializeDocmostMarkdown,
@@ -48,10 +49,7 @@ import {
 } from "./lib/json-edit.js";
 import { getCollabToken, performLogin } from "./lib/auth-utils.js";
 import { diffDocs, summarizeChange } from "./lib/diff.js";
-import {
-  applyAnchorInDoc,
-  canAnchorInDoc,
-} from "./lib/comment-anchor.js";
+import { applyAnchorInDoc, canAnchorInDoc } from "./lib/comment-anchor.js";
 import {
   blockText,
   walk,
@@ -304,7 +302,9 @@ export class DocmostClient {
       // getCollabToken wraps the AxiosError in a plain Error but attaches the
       // HTTP status as `.status`, so detect an auth failure via either the raw
       // AxiosError shape OR the attached status.
-      const axiosStatus = axios.isAxiosError(e) ? e.response?.status : undefined;
+      const axiosStatus = axios.isAxiosError(e)
+        ? e.response?.status
+        : undefined;
       const attachedStatus = (e as any)?.status;
       const isAuthError =
         axiosStatus === 401 ||
@@ -478,18 +478,14 @@ export class DocmostClient {
               return;
             }
 
-            const tempDoc = TiptapTransformer.toYdoc(
-              newDoc,
-              "default",
-              docmostExtensions,
-            );
-            const fragment = ydoc.getXmlFragment("default");
-            ydoc.transact(() => {
-              if (fragment.length > 0) {
-                fragment.delete(0, fragment.length);
-              }
-              Y.applyUpdate(ydoc, Y.encodeStateAsUpdate(tempDoc));
-            });
+            // Structural diff into the live fragment (issue #152), mirroring
+            // the main write path: preserves the Yjs ids of unchanged nodes so
+            // an open editor's cursor is not yanked to the end of the document.
+            // The previous destructive rewrite (delete-all + applyUpdate of a
+            // fresh Y.Doc) discarded every node id, so replaceImage — the only
+            // caller of this method — still reproduced the #152 cursor jump
+            // (#164). applyDocToFragment runs its own atomic `transact`.
+            applyDocToFragment(ydoc, newDoc);
           } catch (e) {
             finish(e instanceof Error ? e : new Error(String(e)));
             return;
@@ -600,11 +596,7 @@ export class DocmostClient {
    * sidebar requests and is bounded by that method's 10000-node cap (and skips
    * soft-deleted pages server-side).
    */
-  async listPages(
-    spaceId?: string,
-    limit: number = 50,
-    tree: boolean = false,
-  ) {
+  async listPages(spaceId?: string, limit: number = 50, tree: boolean = false) {
     await this.ensureAuthenticated();
 
     if (tree) {
@@ -883,7 +875,12 @@ export class DocmostClient {
         `table_insert_row: no table found for "${tableRef}" on page ${pageId} (use "#<index>" from get_outline, or a block id inside the table)`,
       );
     }
-    return { success: true, table: tableRef, inserted: true, verify: mutation.verify };
+    return {
+      success: true,
+      table: tableRef,
+      inserted: true,
+      verify: mutation.verify,
+    };
   }
 
   /**
@@ -902,7 +899,11 @@ export class DocmostClient {
       this.apiUrl,
       (liveDoc) => {
         deleted = false;
-        const { doc: nd, deleted: del } = deleteTableRow(liveDoc, tableRef, index);
+        const { doc: nd, deleted: del } = deleteTableRow(
+          liveDoc,
+          tableRef,
+          index,
+        );
         deleted = del;
         if (!deleted) return null; // table not found -> skip the write entirely
         return nd;
@@ -914,7 +915,12 @@ export class DocmostClient {
         `table_delete_row: no table found for "${tableRef}" on page ${pageId} (use "#<index>" from get_outline, or a block id inside the table)`,
       );
     }
-    return { success: true, table: tableRef, deleted: true, verify: mutation.verify };
+    return {
+      success: true,
+      table: tableRef,
+      deleted: true,
+      verify: mutation.verify,
+    };
   }
 
   /**
@@ -959,7 +965,13 @@ export class DocmostClient {
         `table_update_cell: no table found for "${tableRef}" on page ${pageId} (use "#<index>" from get_outline, or a block id inside the table)`,
       );
     }
-    return { success: true, table: tableRef, row, col, verify: mutation.verify };
+    return {
+      success: true,
+      table: tableRef,
+      row,
+      col,
+      verify: mutation.verify,
+    };
   }
 
   /**
@@ -1033,8 +1045,7 @@ export class DocmostClient {
         response = await axios.post(importUrl, form2, {
           headers: {
             ...form2.getHeaders(),
-            Authorization:
-              this.client.defaults.headers.common["Authorization"],
+            Authorization: this.client.defaults.headers.common["Authorization"],
           },
           timeout: 60000,
         });
@@ -1054,7 +1065,10 @@ export class DocmostClient {
       await this.client.post("/pages/update", { pageId: newPageId, title });
     }
 
-    return this.getPage(newPageId);
+    const page = await this.getPage(newPageId);
+    // Surface non-fatal footnote problems (dangling refs, empty/duplicate
+    // definitions, markers in tables) so the agent can fix its markup (#166).
+    return { ...page, ...footnoteWarningsField(content) };
   }
 
   /**
@@ -1065,10 +1079,11 @@ export class DocmostClient {
   async updatePage(pageId: string, content: string, title?: string) {
     await this.ensureAuthenticated();
 
-    if (title) {
-      await this.client.post("/pages/update", { pageId, title });
-    }
-
+    // Write the BODY first, then the title (#159 split-brain). If the collab
+    // body write fails (e.g. a persist timeout), the title must be left
+    // UNTOUCHED so the page never ends up with a new title over its old body.
+    // A title write failing AFTER a successful body is rarer (REST is fast) and
+    // leaves correct content under a stale title — the lesser inconsistency.
     let collabToken = "";
     let mutation;
     try {
@@ -1095,12 +1110,19 @@ export class DocmostClient {
       throw new Error(`Failed to update page content: ${error.message}`);
     }
 
+    // Body persisted successfully — now it is safe to set the title.
+    if (title) {
+      await this.client.post("/pages/update", { pageId, title });
+    }
+
     return {
       success: true,
       modified: true,
       message: "Page updated successfully.",
       pageId: pageId,
       verify: mutation.verify,
+      // Non-fatal footnote diagnostics (#166); omitted when there are none.
+      ...footnoteWarningsField(content),
     };
   }
 
@@ -1167,9 +1189,7 @@ export class DocmostClient {
       for (const mark of node.marks) {
         if (mark && mark.type === "link" && mark.attrs) {
           if (!this.isSafeUrl(mark.attrs.href, "link")) {
-            throw new Error(
-              `unsafe link href rejected: "${mark.attrs.href}"`,
-            );
+            throw new Error(`unsafe link href rejected: "${mark.attrs.href}"`);
           }
         }
       }
@@ -1228,7 +1248,11 @@ export class DocmostClient {
         "invalid ProseMirror document: every node must be an object with a string `type`",
       );
     }
-    if ("text" in node && node.type === "text" && typeof node.text !== "string") {
+    if (
+      "text" in node &&
+      node.type === "text" &&
+      typeof node.text !== "string"
+    ) {
       throw new Error(
         "invalid ProseMirror document: a text node must have a string `text`",
       );
@@ -1240,7 +1264,11 @@ export class DocmostClient {
         );
       }
       for (const mark of node.marks) {
-        if (!mark || typeof mark !== "object" || typeof mark.type !== "string") {
+        if (
+          !mark ||
+          typeof mark !== "object" ||
+          typeof mark.type !== "string"
+        ) {
           throw new Error(
             "invalid ProseMirror document: every mark must be an object with a string `type`",
           );
@@ -1315,10 +1343,8 @@ export class DocmostClient {
     // inject javascript:/data: link hrefs or media srcs straight into the doc.
     this.validateDocUrls(doc);
 
-    if (title) {
-      await this.client.post("/pages/update", { pageId, title });
-    }
-
+    // Write the BODY first, then the title (#159 split-brain): a failed body
+    // write (e.g. persist timeout) must not leave a new title over the old body.
     const collabToken = await this.getCollabTokenWithReauth();
     const mutation = await replacePageContent(
       pageId,
@@ -1327,6 +1353,11 @@ export class DocmostClient {
       this.apiUrl,
     );
 
+    // Body persisted successfully — now it is safe to set the title.
+    if (title) {
+      await this.client.post("/pages/update", { pageId, title });
+    }
+
     return {
       success: true,
       modified: true,
@@ -1344,9 +1375,7 @@ export class DocmostClient {
   async exportPageMarkdown(pageId: string): Promise<string> {
     await this.ensureAuthenticated();
     const page = await this.getPageRaw(pageId);
-    const body = page.content
-      ? convertProseMirrorToMarkdown(page.content)
-      : "";
+    const body = page.content ? convertProseMirrorToMarkdown(page.content) : "";
     let comments: any[] = [];
     try {
       comments = await this.listComments(pageId);
@@ -1416,6 +1445,11 @@ export class DocmostClient {
     if (meta?.pageId && meta.pageId !== pageId) {
       result.warning = `File was exported from page ${meta.pageId} but is being imported into ${pageId}.`;
     }
+    // Non-fatal footnote diagnostics (#166), analyzed on the BODY (the part after
+    // the docmost:meta / docmost:comments blocks) — so a `[^x]`-like token inside
+    // those JSON blocks never produces a false warning, while real markers in the
+    // body do. `body` comes from parseDocmostMarkdown(fullMarkdown) above.
+    Object.assign(result, footnoteWarningsField(body));
     return result;
   }
 
@@ -1555,9 +1589,10 @@ export class DocmostClient {
       pageId,
       applied: results,
       failed,
-      message: (failed?.length ?? 0)
-        ? `Applied ${results?.length ?? 0} edit(s); ${failed!.length} failed (see failed[]). Node ids and formatting preserved.`
-        : "Text edits applied (node ids and formatting preserved).",
+      message:
+        (failed?.length ?? 0)
+          ? `Applied ${results?.length ?? 0} edit(s); ${failed!.length} failed (see failed[]). Node ids and formatting preserved.`
+          : "Text edits applied (node ids and formatting preserved).",
       verify: mutation.verify,
     };
 
@@ -1616,9 +1651,19 @@ export class DocmostClient {
       this.apiUrl,
       (liveDoc) => {
         replaced = 0;
-        const { doc: nd, replaced: r } = replaceNodeById(liveDoc, nodeId, target);
+        const { doc: nd, replaced: r } = replaceNodeById(
+          liveDoc,
+          nodeId,
+          target,
+        );
         replaced = r;
-        if (replaced === 0) return null; // no match -> skip the write entirely
+        // 0 matches -> skip the write. >1 matches -> the id is AMBIGUOUS: Docmost
+        // duplicates block ids on copy/paste (and copyPageContent writes them
+        // verbatim), so replacing "the node with id X" would silently clobber
+        // EVERY duplicate (#159). Refuse: skip the write and throw below so the
+        // model re-targets with a more specific anchor instead of corrupting the
+        // page. Only an unambiguous single match is written.
+        if (replaced !== 1) return null;
         return nd;
       },
     );
@@ -1628,6 +1673,11 @@ export class DocmostClient {
         `patch_node: no node with id "${nodeId}" found on page ${pageId}`,
       );
     }
+    if (replaced > 1) {
+      throw new Error(
+        `patch_node: id "${nodeId}" is ambiguous — ${replaced} nodes on page ${pageId} share it (block ids are duplicated on copy/paste). Refusing to replace all of them; nothing was changed. Re-target with a more specific anchor.`,
+      );
+    }
 
     return { success: true, replaced, nodeId, verify: mutation.verify };
   }
@@ -1696,7 +1746,11 @@ export class DocmostClient {
       this.apiUrl,
       (liveDoc) => {
         inserted = false;
-        const { doc: nd, inserted: ins } = insertNodeRelative(liveDoc, node, opts);
+        const { doc: nd, inserted: ins } = insertNodeRelative(
+          liveDoc,
+          node,
+          opts,
+        );
         inserted = ins;
         if (!inserted) return null; // anchor not found -> skip the write entirely
         return nd;
@@ -1711,7 +1765,7 @@ export class DocmostClient {
       // markdown/emoji are tolerated only as a strip-and-retry fallback, so a
       // miss usually means the text differs from what's on the page.
       const hint = opts.anchorText
-        ? ' anchorText must be the block\'s literal rendered plain text (no markdown wrappers or emoji); anchorNodeId from get_page_json is more reliable.'
+        ? " anchorText must be the block's literal rendered plain text (no markdown wrappers or emoji); anchorNodeId from get_page_json is more reliable."
         : "";
       throw new Error(
         `insert_node: anchor not found (${anchorDesc}) on page ${pageId}.${hint}`,
@@ -1748,7 +1802,12 @@ export class DocmostClient {
         deleted = 0;
         const { doc: nd, deleted: d } = deleteNodeById(liveDoc, nodeId);
         deleted = d;
-        if (deleted === 0) return null; // no match -> skip the write entirely
+        // 0 matches -> skip the write. >1 matches -> the id is AMBIGUOUS (block
+        // ids are duplicated on copy/paste, #159): deleting "the node with id X"
+        // would silently remove EVERY duplicate. Refuse: skip the write and throw
+        // below so the model re-targets. Only an unambiguous single match is
+        // deleted.
+        if (deleted !== 1) return null;
         return nd;
       },
     );
@@ -1758,6 +1817,11 @@ export class DocmostClient {
         `delete_node: no node with id "${nodeId}" found on page ${pageId}`,
       );
     }
+    if (deleted > 1) {
+      throw new Error(
+        `delete_node: id "${nodeId}" is ambiguous — ${deleted} nodes on page ${pageId} share it (block ids are duplicated on copy/paste). Refusing to delete all of them; nothing was changed. Re-target with a more specific anchor.`,
+      );
+    }
 
     return { success: true, deleted, nodeId, verify: mutation.verify };
   }
@@ -2129,7 +2193,11 @@ export class DocmostClient {
    * subtree): pages updated after `since` are scanned and their comments
    * filtered by createdAt > since.
    */
-  async checkNewComments(spaceId: string, since: string, parentPageId?: string) {
+  async checkNewComments(
+    spaceId: string,
+    since: string,
+    parentPageId?: string,
+  ) {
     await this.ensureAuthenticated();
 
     const sinceDate = new Date(since);
@@ -2429,8 +2497,7 @@ export class DocmostClient {
         response = await axios.post(uploadUrl, form2, {
           headers: {
             ...form2.getHeaders(),
-            Authorization:
-              this.client.defaults.headers.common["Authorization"],
+            Authorization: this.client.defaults.headers.common["Authorization"],
           },
           timeout: 60000,
         });
@@ -2517,76 +2584,76 @@ export class DocmostClient {
       collabToken,
       this.apiUrl,
       (liveDoc) => {
-      const doc =
-        liveDoc && liveDoc.type === "doc"
-          ? liveDoc
-          : { type: "doc", content: [] };
-      if (!Array.isArray(doc.content)) doc.content = [];
+        const doc =
+          liveDoc && liveDoc.type === "doc"
+            ? liveDoc
+            : { type: "doc", content: [] };
+        if (!Array.isArray(doc.content)) doc.content = [];
 
-      if (opts.replaceText) {
-        // Ambiguity guard (mirrors editPageText): count matching top-level
-        // blocks first, so a non-unique fragment cannot silently replace the
-        // wrong block (e.g. text that also appears inside a callout/table).
-        const matches = doc.content.filter((b: any) =>
-          blockText(b).includes(opts.replaceText!),
-        );
-        if (matches.length === 0) {
-          throw new Error(`replaceText not found: "${opts.replaceText}"`);
-        }
-        if (matches.length > 1) {
-          throw new Error(
-            `replaceText "${opts.replaceText}" matches ${matches.length} blocks; use a longer unique fragment`,
+        if (opts.replaceText) {
+          // Ambiguity guard (mirrors editPageText): count matching top-level
+          // blocks first, so a non-unique fragment cannot silently replace the
+          // wrong block (e.g. text that also appears inside a callout/table).
+          const matches = doc.content.filter((b: any) =>
+            blockText(b).includes(opts.replaceText!),
           );
-        }
-        const idx = doc.content.findIndex((b: any) =>
-          blockText(b).includes(opts.replaceText!),
-        );
-        // Data-loss guard: replaceText swaps the WHOLE top-level block, so if
-        // the fragment only appears nested inside a container (table, callout,
-        // list, blockquote) the entire structure would be destroyed. Refuse
-        // when the matched block is a container rather than a leaf
-        // paragraph/heading and point the caller at a safer tool.
-        const CONTAINER_TYPES = new Set([
-          "table",
-          "callout",
-          "bulletList",
-          "orderedList",
-          "taskList",
-          "blockquote",
-        ]);
-        const matchedBlock = doc.content[idx];
-        if (matchedBlock && CONTAINER_TYPES.has(matchedBlock.type)) {
-          throw new Error(
-            `replaceText matched a ${matchedBlock.type} container block; replacing it would destroy the whole structure. ` +
-              `Use afterText to insert near it, or update_page_json for surgical edits.`,
+          if (matches.length === 0) {
+            throw new Error(`replaceText not found: "${opts.replaceText}"`);
+          }
+          if (matches.length > 1) {
+            throw new Error(
+              `replaceText "${opts.replaceText}" matches ${matches.length} blocks; use a longer unique fragment`,
+            );
+          }
+          const idx = doc.content.findIndex((b: any) =>
+            blockText(b).includes(opts.replaceText!),
           );
-        }
-        doc.content.splice(idx, 1, node);
-        placement = "replaced";
-      } else if (opts.afterText) {
-        // Ambiguity guard (mirrors editPageText): refuse a non-unique fragment.
-        const matches = doc.content.filter((b: any) =>
-          blockText(b).includes(opts.afterText!),
-        );
-        if (matches.length === 0) {
-          throw new Error(`afterText not found: "${opts.afterText}"`);
-        }
-        if (matches.length > 1) {
-          throw new Error(
-            `afterText "${opts.afterText}" matches ${matches.length} blocks; use a longer unique fragment`,
+          // Data-loss guard: replaceText swaps the WHOLE top-level block, so if
+          // the fragment only appears nested inside a container (table, callout,
+          // list, blockquote) the entire structure would be destroyed. Refuse
+          // when the matched block is a container rather than a leaf
+          // paragraph/heading and point the caller at a safer tool.
+          const CONTAINER_TYPES = new Set([
+            "table",
+            "callout",
+            "bulletList",
+            "orderedList",
+            "taskList",
+            "blockquote",
+          ]);
+          const matchedBlock = doc.content[idx];
+          if (matchedBlock && CONTAINER_TYPES.has(matchedBlock.type)) {
+            throw new Error(
+              `replaceText matched a ${matchedBlock.type} container block; replacing it would destroy the whole structure. ` +
+                `Use afterText to insert near it, or update_page_json for surgical edits.`,
+            );
+          }
+          doc.content.splice(idx, 1, node);
+          placement = "replaced";
+        } else if (opts.afterText) {
+          // Ambiguity guard (mirrors editPageText): refuse a non-unique fragment.
+          const matches = doc.content.filter((b: any) =>
+            blockText(b).includes(opts.afterText!),
           );
+          if (matches.length === 0) {
+            throw new Error(`afterText not found: "${opts.afterText}"`);
+          }
+          if (matches.length > 1) {
+            throw new Error(
+              `afterText "${opts.afterText}" matches ${matches.length} blocks; use a longer unique fragment`,
+            );
+          }
+          const idx = doc.content.findIndex((b: any) =>
+            blockText(b).includes(opts.afterText!),
+          );
+          doc.content.splice(idx + 1, 0, node);
+          placement = "after";
+        } else {
+          doc.content.push(node);
+          placement = "appended";
         }
-        const idx = doc.content.findIndex((b: any) =>
-          blockText(b).includes(opts.afterText!),
-        );
-        doc.content.splice(idx + 1, 0, node);
-        placement = "after";
-      } else {
-        doc.content.push(node);
-        placement = "appended";
-      }
 
-      return doc;
+        return doc;
       },
     );
 
@@ -2843,8 +2910,7 @@ export class DocmostClient {
   async diffPageVersions(pageId: string, from?: string, to?: string) {
     await this.ensureAuthenticated();
 
-    const isCurrent = (v?: string) =>
-      v == null || v === "" || v === "current";
+    const isCurrent = (v?: string) => v == null || v === "" || v === "current";
 
     const resolveSide = async (
       v?: string,
@@ -2965,7 +3031,9 @@ export class DocmostClient {
         throw new Error(`transform did not compile: ${e?.message ?? e}`);
       }
       if (typeof fn !== "function") {
-        throw new Error("transform must evaluate to a function (doc, ctx) => doc");
+        throw new Error(
+          "transform must evaluate to a function (doc, ctx) => doc",
+        );
       }
       const result = vm.runInNewContext(
         "f(d, c)",

packages/mcp/src/lib/collaboration.ts

@@ -10,6 +10,7 @@ import { JSDOM } from "jsdom";
 import { docmostExtensions, docmostSchema } from "./docmost-schema.js";
 import { withPageLock } from "./page-lock.js";
 import { sanitizeForYjs, findUnstorableAttr } from "./node-ops.js";
+import { lexFootnoteLines } from "./footnote-lex.js";
 import { summarizeChange, VerifyReport } from "./diff.js";
 
 /**
@@ -316,58 +317,14 @@ function bridgeTaskLists(html: string): string {
 // Mirror of packages/editor-ext footnote markdown handling. A `[^id]` inline
 // marker becomes <sup data-footnote-ref data-id="id">, and `[^id]: text`
 // definition lines are collected into a single <section data-footnotes>.
-const FOOTNOTE_DEF_RE = /^\[\^([^\]\s]+)\]:[ \t]*(.*)$/;
+// Definition detection + fence handling are shared with analyzeFootnotes via
+// lexFootnoteLines (footnote-lex.js). FOOTNOTE_REF_RE is the inline tokenizer's.
 const FOOTNOTE_REF_RE = /\[\^([^\]\s]+)\]/;
 
 function escapeFootnoteAttr(value: string): string {
   return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
 }
 
-function escapeFootnoteRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-/**
- * Derive a DETERMINISTIC unique footnote id for the k-th (k >= 2) occurrence of
- * an original id `X` during definition dedup.
- *
- * EXACT MIRROR of editor-ext `deriveFootnoteId`
- * (packages/editor-ext/src/lib/footnote/footnote-util.ts). These two copies MUST
- * STAY IN SYNC: the same markdown imported through the editor and through this
- * MCP path has to produce identical ids, and the sync plugin (which re-ids on
- * every collaborating client) relies on the same scheme to converge. NEVER use
- * Math.random()/Date.now()/uuid here — a random id would diverge across clients.
- *
- * Scheme: base candidate `${originalId}__${occurrence}` (e.g. `X__2`), bumped
- * with a stable alphabetic suffix (`X__2b`, `X__2c`, ...) until it is not in
- * `taken` (the set of ids already present / already minted — pure doc state).
- */
-function deriveFootnoteId(
-  originalId: string,
-  occurrence: number,
-  taken: Set<string>,
-): string {
-  let candidate = `${originalId}__${occurrence}`;
-  let n = 0;
-  while (taken.has(candidate)) {
-    n += 1;
-    candidate = `${originalId}__${occurrence}${footnoteSuffix(n)}`;
-  }
-  return candidate;
-}
-
-/** Map 1 -> "b", 2 -> "c", ... (mirror of editor-ext `suffix`). */
-function footnoteSuffix(n: number): string {
-  let out = "";
-  let x = n;
-  while (x > 0) {
-    const rem = (x - 1) % 25;
-    out = String.fromCharCode(98 + rem) + out; // 98 = 'b'
-    x = Math.floor((x - 1) / 25);
-  }
-  return out;
-}
-
 const footnoteRefMarkedExtension = {
   name: "footnoteRef",
   level: "inline" as const,
@@ -398,69 +355,39 @@ function extractFootnotes(markdown: string): {
   body: string;
   section: string;
 } {
-  const lines = markdown.split("\n");
   const bodyLines: string[] = [];
   const defs: Array<{ id: string; text: string }> = [];
-  // Track fenced-code state so a `[^id]: ...` line shown inside a ``` / ~~~ code
-  // block is preserved verbatim and not treated as a footnote definition.
-  let fence: string | null = null;
-  for (const line of lines) {
-    const fenceMatch = /^(\s*)(`{3,}|~{3,})/.exec(line);
-    if (fenceMatch) {
-      const marker = fenceMatch[2][0];
-      if (fence === null) fence = marker;
-      else if (marker === fence) fence = null;
-      bodyLines.push(line);
-      continue;
-    }
-    const m = fence === null ? FOOTNOTE_DEF_RE.exec(line) : null;
-    if (m) defs.push({ id: m[1], text: m[2] });
-    else bodyLines.push(line);
+  // Shared lexer (footnote-lex): a `[^id]: ...` line inside a ``` / ~~~ code
+  // block is inert and stays in the body verbatim; only real definition lines
+  // are pulled out. analyzeFootnotes() consumes the SAME lexer so its diagnostics
+  // match exactly what import keeps/strips (#166).
+  for (const tok of lexFootnoteLines(markdown)) {
+    if (!tok.inFence && tok.definition) defs.push(tok.definition);
+    else bodyLines.push(tok.line);
   }
   if (defs.length === 0) return { body: markdown, section: "" };
 
-  // De-duplicate colliding definition ids (mirror of editor-ext
-  // extractFootnoteDefinitions). Two definitions sharing an id would otherwise
-  // collapse into one footnote downstream; rename each colliding id to a
-  // DETERMINISTIC derived one (NOT random) and rewrite the corresponding `[^id]`
-  // marker so the (reference, definition) pairing stays 1:1. Determinism lets
-  // the same markdown imported here and via the editor produce identical ids.
-  let dedupedBody = bodyLines.join("\n");
-  const taken = new Set<string>(defs.map((d) => d.id));
-  const seenDefIds = new Map<string, number>();
+  // Duplicate definition ids: FIRST WINS, the rest are DROPPED (mirror of
+  // editor-ext extractFootnoteDefinitions). Reference markers are left untouched
+  // so repeated `[^a]` references reuse the single footnote (Pandoc semantics,
+  // #166). The dropped duplicate is surfaced to the caller via analyzeFootnotes
+  // (`duplicateDefinitions`), not silently lost. MUST stay in sync with the
+  // editor-ext mirror.
+  const firstById = new Map<string, string>(); // id -> first definition text
   for (const def of defs) {
-    const originalId = def.id;
-    const count = seenDefIds.get(originalId) ?? 0;
-    seenDefIds.set(originalId, count + 1);
-    if (count === 0) continue; // first definition keeps its id
-    const newId = deriveFootnoteId(originalId, count + 1, taken);
-    taken.add(newId);
-    def.id = newId;
-    // Remaining `[^originalId]` matches: index 0 = keeper's marker (left alone),
-    // index 1 = this duplicate's marker. Rewrite index 1.
-    let occurrence = 0;
-    let rewritten = false;
-    const re = new RegExp(`\\[\\^${escapeFootnoteRegExp(originalId)}\\]`, "g");
-    dedupedBody = dedupedBody.replace(re, (match) => {
-      const idx = occurrence++;
-      if (!rewritten && idx === 1) {
-        rewritten = true;
-        return `[^${newId}]`;
-      }
-      return match;
-    });
+    if (!firstById.has(def.id)) firstById.set(def.id, def.text);
   }
 
-  const inner = defs
+  const inner = [...firstById.entries()]
     .map(
-      (d) =>
+      ([id, text]) =>
         `<div data-footnote-def data-id="${escapeFootnoteAttr(
-          d.id,
-        )}"><p>${marked.parseInline(d.text || "")}</p></div>`,
+          id,
+        )}"><p>${marked.parseInline(text || "")}</p></div>`,
     )
     .join("");
   return {
-    body: dedupedBody,
+    body: bodyLines.join("\n"),
     section: `<section data-footnotes>${inner}</section>`,
   };
 }

packages/mcp/src/lib/footnote-analyze.ts

@@ -0,0 +1,129 @@
+/**
+ * Footnote diagnostics for imported Markdown (issue #166).
+ *
+ * A PURE, fence-aware text scan (independent of the Markdown->ProseMirror
+ * conversion path, so it reports the same problems for `create_page`,
+ * `update_page` and `import_page_markdown`). It never changes the document — the
+ * importer still creates the page; this only surfaces footnote problems to the
+ * caller so an agent can fix its own markup instead of shipping broken footnotes.
+ *
+ * Detected problems:
+ *  - danglingReferences: a `[^id]` reference with no `[^id]:` definition.
+ *  - emptyDefinitions:   a `[^id]:` whose (kept) text is empty/whitespace.
+ *  - duplicateDefinitions: an id defined by two or more `[^id]:` lines (only the
+ *    first is kept on import — first-wins; see extractFootnotes).
+ *  - referencesInTables: a `[^id]` marker found in a GFM table row (heuristic:
+ *    the line, trimmed, starts with `|`) — footnotes in table cells often do not
+ *    render as expected.
+ */
+
+import {
+  lexFootnoteLines,
+  forEachFootnoteReference,
+} from "./footnote-lex.js";
+
+export interface FootnoteDiagnostics {
+  /** Reference ids (distinct, document order) with no matching definition. */
+  danglingReferences: string[];
+  /** Definition ids whose first (kept) text is empty/whitespace. */
+  emptyDefinitions: string[];
+  /** Ids defined by two or more `[^id]:` lines (only the first is kept). */
+  duplicateDefinitions: string[];
+  /** Reference ids found inside a GFM table row (heuristic). */
+  referencesInTables: string[];
+  /** Human-readable warning lines for the tool result (one per problem class). */
+  warnings: string[];
+}
+
+/**
+ * Analyze the footnotes in a Markdown string. Pure; safe to call on any body.
+ */
+export function analyzeFootnotes(markdown: string): FootnoteDiagnostics {
+  // Distinct reference ids in first-appearance order, plus the set of ids seen
+  // inside a table row.
+  const refIds: string[] = [];
+  const refIdSet = new Set<string>();
+  const referencesInTables = new Set<string>();
+  const addRef = (id: string, inTable: boolean) => {
+    if (!refIdSet.has(id)) {
+      refIdSet.add(id);
+      refIds.push(id);
+    }
+    if (inTable) referencesInTables.add(id);
+  };
+
+  // Definition texts per id, in first-appearance order of the id.
+  const defTextsById = new Map<string, string[]>();
+
+  // Same lexer the importer uses, so the analysis matches exactly what import
+  // keeps/strips (#166): fenced lines are inert, definition lines are pulled.
+  for (const tok of lexFootnoteLines(markdown)) {
+    if (tok.inFence) continue;
+    if (tok.definition) {
+      const { id, text } = tok.definition;
+      const arr = defTextsById.get(id);
+      if (arr) arr.push(text);
+      else defTextsById.set(id, [text]);
+      // A definition's TEXT can itself reference another footnote (`[^a]: see
+      // [^b]`); count those so such a `[^b]` is not falsely reported dangling.
+      forEachFootnoteReference(text, (rid) => addRef(rid, false));
+      continue;
+    }
+    const inTable = tok.line.trimStart().startsWith("|");
+    forEachFootnoteReference(tok.line, (id) => addRef(id, inTable));
+  }
+
+  const danglingReferences = refIds.filter((id) => !defTextsById.has(id));
+  const duplicateDefinitions: string[] = [];
+  const emptyDefinitions: string[] = [];
+  for (const [id, texts] of defTextsById) {
+    if (texts.length >= 2) duplicateDefinitions.push(id);
+    // First-wins: the kept definition is the first one; flag it if it is blank.
+    if ((texts[0] ?? "").trim().length === 0) emptyDefinitions.push(id);
+  }
+  const tableRefs = [...referencesInTables];
+
+  const warnings: string[] = [];
+  const list = (ids: string[]) => ids.map((id) => `[^${id}]`).join(", ");
+  if (danglingReferences.length > 0) {
+    warnings.push(
+      `Footnote reference(s) with no matching definition: ${list(danglingReferences)} (each will render as an empty footnote in the editor).`,
+    );
+  }
+  if (emptyDefinitions.length > 0) {
+    warnings.push(
+      `Footnote definition(s) with empty text: ${list(emptyDefinitions)}.`,
+    );
+  }
+  if (duplicateDefinitions.length > 0) {
+    warnings.push(
+      `Footnote id(s) defined more than once (only the first definition was kept): ${list(duplicateDefinitions)}.`,
+    );
+  }
+  if (tableRefs.length > 0) {
+    warnings.push(
+      `Footnote marker(s) inside a table row (footnotes in table cells may not render as expected): ${list(tableRefs)}.`,
+    );
+  }
+
+  return {
+    danglingReferences,
+    emptyDefinitions,
+    duplicateDefinitions,
+    referencesInTables: tableRefs,
+    warnings,
+  };
+}
+
+/**
+ * The optional `footnoteWarnings` field for a page-write tool result: present
+ * (with the warning lines) only when `markdown` has footnote problems, omitted
+ * otherwise. One helper so all three call sites (create/update/import) attach the
+ * field identically. Spread into the result: `{ ...result, ...footnoteWarningsField(text) }`.
+ */
+export function footnoteWarningsField(markdown: string): {
+  footnoteWarnings?: string[];
+} {
+  const { warnings } = analyzeFootnotes(markdown);
+  return warnings.length > 0 ? { footnoteWarnings: warnings } : {};
+}

packages/mcp/src/lib/footnote-lex.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared, fence-aware line lexer for footnote markdown (MCP-internal).
+ *
+ * Both the importer (`extractFootnotes` in collaboration.ts, which strips
+ * definition lines and rebuilds a footnotes section) and the diagnostics
+ * (`analyzeFootnotes` in footnote-analyze.ts) must agree EXACTLY on which lines
+ * are definitions and which lines are inert (inside a code fence). Sharing one
+ * lexer makes "the analyzer sees what the importer leaves" a structural property
+ * instead of two hand-kept copies that can drift (#166 review).
+ *
+ * NOTE: this is deliberately NOT shared with editor-ext's
+ * `extractFootnoteDefinitions` — that lives in a different package and the
+ * decoupling between the editor and the MCP mirror is intentional.
+ */
+
+/** A footnote DEFINITION line: `[^id]: text` (id + text captured). */
+export const FOOTNOTE_DEF_RE = /^\[\^([^\]\s]+)\]:[ \t]*(.*)$/;
+/** Every footnote REFERENCE `[^id]` in a line (global; id captured). */
+export const FOOTNOTE_REF_RE_G = /\[\^([^\]\s]+)\]/g;
+/** Opening/closing code fence marker (``` or ~~~). */
+const FENCE_RE = /^(\s*)(`{3,}|~{3,})/;
+
+export interface FootnoteLine {
+  /** The raw line, verbatim. */
+  line: string;
+  /**
+   * True for a code-fence marker line AND every line inside a fence — footnote
+   * syntax on such lines is inert (example text, not real markup). The importer
+   * keeps these in the body; the analyzer skips them.
+   */
+  inFence: boolean;
+  /** The parsed definition, when this is a `[^id]: text` line OUTSIDE any fence. */
+  definition: { id: string; text: string } | null;
+}
+
+/** Classify every line of `markdown`, tracking fenced-code state. Pure. */
+export function lexFootnoteLines(markdown: string): FootnoteLine[] {
+  const out: FootnoteLine[] = [];
+  let fence: string | null = null;
+  for (const line of markdown.split("\n")) {
+    const fenceMatch = FENCE_RE.exec(line);
+    if (fenceMatch) {
+      const marker = fenceMatch[2][0];
+      if (fence === null) fence = marker; // opening fence
+      else if (marker === fence) fence = null; // matching closing fence
+      out.push({ line, inFence: true, definition: null });
+      continue;
+    }
+    if (fence !== null) {
+      out.push({ line, inFence: true, definition: null });
+      continue;
+    }
+    const m = FOOTNOTE_DEF_RE.exec(line);
+    out.push({
+      line,
+      inFence: false,
+      definition: m ? { id: m[1], text: m[2] } : null,
+    });
+  }
+  return out;
+}
+
+/** Scan a line for every `[^id]` reference, invoking `onRef(id)` for each. */
+export function forEachFootnoteReference(
+  line: string,
+  onRef: (id: string) => void,
+): void {
+  FOOTNOTE_REF_RE_G.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = FOOTNOTE_REF_RE_G.exec(line)) !== null) onRef(m[1]);
+}

packages/mcp/test/mock/footnote-warnings.test.mjs

@@ -0,0 +1,110 @@
+// Mock-HTTP test for the footnoteWarnings plumbing (#166). createPage is the
+// representative path that is fully plain-HTTP (import + getPage) and so is
+// mockable here; updatePage / importPageMarkdown attach footnoteWarnings with the
+// IDENTICAL wiring (`analyzeFootnotes(...)` + spread-when-non-empty) but run their
+// mutation over the Hocuspocus collab WebSocket, which this plain-HTTP harness
+// does not stand up. The analyzer itself is unit-tested in footnote-analyze.test.
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import http from "node:http";
+import { DocmostClient } from "../../build/client.js";
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    let raw = "";
+    req.on("data", (c) => (raw += c));
+    req.on("end", () => resolve(raw));
+  });
+}
+
+function sendJson(res, status, obj, extraHeaders = {}) {
+  res.writeHead(status, { "Content-Type": "application/json", ...extraHeaders });
+  res.end(JSON.stringify(obj));
+}
+
+const openServers = [];
+function spawn(handler) {
+  return new Promise((resolve) => {
+    const server = http.createServer(handler);
+    openServers.push(server);
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      resolve(`http://127.0.0.1:${port}/api`);
+    });
+  });
+}
+
+after(async () => {
+  await Promise.all(
+    openServers.map((s) => new Promise((r) => s.close(r))),
+  );
+});
+
+// A handler that imports a page, lets getPage read it back, and 404s everything
+// else (listSidebarPages fails gracefully inside getPage).
+function pageHandler() {
+  return async (req, res) => {
+    await readBody(req);
+    if (req.url === "/api/auth/login") {
+      sendJson(res, 200, { success: true }, {
+        "Set-Cookie": "authToken=t; Path=/; HttpOnly",
+      });
+      return;
+    }
+    if (req.url === "/api/pages/import") {
+      sendJson(res, 200, { data: { id: "new-1" } });
+      return;
+    }
+    if (req.url === "/api/pages/update") {
+      // The title-restore step after import.
+      sendJson(res, 200, { data: { id: "new-1" } });
+      return;
+    }
+    if (req.url === "/api/pages/info") {
+      sendJson(res, 200, {
+        data: {
+          id: "new-1",
+          slugId: "slug-1",
+          title: "T",
+          spaceId: "sp-1",
+          content: { type: "doc", content: [] },
+        },
+      });
+      return;
+    }
+    sendJson(res, 404, { message: "not found" });
+  };
+}
+
+test("createPage attaches footnoteWarnings when the content has footnote problems", async () => {
+  const baseURL = await spawn(pageHandler());
+  const client = new DocmostClient(baseURL, "user@example.com", "pw");
+  // A dangling reference + a duplicate definition + a table marker.
+  const content = [
+    "Intro[^missing] and| cell[^t] |.",
+    "",
+    "[^d]: one",
+    "[^d]: two",
+    "[^t]: in table",
+  ].join("\n");
+  const result = await client.createPage("T", content, "sp-1");
+  assert.ok(Array.isArray(result.footnoteWarnings), "footnoteWarnings present");
+  const joined = result.footnoteWarnings.join("\n");
+  assert.match(joined, /no matching definition/); // dangling [^missing]
+  assert.match(joined, /defined more than once/); // duplicate [^d]
+  // The page itself is still returned.
+  assert.equal(result.success, true);
+});
+
+test("createPage omits footnoteWarnings when the content is clean", async () => {
+  const baseURL = await spawn(pageHandler());
+  const client = new DocmostClient(baseURL, "user@example.com", "pw");
+  const content = ["A[^a] and reuse[^a].", "", "[^a]: fine"].join("\n");
+  const result = await client.createPage("T", content, "sp-1");
+  assert.equal(
+    "footnoteWarnings" in result,
+    false,
+    "no footnoteWarnings field on clean input",
+  );
+  assert.equal(result.success, true);
+});

packages/mcp/test/unit/comment-cursor-stability.test.mjs

@@ -162,3 +162,70 @@ test("assertYjsEncodable rejects an un-hydratable doc at preview time (fromJSON
     /Failed to encode document to Yjs/,
   );
 });
+
+// Issue #164: `replaceImage` went through `mutateLiveContentUnlocked`, which
+// (unlike the main write path fixed in #152) still deleted the whole fragment
+// and re-applied a fresh Y.Doc — discarding every node id, so an open editor's
+// cursor jumped to the document end on an image swap. That method now uses the
+// same `applyDocToFragment`, so a sibling paragraph's cursor anchor survives an
+// image `src`/`attachmentId` replacement. These exercise that routine on the
+// image shapes `replaceImage` produces (top-level and nested in a callout).
+
+const image = (attachmentId, src) => ({
+  type: "image",
+  attrs: { attachmentId, src, width: "640", align: "center" },
+});
+
+test("replacing a top-level image keeps a sibling paragraph's cursor anchor (#164)", () => {
+  const ydoc = new Y.Doc();
+  applyDocToFragment(
+    ydoc,
+    doc(para("Caption above"), image("att-old", "/files/old.png")),
+  );
+
+  // The user's cursor sits in the (unchanged) caption paragraph.
+  const relPos = Y.createRelativePositionFromTypeIndex(paragraphText(ydoc, 0), 7);
+
+  // Agent repoints the image to a freshly uploaded attachment (new id + src).
+  applyDocToFragment(
+    ydoc,
+    doc(para("Caption above"), image("att-new", "/files/new.png")),
+  );
+
+  const abs = Y.createAbsolutePositionFromRelativePosition(relPos, ydoc);
+  assert.notEqual(abs, null, "the caption cursor anchor must still resolve");
+  assert.equal(abs.index, 7, "the cursor must stay at the same offset");
+  // The swap actually landed: the image now carries the new attachment id/src.
+  const img = ydoc.getXmlFragment("default").get(1);
+  assert.equal(img.nodeName, "image");
+  assert.equal(img.getAttribute("attachmentId"), "att-new");
+  assert.equal(img.getAttribute("src"), "/files/new.png");
+});
+
+test("replacing an image nested in a callout keeps an outer paragraph's anchor (#164)", () => {
+  const callout = (attachmentId, src) => ({
+    type: "callout",
+    attrs: { type: "info" },
+    content: [image(attachmentId, src)],
+  });
+  const ydoc = new Y.Doc();
+  applyDocToFragment(
+    ydoc,
+    doc(para("Intro paragraph"), callout("att-old", "/files/old.png")),
+  );
+
+  const relPos = Y.createRelativePositionFromTypeIndex(paragraphText(ydoc, 0), 5);
+
+  applyDocToFragment(
+    ydoc,
+    doc(para("Intro paragraph"), callout("att-new", "/files/new.png")),
+  );
+
+  const abs = Y.createAbsolutePositionFromRelativePosition(relPos, ydoc);
+  assert.notEqual(abs, null, "the outer paragraph anchor must still resolve");
+  assert.equal(abs.index, 5, "the cursor must stay at the same offset");
+  // The nested image was repointed.
+  const calloutEl = ydoc.getXmlFragment("default").get(1);
+  const img = calloutEl.get(0);
+  assert.equal(img.getAttribute("attachmentId"), "att-new");
+});

packages/mcp/test/unit/derive-id-parity.test.mjs

@@ -1,134 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import { markdownToProseMirror } from "../../build/lib/collaboration.js";
-
-/**
- * CROSS-PACKAGE DRIFT GUARD for the footnote id derivation scheme.
- *
- * `deriveFootnoteId` is duplicated in two places that MUST behave identically:
- *   - packages/editor-ext/src/lib/footnote/footnote-util.ts (exported)
- *   - packages/mcp/src/lib/collaboration.ts                  (internal helper)
- * so the same markdown imported through the editor and through the MCP path
- * derives identical footnote ids.
- *
- * The mcp copy is NOT exported from the compiled build (it is an internal helper
- * of collaboration.js), and production source must not be modified to export it.
- * So this test exercises the REAL compiled `deriveFootnoteId` *indirectly*, the
- * same way production does: through `markdownToProseMirror`, which runs
- * extractFootnotes -> deriveFootnoteId during duplicate-id dedup. We craft the
- * `taken` set via literal pre-existing definition ids and read back the derived
- * footnoteDefinition ids.
- *
- * GOLDEN below mirrors DERIVE_GOLDEN in
- *   packages/editor-ext/src/lib/footnote/footnote-util.derive-id.test.ts
- * (asserted there by a DIRECT call). Same (originalId, occurrence, taken) ->
- * same expected id. If the two copies drift, one of the two suites goes red.
- */
-
-/** The 25 single-letter suffixes the scheme uses (n=1..25): b, c, ..., z. */
-function singleLetterSuffixes() {
-  return Array.from({ length: 25 }, (_, i) => String.fromCharCode(98 + i));
-}
-
-// Identical matrix + expected values to the editor-ext golden table.
-const GOLDEN = [
-  { originalId: "d", occurrence: 2, taken: [], expected: "d__2" },
-  { originalId: "d", occurrence: 3, taken: [], expected: "d__3" },
-  { originalId: "d", occurrence: 2, taken: ["d__2"], expected: "d__2b" },
-  { originalId: "d", occurrence: 2, taken: ["d__2", "d__2b"], expected: "d__2c" },
-  {
-    originalId: "d",
-    occurrence: 2,
-    taken: ["d__2", "d__2b", "d__2c", "d__2d"],
-    expected: "d__2e",
-  },
-  {
-    originalId: "d",
-    occurrence: 2,
-    taken: ["d__2", ...singleLetterSuffixes().map((s) => `d__2${s}`)],
-    expected: "d__2bb",
-  },
-];
-
-/** Recursively collect every node of `type`. */
-function findAll(node, type, acc = []) {
-  if (!node || typeof node !== "object") return acc;
-  if (node.type === type) acc.push(node);
-  if (Array.isArray(node.content)) for (const c of node.content) findAll(c, type, acc);
-  return acc;
-}
-
-/**
- * Build markdown that drives the real `deriveFootnoteId(originalId, occurrence,
- * taken)`:
- *  - `occurrence` duplicate definitions of `[^originalId]` so the dedup walk
- *    reaches the requested occurrence (occurrence=2 -> 1 keeper + 1 duplicate;
- *    occurrence=3 -> keeper + 2 duplicates, of which the LAST is the one whose
- *    id we read);
- *  - one literal pre-existing definition for every id in `taken`, each with its
- *    own reference marker so it is a real (non-orphan) definition. Those ids are
- *    reserved up-front in the dedup `taken` set, exactly forcing the bump.
- *
- * Returns the derived id of the FINAL duplicate of `originalId`.
- */
-async function deriveViaMarkdown(originalId, occurrence, takenIds) {
-  // References: one [^originalId] per definition (keeper + duplicates) so each
-  // duplicate has a marker to pair with, plus one marker per taken id.
-  const dupCount = occurrence; // keeper + (occurrence-1) duplicates = `occurrence` defs
-  const refMarkers = [];
-  for (let i = 0; i < dupCount; i++) refMarkers.push(`[^${originalId}]`);
-  for (const id of takenIds) refMarkers.push(`[^${id}]`);
-  const refLine = `Body ${refMarkers.join(" ")}.`;
-
-  // Definitions: `occurrence` copies of [^originalId]: ... then the taken ids.
-  const defLines = [];
-  for (let i = 0; i < dupCount; i++) {
-    defLines.push(`[^${originalId}]: copy ${i}`);
-  }
-  for (const id of takenIds) {
-    defLines.push(`[^${id}]: reserved ${id}`);
-  }
-
-  const md = [refLine, "", ...defLines].join("\n");
-  const json = await markdownToProseMirror(md);
-  const defIds = findAll(json, "footnoteDefinition").map((d) => d.attrs.id);
-
-  // The derived id we want is the one that is neither the keeper (originalId),
-  // nor any reserved taken id, nor a lower-occurrence derived id. For
-  // occurrence=2 that is the single bumped id; for occurrence=3 it is the
-  // highest `${originalId}__3...` id. Compute it generically: among the def ids
-  // that start with `${originalId}__${occurrence}`, the expected one is present.
-  return { defIds, json };
-}
-
-for (const row of GOLDEN) {
-  test(`parity: derive("${row.originalId}", ${row.occurrence}, {${row.taken.join(",")}}) -> "${row.expected}"`, async () => {
-    const { defIds } = await deriveViaMarkdown(
-      row.originalId,
-      row.occurrence,
-      row.taken,
-    );
-    // The real compiled deriveFootnoteId must have minted exactly the golden id.
-    assert.ok(
-      defIds.includes(row.expected),
-      `expected derived id "${row.expected}" among def ids ${JSON.stringify(defIds)}`,
-    );
-    // And every id is distinct: nothing collapsed.
-    assert.equal(new Set(defIds).size, defIds.length, "all def ids distinct");
-  });
-}
-
-test("parity: the simple keeper+two-duplicate case mints d, d__2, d__3", async () => {
-  // The canonical no-collision path, asserted as a whole set for clarity.
-  const md = [
-    "See[^d] one[^d] two[^d].",
-    "",
-    "[^d]: first",
-    "[^d]: second",
-    "[^d]: third",
-  ].join("\n");
-  const json = await markdownToProseMirror(md);
-  const defIds = findAll(json, "footnoteDefinition").map((d) => d.attrs.id);
-  assert.deepEqual([...defIds].sort(), ["d", "d__2", "d__3"]);
-});

packages/mcp/test/unit/footnote-analyze.test.mjs

@@ -0,0 +1,106 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { analyzeFootnotes } from "../../build/lib/footnote-analyze.js";
+
+test("clean footnotes produce no diagnostics", () => {
+  const md = ["A[^a] and B[^b].", "", "[^a]: first", "[^b]: second"].join("\n");
+  const d = analyzeFootnotes(md);
+  assert.deepEqual(d.danglingReferences, []);
+  assert.deepEqual(d.emptyDefinitions, []);
+  assert.deepEqual(d.duplicateDefinitions, []);
+  assert.deepEqual(d.referencesInTables, []);
+  assert.deepEqual(d.warnings, []);
+});
+
+test("reuse (repeated references to one definition) is NOT a warning", () => {
+  const md = ["A[^a] B[^a] C[^a].", "", "[^a]: shared"].join("\n");
+  const d = analyzeFootnotes(md);
+  assert.deepEqual(d.danglingReferences, []);
+  assert.deepEqual(d.warnings, []);
+});
+
+test("dangling reference (no definition) is reported", () => {
+  const md = ["See[^missing] and[^a].", "", "[^a]: defined"].join("\n");
+  const d = analyzeFootnotes(md);
+  assert.deepEqual(d.danglingReferences, ["missing"]);
+  assert.equal(d.warnings.length, 1);
+  assert.match(d.warnings[0], /no matching definition/);
+  assert.match(d.warnings[0], /\[\^missing\]/);
+});
+
+test("empty definition text is reported", () => {
+  const md = ["See[^a].", "", "[^a]:   "].join("\n");
+  const d = analyzeFootnotes(md);
+  assert.deepEqual(d.emptyDefinitions, ["a"]);
+  assert.match(d.warnings.join("\n"), /empty text/);
+});
+
+test("duplicate definition id is reported (first-wins)", () => {
+  const md = ["See[^d].", "", "[^d]: first", "[^d]: second"].join("\n");
+  const d = analyzeFootnotes(md);
+  assert.deepEqual(d.duplicateDefinitions, ["d"]);
+  assert.match(d.warnings.join("\n"), /defined more than once/);
+});
+
+test("reference inside a GFM table row is reported (heuristic)", () => {
+  const md = [
+    "| Col |",
+    "| --- |",
+    "| cell[^t] |",
+    "",
+    "[^t]: table note",
+  ].join("\n");
+  const d = analyzeFootnotes(md);
+  assert.deepEqual(d.referencesInTables, ["t"]);
+  assert.match(d.warnings.join("\n"), /table/);
+  // It is defined, so it is NOT also dangling.
+  assert.deepEqual(d.danglingReferences, []);
+});
+
+test("footnote syntax inside a code fence is ignored", () => {
+  const md = [
+    "Intro.",
+    "",
+    "```",
+    "Example[^demo]",
+    "[^demo]: not a real definition",
+    "```",
+    "",
+    "Outro[^a].",
+    "",
+    "[^a]: real",
+  ].join("\n");
+  const d = analyzeFootnotes(md);
+  // `[^demo]` lives only in the fenced block, so it is neither a reference nor a
+  // dangling one, and `[^demo]:` is not counted as a definition.
+  assert.deepEqual(d.danglingReferences, []);
+  assert.deepEqual(d.duplicateDefinitions, []);
+  assert.deepEqual(d.warnings, []);
+});
+
+test("a reference that only appears inside a definition's text is not dangling", () => {
+  // `[^b]` is referenced from within [^a]'s text and has its own definition.
+  const md = ["See[^a].", "", "[^a]: see also [^b]", "[^b]: the other"].join(
+    "\n",
+  );
+  const d = analyzeFootnotes(md);
+  assert.deepEqual(d.danglingReferences, []);
+});
+
+test("multiple problem classes accumulate distinct warnings", () => {
+  const md = [
+    "Ref[^x] and[^dup].",
+    "",
+    "[^dup]: one",
+    "[^dup]: two",
+    "[^empty]:",
+  ].join("\n");
+  const d = analyzeFootnotes(md);
+  // x has no definition; dup is defined twice; empty is empty AND has no ref.
+  assert.ok(d.danglingReferences.includes("x"));
+  assert.deepEqual(d.duplicateDefinitions, ["dup"]);
+  assert.deepEqual(d.emptyDefinitions, ["empty"]);
+  // One warning line per problem class present.
+  assert.ok(d.warnings.length >= 3);
+});

packages/mcp/test/unit/footnote-warnings-import.test.mjs

@@ -0,0 +1,63 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  analyzeFootnotes,
+  footnoteWarningsField,
+} from "../../build/lib/footnote-analyze.js";
+import {
+  serializeDocmostMarkdown,
+  parseDocmostMarkdown,
+} from "../../build/lib/markdown-document.js";
+
+// Pins the footnoteWarnings PLUMBING contract (#169 review): the field is
+// present only on problems and omitted on clean input, AND `import_page_markdown`
+// analyzes the BODY (after the docmost:meta / docmost:comments blocks) — so a
+// footnote-like token inside those JSON blocks never warns, while a real marker
+// in the body does. importPageMarkdown does exactly
+// `footnoteWarningsField(parseDocmostMarkdown(full).body)` over a collab socket
+// this harness does not stand up, so we test the same pure composition directly.
+
+test("footnoteWarningsField is present on problems and omitted on clean input", () => {
+  const problem = footnoteWarningsField("See[^missing].\n\n[^a]: defined");
+  assert.ok(Array.isArray(problem.footnoteWarnings));
+  assert.match(problem.footnoteWarnings.join("\n"), /no matching definition/);
+
+  const clean = footnoteWarningsField("A[^a] and reuse[^a].\n\n[^a]: fine");
+  assert.deepEqual(clean, {}); // no key at all on clean input
+});
+
+test("import analyzes the BODY only — tokens inside meta/comments never warn", () => {
+  // meta + comments JSON carry `[^metaonly]` / `[^commentonly]`-looking text; the
+  // BODY has a genuinely dangling `[^bodyref]`.
+  const full = serializeDocmostMarkdown(
+    { pageId: "p1", note: "front-matter mentions [^metaonly] in text" },
+    "Body with a dangling[^bodyref] marker.",
+    [{ id: "c1", content: "a comment that says [^commentonly]" }],
+  );
+
+  const { body } = parseDocmostMarkdown(full);
+  // Sanity: the meta/comments markers are NOT in the parsed body.
+  assert.ok(!body.includes("[^metaonly]"));
+  assert.ok(!body.includes("[^commentonly]"));
+
+  const field = footnoteWarningsField(body);
+  const joined = (field.footnoteWarnings ?? []).join("\n");
+  // ONLY the body's dangling reference is flagged.
+  assert.match(joined, /\[\^bodyref\]/);
+  assert.ok(!joined.includes("metaonly"));
+  assert.ok(!joined.includes("commentonly"));
+
+  // Cross-check against analyzeFootnotes directly (same composition the importer uses).
+  assert.deepEqual(analyzeFootnotes(body).danglingReferences, ["bodyref"]);
+});
+
+test("import on a clean body yields no footnoteWarnings field", () => {
+  const full = serializeDocmostMarkdown(
+    { pageId: "p1" },
+    "Clean body[^a] reusing[^a].\n\n[^a]: ok",
+    [],
+  );
+  const { body } = parseDocmostMarkdown(full);
+  assert.deepEqual(footnoteWarningsField(body), {});
+});

packages/mcp/test/unit/footnotes.test.mjs

@@ -90,11 +90,10 @@ test("JSON -> MD -> JSON preserves footnote ids and text", async () => {
   assert.match(md2, /\[\^fn2\]: Second note\./);
 });
 
-test("duplicate-id markdown dedups DETERMINISTICALLY (same input -> same ids)", async () => {
-  // The MCP import must derive duplicate ids deterministically (NOT random) so
-  // the same markdown imported here and via the editor produces identical ids,
-  // and re-importing is stable. This is the test that would FAIL on the old
-  // Math.random()/Date.now() implementation.
+test("repeated references REUSE one footnote; duplicate definitions are first-wins (#166)", async () => {
+  // Reuse semantics: many `[^d]` references + several `[^d]:` definitions import
+  // as ONE footnote — the references all keep id "d" (reuse), and only the FIRST
+  // definition is kept (first-wins). Deterministic and stable across re-imports.
   const md = [
     "See[^d] one[^d] two[^d].",
     "",
@@ -106,21 +105,26 @@ test("duplicate-id markdown dedups DETERMINISTICALLY (same input -> same ids)",
   const idsOf = async () => {
     const json = await markdownToProseMirror(md);
     const refs = findAll(json, "footnoteReference").map((r) => r.attrs.id);
-    const defs = findAll(json, "footnoteDefinition").map((d) => d.attrs.id);
-    return { refs, defs };
+    const defs = findAll(json, "footnoteDefinition");
+    return {
+      refs,
+      defIds: defs.map((d) => d.attrs.id),
+      defText: defs
+        .map((d) => JSON.stringify(d).match(/"text":"([^"]*)"/)?.[1])
+        .join("|"),
+    };
   };
 
   const a = await idsOf();
   const b = await idsOf();
 
-  // Identical across runs.
-  assert.deepEqual(a.refs, b.refs);
-  assert.deepEqual(a.defs, b.defs);
-  // Deterministic derived scheme: keeper "d", duplicates "d__2", "d__3".
-  assert.deepEqual([...a.defs].sort(), ["d", "d__2", "d__3"]);
-  // 1:1 reference <-> definition pairing, all distinct.
-  assert.equal(new Set(a.defs).size, 3);
-  assert.deepEqual([...a.refs].sort(), [...a.defs].sort());
+  // Stable across runs.
+  assert.deepEqual(a, b);
+  // Reuse: all three reference markers stay "d".
+  assert.deepEqual(a.refs, ["d", "d", "d"]);
+  // First-wins: a single definition "d" with the FIRST text.
+  assert.deepEqual(a.defIds, ["d"]);
+  assert.equal(a.defText, "first");
 });
 
 test("a [^id]: line inside a fenced code block is NOT treated as a definition", async () => {