docs(page-tree): correct isUnloadedBranch comment — no DnD-guard consumer (#525 review)

The comment falsely listed a 'DnD move guard' consumer; no DnD path routes
through the predicate (local DnD/create-page use the raw index-based insert).
List the real consumers (handleToggle + realtime insertByPosition/placeByPosition)
and note the local raw-insert path as a #525 follow-up. Comment-only.

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

apps/client/package.json

@@ -22,6 +22,7 @@
     "@casl/react": "5.0.1",
     "@docmost/editor-ext": "workspace:*",
     "@docmost/prosemirror-markdown": "workspace:*",
+    "@docmost/token-estimate": "workspace:*",
     "@excalidraw/excalidraw": "0.18.0-3a5ef40",
     "@mantine/core": "8.3.18",
     "@mantine/dates": "8.3.18",

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

@@ -256,6 +256,9 @@
   "Invite link": "Ссылка для приглашения",
   "Copy": "Копировать",
   "Copy to space": "Копировать в пространство",
+  "Copy chat": "Копировать чат",
+  "Dock to sidebar": "Закрепить в боковой панели",
+  "Undock": "Открепить",
   "Copied": "Скопировано",
   "Failed to export chat": "Не удалось экспортировать чат",
   "Duplicate": "Дублировать",
@@ -285,6 +288,9 @@
   "Alt text": "Альтернативный текст",
   "Describe this for accessibility.": "Опишите это для специальных возможностей.",
   "Add a description": "Добавить описание",
+  "Caption": "Подпись",
+  "Add a caption": "Добавить подпись",
+  "Shown below the image.": "Отображается под изображением.",
   "Justify": "По ширине",
   "Merge cells": "Объединить ячейки",
   "Split cell": "Разделить ячейку",
@@ -388,22 +394,6 @@
   "Quote": "Цитата",
   "Image": "Изображение",
   "Audio": "Аудио",
-  "Transcribe": "Транскрибировать",
-  "Transcribing…": "Транскрибация…",
-  "No speech detected": "Речь не распознана",
-  "Transcription failed": "Не удалось распознать речь",
-  "Voice dictation is not configured": "Голосовой ввод не настроен",
-  "Start dictation": "Начать диктовку",
-  "Stop recording": "Остановить запись",
-  "Microphone access denied": "Доступ к микрофону запрещён",
-  "No microphone found": "Микрофон не найден",
-  "Microphone is unavailable or already in use": "Микрофон недоступен или уже используется",
-  "Could not start recording": "Не удалось начать запись",
-  "Audio recording is not available in this browser/context": "Запись аудио недоступна в этом браузере/контексте",
-  "Dictation": "Диктовка",
-  "Dictation becomes available once the page finishes connecting": "Диктовка станет доступна после подключения к документу",
-  "No connection to the collaboration server — dictation unavailable": "Нет связи с сервером совместного редактирования — диктовка недоступна",
-  "This page is read-only": "Страница открыта только для чтения",
   "Embed PDF": "Встроить PDF",
   "Upload and embed a PDF file.": "Загрузите и встроите PDF-файл.",
   "Embed as PDF": "Встроить как PDF",
@@ -419,9 +409,6 @@
   "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.": "Вставить математическое выражение в строку.",
   "Math block": "Блок формулы",
@@ -447,6 +434,9 @@
   "{{count}} command available_other": "Доступно {{count}} команд",
   "{{count}} result available_one": "Доступен 1 результат",
   "{{count}} result available_other": "Доступно {{count}} результатов",
+  "{{count}} result found_one": "Найден {{count}} результат",
+  "{{count}} result found_few": "Найдено {{count}} результата",
+  "{{count}} result found_other": "Найдено {{count}} результатов",
   "Equal columns": "Равные столбцы",
   "Left sidebar": "Левая боковая панель",
   "Right sidebar": "Правая боковая панель",
@@ -456,6 +446,7 @@
   "Names do not match": "Названия не совпадают",
   "Today, {{time}}": "Сегодня, {{time}}",
   "Yesterday, {{time}}": "Вчера, {{time}}",
+  "now": "сейчас",
   "Space created successfully": "Пространство успешно создано",
   "Space updated successfully": "Пространство успешно обновлено",
   "Space deleted successfully": "Пространство успешно удалено",
@@ -559,6 +550,7 @@
   "Add 2FA method": "Добавить метод 2FA",
   "Backup codes": "Резервные коды",
   "Disable": "Отключить",
+  "disabled": "отключено",
   "Invalid verification code": "Недействительный код подтверждения",
   "New backup codes have been generated": "Новые резервные коды сгенерированы",
   "Failed to regenerate backup codes": "Не удалось заново сгенерировать резервные коды",
@@ -702,62 +694,6 @@
   "AI search": "Поиск ИИ",
   "AI Answer": "Ответ ИИ",
   "Ask AI": "Спросить ИИ",
-  "AI agent": "AI-агент",
-  "Take a look at the current document": "Посмотри текущий документ",
-  "Start automatically": "Запускать автоматически",
-  "When on, picking this role sends a launch message and starts the chat. When off, the role is selected and you type the first message yourself.": "Когда включено, выбор этой роли отправляет стартовое сообщение и начинает чат. Когда выключено, роль выбирается, а первое сообщение вы вводите сами.",
-  "Launch message": "Стартовое сообщение",
-  "Sent automatically when this role is picked. Leave empty to use the default text. Ignored when “Start automatically” is off.": "Отправляется автоматически при выборе этой роли. Оставьте пустым, чтобы использовать текст по умолчанию. Игнорируется, когда «Запускать автоматически» выключено.",
-  "AI agent is typing…": "AI-агент печатает…",
-  "{{name}} is typing…": "{{name}} печатает…",
-  "Thinking…": "Думаю…",
-  "Thinking… · {{count}} tokens": "Думаю… · {{count}} токенов",
-  "Thinking… · {{count}} tokens_one": "Думаю… · {{count}} токен",
-  "Thinking… · {{count}} tokens_few": "Думаю… · {{count}} токена",
-  "Thinking… · {{count}} tokens_many": "Думаю… · {{count}} токенов",
-  "Thinking · {{count}} tokens": "Размышления · {{count}} токенов",
-  "Thinking · {{count}} tokens_one": "Размышления · {{count}} токен",
-  "Thinking · {{count}} tokens_few": "Размышления · {{count}} токена",
-  "Thinking · {{count}} tokens_many": "Размышления · {{count}} токенов",
-  "Agent role": "Роль агента",
-  "AI chat": "AI-чат",
-  "AI chat is disabled for this workspace.": "AI-чат отключён для этого рабочего пространства.",
-  "Ask a question about this documentation.": "Задайте вопрос об этой документации.",
-  "Ask a question…": "Задайте вопрос…",
-  "Ask the AI agent anything about your workspace.": "Спросите AI-агента о чём угодно по вашему рабочему пространству.",
-  "Ask the AI agent…": "Спросите AI-агента…",
-  "Copy chat": "Копировать чат",
-  "Dock to sidebar": "Закрепить в боковой панели",
-  "Undock": "Открепить",
-  "Created successfully": "Успешно создано",
-  "Context size / model limit": "Размер контекста / лимит модели",
-  "Context window (tokens)": "Окно контекста (токены)",
-  "Shown as used / total in the chat header. Leave empty to hide the limit.": "Показывается в шапке чата как использовано / всего. Пусто — лимит скрыт.",
-  "Delete this chat?": "Удалить этот чат?",
-  "Deleted successfully": "Успешно удалено",
-  "AI agent «{{role}}» on behalf of {{person}}": "AI-агент «{{role}}» от имени {{person}}",
-  "AI agent {{name}}": "AI-агент {{name}}",
-  "Failed to delete chat": "Не удалось удалить чат",
-  "Failed to rename chat": "Не удалось переименовать чат",
-  "Failed": "Ошибка",
-  "OK · {{n}}": "OK · {{n}}",
-  "Test": "Тест",
-  "No tools available": "Инструменты недоступны",
-  "Available tools": "Доступные инструменты",
-  "Minimize": "Свернуть",
-  "No chats yet.": "Чатов пока нет.",
-  "Send": "Отправить",
-  "Send when the agent finishes": "Отправить, когда агент закончит",
-  "Queue message": "Поставить в очередь",
-  "Remove queued message": "Убрать из очереди",
-  "Send now": "Отправить сейчас",
-  "Interrupt and send now": "Прервать и отправить сейчас",
-  "Something went wrong": "Что-то пошло не так",
-  "Stop": "Стоп",
-  "The AI agent could not respond. Please try again.": "AI-агент не смог ответить. Попробуйте ещё раз.",
-  "The AI provider is not configured. Ask an administrator to set it up.": "AI-провайдер не настроен. Попросите администратора настроить его.",
-  "Universal assistant": "Универсальный ассистент",
-  "You": "Вы",
   "AI is thinking...": "ИИ обрабатывает запрос...",
   "Thinking": "Думаю",
   "Ask a question...": "Задайте вопрос...",
@@ -784,8 +720,40 @@
   "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": "Инструкции",
+  "AI / Models": "ИИ / Модели",
+  "AI / External tools (MCP)": "ИИ / Внешние инструменты (MCP)",
+  "Add server": "Добавить сервер",
+  "Edit server": "Изменить сервер",
+  "Delete server": "Удалить сервер",
+  "Are you sure you want to delete this MCP server?": "Вы уверены, что хотите удалить этот MCP-сервер?",
+  "No external servers configured": "Внешние серверы не настроены",
+  "Server name": "Имя сервера",
+  "Transport": "Транспорт",
+  "URL": "URL",
+  "Authorization header": "Заголовок авторизации",
+  "Tool allowlist": "Список разрешённых инструментов",
+  "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>_*\".": "Необязательное указание агенту, как и когда использовать инструменты этого сервера. Добавляется в системный промпт. Инструменты сервера именуются с префиксом «<имя сервера>_*».",
+  "Test": "Тест",
+  "Available tools": "Доступные инструменты",
+  "No tools available": "Инструменты недоступны",
+  "Failed": "Ошибка",
+  "OK · {{n}}": "OK · {{n}}",
+  "Created successfully": "Успешно создано",
+  "Deleted successfully": "Успешно удалено",
+  "Clear": "Очистить",
+  "Provider": "Провайдер",
+  "•••• set": "•••• задан",
+  "Clear key": "Очистить ключ",
+  "Base URL": "Базовый URL",
+  "Chat model": "Модель чата",
+  "Embedding model": "Модель эмбеддингов",
+  "System message": "Системное сообщение",
+  "A built-in safety framework is always appended.": "Встроенный набор правил безопасности всегда добавляется автоматически.",
+  "Test connection": "Проверить соединение",
+  "Connection successful": "Соединение установлено",
+  "Connection failed": "Не удалось установить соединение",
+  "Only workspace admins can manage AI provider settings.": "Управлять настройками провайдера ИИ могут только администраторы рабочего пространства.",
   "Sources": "Источники",
   "AI Answers not available for attachments": "Ответы ИИ недоступны для вложений",
   "No answer available": "Ответ недоступен",
@@ -1013,6 +981,7 @@
   "Try again": "Попробовать снова",
   "Untitled chat": "Чат без названия",
   "No document": "Без документа",
+  "You": "Вы",
   "What can I help you with?": "Чем я могу вам помочь?",
   "Are you sure you want to revoke this {{credential}}": "Вы уверены, что хотите отозвать этот {{credential}}",
   "Automatically provision users and groups from your identity provider via SCIM.": "Автоматически предоставляйте доступ пользователям и группам из вашего провайдера удостоверений через SCIM.",
@@ -1041,6 +1010,9 @@
   "Page menu": "Меню страницы",
   "Expand": "Развернуть",
   "Collapse": "Свернуть",
+  "Expand all": "Развернуть все",
+  "Collapse all": "Свернуть все",
+  "Couldn't expand the tree: {{reason}}": "Не удалось развернуть дерево: {{reason}}",
   "Comment menu": "Меню комментария",
   "Group menu": "Меню группы",
   "Show hidden breadcrumbs": "Показать скрытые хлебные крошки",
@@ -1077,7 +1049,7 @@
   "Search pages and spaces...": "Поиск страниц и пространств...",
   "No results found": "Результаты не найдены",
   "You don't have permission to create pages here": "У вас нет прав на создание страниц здесь",
-  "Chat menu": "Меню чата",
+  "Chat menu for {{title}}": "Меню чата для {{title}}",
   "API key menu": "Меню API-ключа",
   "Jump to comment selection": "Перейти к выбору комментария",
   "Slash commands": "Команды со слешем",
@@ -1131,6 +1103,9 @@
   "Undo": "Отменить",
   "Redo": "Повторить",
   "Backlinks": "Обратные ссылки",
+  "Back to references": "Вернуться к ссылкам",
+  "Back to reference {{label}}": "Вернуться к ссылке {{label}}",
+  "Empty footnote": "Пустая сноска",
   "Last updated by": "Последний изменивший",
   "Last updated": "Последнее обновление",
   "Stats": "Статистика",
@@ -1164,6 +1139,7 @@
   "Page title": "Заголовок страницы",
   "Page content": "Содержимое страницы",
   "Member actions": "Действия с участником",
+  "Member actions for {{name}}": "Действия с участником {{name}}",
   "Toggle password visibility": "Переключить видимость пароля",
   "Send comment": "Отправить комментарий",
   "Token actions": "Действия с токеном",
@@ -1183,11 +1159,187 @@
   "Removed from favorites": "Удалено из избранного",
   "Added {{name}} to favorites": "{{name}} добавлено в избранное",
   "Removed {{name}} from favorites": "{{name}} удалено из избранного",
+  "Label added": "Метка добавлена",
+  "Label removed": "Метка удалена",
+  "Image updated": "Изображение обновлено",
+  "Unsupported image type": "Неподдерживаемый тип изображения",
+  "Member deactivated": "Участник деактивирован",
+  "Member activated": "Участник активирован",
+  "Name is required": "Укажите имя",
+  "Name must be 40 characters or fewer": "Имя должно содержать не более 40 символов",
+  "Group name must be at least 2 characters": "Название группы должно содержать не менее 2 символов",
+  "Group name must be 100 characters or fewer": "Название группы должно содержать не более 100 символов",
+  "Description must be 500 characters or fewer": "Описание должно содержать не более 500 символов",
+  "Invalid invitation link": "Недействительная ссылка-приглашение",
   "Page menu for {{name}}": "Меню страницы для {{name}}",
   "Create subpage of {{name}}": "Создать подстраницу для {{name}}",
+  "AI chat": "AI-чат",
+  "Ask a question about this documentation.": "Задайте вопрос об этой документации.",
+  "Ask a question…": "Задайте вопрос…",
+  "Thinking…": "Думаю…",
+  "Thinking… · {{count}} tokens": "Думаю… · {{count}} токенов",
+  "Thinking… · {{count}} tokens_one": "Думаю… · {{count}} токен",
+  "Thinking… · {{count}} tokens_few": "Думаю… · {{count}} токена",
+  "Thinking… · {{count}} tokens_many": "Думаю… · {{count}} токенов",
+  "Thinking… · {{count}} tokens_other": "Думаю… · {{count}} токенов",
+  "Thinking · {{count}} tokens": "Размышления · {{count}} токенов",
+  "Thinking · {{count}} tokens_one": "Размышления · {{count}} токен",
+  "Thinking · {{count}} tokens_few": "Размышления · {{count}} токена",
+  "Thinking · {{count}} tokens_many": "Размышления · {{count}} токенов",
+  "Thinking · {{count}} tokens_other": "Размышления · {{count}} токенов",
+  "The assistant is unavailable right now. Please try again.": "Ассистент сейчас недоступен. Попробуйте ещё раз.",
+  "Public share assistant": "Ассистент публичного доступа",
+  "Let anonymous visitors of public shares ask an AI assistant scoped to that share's pages. You pay for the tokens.": "Позвольте анонимным посетителям публичных ссылок обращаться к ИИ-ассистенту в рамках страниц этой публикации. Токены оплачиваете вы.",
+  "Public assistant model": "Модель публичного ассистента",
+  "Defaults to the chat model": "По умолчанию используется модель чата",
+  "Optional cheaper model id for the public assistant. Empty uses the chat model above.": "Необязательный более дешёвый идентификатор модели для публичного ассистента. Если пусто, используется модель чата выше.",
+  "Assistant identity": "Личность ассистента",
+  "Pick an agent role whose persona the public assistant adopts. The safety rules always still apply.": "Выберите роль агента, чью личность примет публичный ассистент. Правила безопасности всегда остаются в силе.",
+  "Built-in assistant persona": "Встроенная личность ассистента",
+  "Minimize": "Свернуть",
+  "Context size / model limit": "Размер контекста / лимит модели",
+  "Context window (tokens)": "Окно контекста (токены)",
+  "Shown as used / total in the chat header. Leave empty to hide the limit.": "Показывается в шапке чата как использовано / всего. Пусто — лимит скрыт.",
+  "AI agent": "AI-агент",
+  "Take a look at the current document": "Посмотри текущий документ",
+  "AI agent is typing…": "AI-агент печатает…",
+  "{{name}} is typing…": "{{name}} печатает…",
+  "Send": "Отправить",
+  "Send when the agent finishes": "Отправить, когда агент закончит",
+  "Queue message": "Поставить в очередь",
+  "Remove queued message": "Убрать из очереди",
+  "Send now": "Отправить сейчас",
+  "Interrupt and send now": "Прервать и отправить сейчас",
+  "Stop": "Стоп",
+  "Response stopped.": "Ответ остановлен.",
+  "Connection lost — the answer was interrupted.": "Соединение потеряно — ответ был прерван.",
+  "Response stopped (manually or the connection dropped).": "Ответ остановлен (вручную или из-за разрыва соединения).",
+  "Chat menu": "Меню чата",
+  "No chats yet.": "Чатов пока нет.",
+  "Delete this chat?": "Удалить этот чат?",
+  "Ask the AI agent…": "Спросите AI-агента…",
+  "Ask the AI agent anything about your workspace.": "Спросите AI-агента о чём угодно по вашему рабочему пространству.",
+  "Failed to rename chat": "Не удалось переименовать чат",
+  "Failed to delete chat": "Не удалось удалить чат",
+  "Something went wrong": "Что-то пошло не так",
+  "AI chat is disabled for this workspace.": "AI-чат отключён для этого рабочего пространства.",
+  "The AI provider is not configured. Ask an administrator to set it up.": "AI-провайдер не настроен. Попросите администратора настроить его.",
+  "The AI agent could not respond. Please try again.": "AI-агент не смог ответить. Попробуйте ещё раз.",
+  "Searched pages": "Поиск по страницам",
+  "Read page": "Прочитана страница",
+  "Created page": "Создана страница",
+  "Updated page": "Обновлена страница",
+  "Renamed page": "Переименована страница",
+  "Moved page": "Перемещена страница",
+  "Deleted page (to trash)": "Удалена страница (в корзину)",
+  "Commented": "Добавлен комментарий",
+  "Resolved comment": "Комментарий решён",
+  "Ran tool {{name}}": "Выполнен инструмент {{name}}",
+  "AI agent «{{role}}» on behalf of {{person}}": "AI-агент «{{role}}» от имени {{person}}",
+  "AI agent {{name}}": "AI-агент {{name}}",
+  "Endpoints": "Эндпоинты",
+  "where we fetch models": "откуда мы получаем модели",
+  "All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.": "Все эндпоинты совместимы с OpenAI. Укажите в базовом URL адрес OpenAI, OpenRouter, локального Ollama или любого self-hosted сервера.",
+  "Chat / LLM": "Чат / LLM",
+  "root": "корневой",
+  "Semantic search": "Семантический поиск",
+  "Voice / STT": "Голос / STT",
+  "Voice dictation": "Голосовой ввод",
+  "Streaming dictation": "Потоковый голосовой ввод",
+  "Transcribe as you speak, cutting on pauses": "Транскрибирование по мере речи, с разбивкой на паузах",
+  "Voice dictation is not available yet.": "Голосовой ввод пока недоступен.",
+  "Test endpoint": "Проверить эндпоинт",
+  "Save and test": "Сохранить и проверить",
+  "Save endpoints": "Сохранить эндпоинты",
+  "Configured and enabled": "Настроено и включено",
+  "Configured but disabled": "Настроено, но отключено",
+  "Enabled but not configured": "Включено, но не настроено",
+  "Not configured": "Не настроено",
+  "External tools": "Внешние инструменты",
+  "Gitmost as MCP client": "Gitmost как MCP-клиент",
+  "Servers the agent calls out to.": "Серверы, к которым обращается агент.",
+  "MCP server": "MCP-сервер",
+  "expose the workspace": "открыть доступ к рабочему пространству",
+  "Enable MCP server": "Включить MCP-сервер",
+  "Exposes the workspace as an MCP server at /mcp — this provides a capability, it doesn't consume a model.": "Открывает рабочее пространство как MCP-сервер по адресу /mcp — это предоставляет возможность, а не потребляет модель.",
+  "Resolves to {{url}}": "Разрешается в {{url}}",
+  "Model": "Модель",
+  "Done": "Готово",
+  "shared prompt · safety framework appended automatically": "общий промпт · правила безопасности добавляются автоматически",
+  "/v1/chat/completions · root endpoint — Embeddings and Voice inherit its URL and key": "/v1/chat/completions · корневой эндпоинт — Эмбеддинги и Голос наследуют его URL и ключ",
+  "/v1/embeddings · embeds pages so semantic search can find them": "/v1/embeddings · создаёт эмбеддинги страниц, чтобы их находил семантический поиск",
+  "/v1/audio/transcriptions · works with local whisper (speaches / faster-whisper-server)": "/v1/audio/transcriptions · работает с локальным whisper (speaches / faster-whisper-server)",
+  "Vector search · requires pgvector": "Векторный поиск · требуется pgvector",
+  "Embedding API key": "API-ключ для эмбеддингов",
+  "Embeddings": "Эмбеддинги",
+  "Leave empty to use the chat API key": "Оставьте пустым, чтобы использовать API-ключ чата",
+  "Leave empty to use the chat base URL": "Оставьте пустым, чтобы использовать базовый URL чата",
+  "Reindex now": "Переиндексировать сейчас",
+  "Start dictation": "Начать диктовку",
+  "Stop recording": "Остановить запись",
+  "Transcribing…": "Транскрибация…",
+  "Microphone access denied": "Доступ к микрофону запрещён",
+  "No microphone found": "Микрофон не найден",
+  "Could not start recording": "Не удалось начать запись",
+  "Transcription failed": "Не удалось распознать речь",
+  "Transcribe": "Транскрибировать",
+  "No speech detected": "Речь не распознана",
+  "Voice dictation is not configured": "Голосовой ввод не настроен",
+  "Microphone is unavailable or already in use": "Микрофон недоступен или уже используется",
+  "Audio recording is not available in this browser/context": "Запись аудио недоступна в этом браузере/контексте",
+  "Dictation": "Диктовка",
+  "Dictation becomes available once the page finishes connecting": "Диктовка станет доступна после подключения к документу",
+  "No connection to the collaboration server — dictation unavailable": "Нет связи с сервером совместного редактирования — диктовка недоступна",
+  "This page is read-only": "Страница открыта только для чтения",
+  "Request format": "Формат запроса",
+  "How transcription requests are sent to the endpoint": "Как запросы на транскрибирование отправляются на эндпоинт",
+  "OpenAI-compatible (multipart/form-data)": "Совместимо с OpenAI (multipart/form-data)",
+  "OpenRouter (JSON, base64 audio)": "OpenRouter (JSON, аудио в base64)",
   "Dictation language": "Язык диктовки",
   "Auto-detect": "Автоопределение",
   "Spoken language hint sent to the transcription model. Auto-detect lets the model decide.": "Подсказка языка речи для модели транскрипции. «Автоопределение» оставляет выбор за моделью.",
+  "Agent role": "Роль агента",
+  "Universal assistant": "Универсальный ассистент",
+  "Add role": "Добавить роль",
+  "Edit role": "Изменить роль",
+  "Role name": "Название роли",
+  "e.g. Proofreader": "напр. Корректор",
+  "Optional. Shown as the chat badge.": "Необязательно. Отображается как значок чата.",
+  "Optional. A short note about what this role does.": "Необязательно. Краткое описание того, что делает эта роль.",
+  "Instructions": "Инструкции",
+  "The built-in safety framework is always added automatically.": "Встроенный набор правил безопасности всегда добавляется автоматически.",
+  "Model provider override": "Переопределение провайдера модели",
+  "Optional. Defaults to the workspace provider.": "Необязательно. По умолчанию используется провайдер рабочего пространства.",
+  "Model override": "Переопределение модели",
+  "Optional. Defaults to the workspace model.": "Необязательно. По умолчанию используется модель рабочего пространства.",
+  "e.g. gpt-4o-mini": "напр. gpt-4o-mini",
+  "If you choose a different provider, it must already be configured in AI settings.": "Если вы выбираете другого провайдера, он уже должен быть настроен в настройках ИИ.",
+  "Start automatically": "Запускать автоматически",
+  "When on, picking this role sends a launch message and starts the chat. When off, the role is selected and you type the first message yourself.": "Когда включено, выбор этой роли отправляет стартовое сообщение и начинает чат. Когда выключено, роль выбирается, а первое сообщение вы вводите сами.",
+  "Launch message": "Стартовое сообщение",
+  "Sent automatically when this role is picked. Leave empty to use the default text. Ignored when “Start automatically” is off.": "Отправляется автоматически при выборе этой роли. Оставьте пустым, чтобы использовать текст по умолчанию. Игнорируется, когда «Запускать автоматически» выключено.",
+  "Agent roles": "Роли агента",
+  "Reusable presets that shape the agent's behavior (and optionally its model). Picked when starting a new chat.": "Многоразовые пресеты, определяющие поведение агента (и, при желании, его модель). Выбираются при запуске нового чата.",
+  "No roles configured": "Роли не настроены",
+  "Delete role": "Удалить роль",
+  "Are you sure you want to delete this role?": "Вы уверены, что хотите удалить эту роль?",
+  "HTML embed": "HTML-вставка",
+  "Edit HTML embed": "Изменить HTML-вставку",
+  "HTML embed is disabled in this workspace": "HTML-вставки отключены в этом рабочем пространстве",
+  "Click to add HTML / CSS / JS": "Нажмите, чтобы добавить HTML / CSS / JS",
+  "This HTML/CSS/JS runs in a sandboxed frame and cannot access the viewer's session, cookies, or API.": "Этот HTML/CSS/JS выполняется в изолированном фрейме и не имеет доступа к сессии, cookie или API просматривающего.",
+  "<script>...</script>": "<script>...</script>",
+  "Height (px, blank = auto)": "Высота (px, пусто = авто)",
+  "advanced": "дополнительно",
+  "Enable HTML embed": "Включить HTML-вставки",
+  "Allow members to insert raw HTML/CSS/JavaScript blocks. The block renders in a sandboxed frame and cannot access the viewer's session, cookies, or API. Off by default.": "Разрешить участникам вставлять блоки с необработанным HTML/CSS/JavaScript. Блок отображается в изолированном фрейме и не имеет доступа к сессии, cookie или API просматривающего. По умолчанию выключено.",
+  "When enabled, any member can insert an HTML embed block. The toggle just enables or disables the block type workspace-wide.": "Когда включено, любой участник может вставить блок HTML-вставки. Переключатель просто включает или отключает этот тип блока во всём рабочем пространстве.",
+  "Embeds run inside a sandboxed iframe with a separate origin, so they cannot read or modify the page they are embedded in.": "Вставки выполняются в изолированном iframe с отдельным источником, поэтому они не могут читать или изменять страницу, в которую встроены.",
+  "Turning this off hides existing embeds (they render as a disabled placeholder) and stops serving them on public share pages.": "Отключение этой опции скрывает существующие вставки (они отображаются как отключённая заглушка) и прекращает их показ на публичных страницах.",
+  "Analytics / tracker": "Аналитика / трекер",
+  "Injected verbatim into the <head> of PUBLIC SHARE pages only (same-origin). For analytics snippets (Google Analytics, Yandex.Metrika, etc.). Admin only.": "Вставляется дословно в <head> только ПУБЛИЧНЫХ страниц (тот же источник). Для сниппетов аналитики (Google Analytics, Яндекс.Метрика и т. п.). Только для администраторов.",
+  "Go to login page": "Перейти на страницу входа",
+  "Move to space": "Переместить в пространство",
   "Float left (wrap text)": "Обтекание слева",
   "Float right (wrap text)": "Обтекание справа",
   "Inline (side by side)": "В ряд",
@@ -1199,6 +1351,7 @@
   "Showing {{count}} subpages_one": "Показано {{count}} подстраница",
   "Showing {{count}} subpages_few": "Показано {{count}} подстраницы",
   "Showing {{count}} subpages_many": "Показано {{count}} подстраниц",
+  "Showing {{count}} subpages_other": "Показано {{count}} подстраниц",
   "Protocol": "Протокол",
   "How chat requests are sent and how reasoning is surfaced": "Как отправляются запросы чата и как показывается reasoning",
   "OpenAI-compatible (surfaces reasoning)": "OpenAI-совместимый (показывает reasoning)",
@@ -1268,7 +1421,6 @@
   "Retry": "Повторить",
   "The catalog is empty": "Каталог пуст",
   "No role bundles are published for this language yet. Try switching the content language.": "Для этого языка ещё не опубликовано ни одного набора ролей. Попробуйте сменить язык контента.",
-  "No roles configured": "Роли не настроены",
   "Already up to date": "Уже актуальна",
   "Updated to the latest version": "Обновлено до последней версии",
   "This role is no longer in the catalog": "Эта роль больше не представлена в каталоге",

apps/client/src/components/chunk-load-error-boundary.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { isChunkLoadError } from "./chunk-load-error-boundary";
+import { isChunkLoadError, shouldAutoReload } from "./chunk-load-error-boundary";
 
 // The detector decides whether a caught render error is a stale-deploy chunk-404
 // (→ auto-reload to fetch the new manifest) vs a genuine app error (→ generic
@@ -35,3 +35,31 @@ describe("isChunkLoadError", () => {
     expect(isChunkLoadError(err)).toBe(false);
   });
 });
+
+// The window gate replaces the old one-shot flag: it must permit recovery across
+// several deploys in one tab (each > window apart) while still stopping an infinite
+// reload loop when a lazy chunk is permanently broken (a second failure < window).
+describe("shouldAutoReload", () => {
+  const WINDOW = 5 * 60 * 1000;
+  const NOW = 1_000_000_000_000;
+
+  it("allows a reload when we have never auto-reloaded", () => {
+    expect(shouldAutoReload(NOW, null, WINDOW)).toBe(true);
+  });
+
+  it("allows a reload when the last one was 6 minutes ago (outside the window)", () => {
+    expect(shouldAutoReload(NOW, NOW - 6 * 60 * 1000, WINDOW)).toBe(true);
+  });
+
+  it("blocks a reload when the last one was 1 minute ago (inside the window)", () => {
+    expect(shouldAutoReload(NOW, NOW - 1 * 60 * 1000, WINDOW)).toBe(false);
+  });
+
+  it("blocks a reload exactly at the window boundary (not strictly older)", () => {
+    expect(shouldAutoReload(NOW, NOW - WINDOW, WINDOW)).toBe(false);
+  });
+
+  it("allows a reload when the stored timestamp is unparseable (NaN)", () => {
+    expect(shouldAutoReload(NOW, NaN, WINDOW)).toBe(true);
+  });
+});

apps/client/src/components/chunk-load-error-boundary.tsx

@@ -2,7 +2,25 @@ import { ReactNode } from "react";
 import { ErrorBoundary } from "react-error-boundary";
 import { Button, Center, Stack, Text } from "@mantine/core";
 
-const RELOAD_FLAG = "chunk-reload-attempted";
+// sessionStorage key holding the epoch-ms timestamp of the last automatic reload.
+const RELOAD_AT_KEY = "chunk-reload-at";
+// Allow at most one automatic reload per this window. A stale-deploy 404 is cured
+// by a single reload, so anything inside the window is treated as a reload loop
+// (permanently-broken chunk) and falls through to the manual UI. A window (rather
+// than a one-shot flag) lets a SECOND deploy in the same tab's lifetime recover too.
+const RELOAD_WINDOW_MS = 5 * 60 * 1000;
+
+// Pure window decision, unit-tested in isolation: auto-reload only if we have never
+// auto-reloaded (lastReloadAt null/NaN) or the last one was strictly older than the
+// window. Anything inside the window is suppressed to break an infinite reload loop.
+export function shouldAutoReload(
+  now: number,
+  lastReloadAt: number | null,
+  windowMs: number,
+): boolean {
+  if (lastReloadAt === null || Number.isNaN(lastReloadAt)) return true;
+  return now - lastReloadAt > windowMs;
+}
 
 // Heuristic detection of a failed dynamic import. Since the code-splitting work,
 // every route (plus Aside / AiChatWindow) is React.lazy: when a new deploy
@@ -24,12 +42,16 @@ export function isChunkLoadError(error: unknown): boolean {
 function handleError(error: unknown) {
   if (!isChunkLoadError(error)) return;
   // A stale-chunk 404 is cured by a full reload that re-fetches index.html and
-  // the new chunk manifest. Auto-reload once, guarding against a reload loop
-  // (e.g. a genuinely missing chunk) with a one-shot sessionStorage flag. If the
-  // flag is already set we fall through to the manual recovery UI below.
+  // the new chunk manifest. Auto-reload at most once per RELOAD_WINDOW_MS: this
+  // recovers across multiple deploys in a single tab's lifetime, yet a
+  // permanently-broken lazy chunk (which would loop) is stopped after the first
+  // reload and falls through to the manual recovery UI below.
   try {
-    if (sessionStorage.getItem(RELOAD_FLAG)) return;
-    sessionStorage.setItem(RELOAD_FLAG, "1");
+    const raw = sessionStorage.getItem(RELOAD_AT_KEY);
+    const lastReloadAt = raw === null ? null : Number.parseInt(raw, 10);
+    const now = Date.now();
+    if (!shouldAutoReload(now, lastReloadAt, RELOAD_WINDOW_MS)) return;
+    sessionStorage.setItem(RELOAD_AT_KEY, String(now));
   } catch {
     // sessionStorage unavailable (private mode / disabled): skip the automatic
     // reload rather than risk an unguarded loop; the fallback UI still recovers.

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

@@ -6,10 +6,13 @@ describe("estimateTokens", () => {
     expect(estimateTokens("")).toBe(0);
   });
 
-  it("ceils chars/4 so any non-empty text is at least 1 token", () => {
+  // #490: migrated onto the shared @docmost/token-estimate module (chars/2.5, up
+  // from the old client-only chars/4) so the client counter and the server replay
+  // budgeter can never diverge.
+  it("ceils chars/2.5 so any non-empty text is at least 1 token", () => {
     expect(estimateTokens("a")).toBe(1);
-    expect(estimateTokens("abcd")).toBe(1);
-    expect(estimateTokens("abcde")).toBe(2);
-    expect(estimateTokens("12345678")).toBe(2);
+    expect(estimateTokens("ab")).toBe(1);
+    expect(estimateTokens("abcde")).toBe(2); // 5 / 2.5 = 2
+    expect(estimateTokens("x".repeat(10))).toBe(4); // 10 / 2.5 = 4
   });
 });

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

@@ -2,18 +2,10 @@
  * Rough client-side token estimation for AI-chat UI affordances.
  *
  * No provider streams exact per-token usage mid-stream, so any in-flight figure
- * is a CLIENT ESTIMATE (chars/≈4 heuristic). Pure + unit-testable: it never runs
- * a real BPE tokenizer (that would be O(n²) on the hot path, bloat the bundle,
- * and be wrong for Gemini/Ollama anyway). Used by the in-body reasoning counter
- * ("Thinking · N tokens").
+ * is a CLIENT ESTIMATE. This re-exports the SHARED estimator from
+ * `@docmost/token-estimate` (chars/2.5) so the in-body counter and the server's
+ * replay budgeter use the SAME heuristic — two divergent estimators would mean
+ * "the badge shows 60%" while "the budgeter already trimmed" (#490). Used by the
+ * in-body reasoning counter ("Thinking · N tokens").
  */
-
-/**
- * Rough token estimate for a piece of text using the standard chars/≈4 heuristic.
- * Returns 0 for empty/whitespace-free-of-content input, and ceils so any
- * non-empty text counts as at least one token.
- */
-export function estimateTokens(text: string): number {
-  if (!text) return 0;
-  return Math.ceil(text.length / 4);
-}
+export { estimateTokens } from "@docmost/token-estimate";

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

@@ -89,6 +89,23 @@ describe("describeChatError", () => {
     expect(view.title).not.toBe("AI provider not configured");
   });
 
+  it("classifies a token-degeneration abort under the SAME 'Response stopped.' marker the live view shows (#495)", () => {
+    // The exact reason the server persists in metadata.error on a degeneration
+    // abort (ai-chat.service OUTPUT_DEGENERATION_ERROR). Live, this event shows
+    // the neutral "Response stopped." notice; the persisted banner MUST match it
+    // so live and refetch never disagree.
+    const view = describeChatError(
+      "Output degeneration detected (repeated token loop)",
+      t,
+    );
+    expect(view.title).toBe("Response stopped.");
+    expect(view.detail).toBe(
+      "The answer was stopped automatically because the model fell into a repeated output loop.",
+    );
+    // Regression guard: it must NOT fall through to the generic heading.
+    expect(view.title).not.toBe("Something went wrong");
+  });
+
   it("classifies a dropped connection (ECONNRESET) as a lost-connection error", () => {
     expect(
       describeChatError("Cannot connect to API: read ECONNRESET", t).title,

apps/client/src/features/ai-chat/utils/error-message.ts

@@ -77,6 +77,22 @@ export function describeChatError(
     };
   }
 
+  // Our own token-degeneration abort (#444): the server aborts a runaway
+  // repetition loop and persists this exact reason in metadata.error. LIVE, the
+  // same abort surfaces as the neutral "Response stopped." notice (the client
+  // cannot tell it from a manual Stop mid-stream), so the persisted banner must
+  // read the SAME "Response stopped." marker — otherwise the live view and a
+  // later refetch show two different texts for one event. The detail explains the
+  // loop-guard cause without contradicting the shared heading.
+  if (/output degeneration detected|repeated token loop/i.test(msg)) {
+    return {
+      title: t("Response stopped."),
+      detail: t(
+        "The answer was stopped automatically because the model fell into a repeated output loop.",
+      ),
+    };
+  }
+
   if (/"statusCode"\s*:\s*403\b/.test(msg)) {
     return {
       title: t("AI chat is disabled"),

apps/client/src/features/editor/components/fixed-toolbar/use-toolbar-state.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from "vitest";
+import * as Y from "yjs";
+import { yHistoryAvailability } from "./use-toolbar-state.ts";
+
+// Undo/redo availability is derived from the Yjs UndoManager's PRIVATE
+// `undoStack` / `redoStack` fields (see use-toolbar-state.ts for why we read the
+// stack lengths directly instead of the expensive `editor.can().undo()` dry-run).
+// These tests lock in the behavior AND pin the library shape so a yjs / y-undo
+// upgrade that renames/restructures those internals fails loudly here rather than
+// silently enabling/disabling the toolbar buttons in production.
+describe("yHistoryAvailability", () => {
+  it("reports availability from the stack lengths", () => {
+    expect(yHistoryAvailability({ undoStack: [], redoStack: [] })).toEqual({
+      canUndo: false,
+      canRedo: false,
+    });
+    expect(
+      yHistoryAvailability({ undoStack: [{}], redoStack: [] }),
+    ).toEqual({ canUndo: true, canRedo: false });
+    expect(
+      yHistoryAvailability({ undoStack: [{}], redoStack: [{}, {}] }),
+    ).toEqual({ canUndo: true, canRedo: true });
+  });
+
+  it("returns null when the private stack shape is unrecognized (upgrade guard)", () => {
+    // Simulates a yjs / y-undo upgrade that renames or restructures the private
+    // fields: the caller then falls back to the safe prosemirror-history default
+    // instead of throwing on `.length` of undefined or reading garbage.
+    expect(yHistoryAvailability(undefined)).toBeNull();
+    expect(yHistoryAvailability(null)).toBeNull();
+    expect(yHistoryAvailability({})).toBeNull();
+    expect(yHistoryAvailability({ undoStack: 5, redoStack: 5 })).toBeNull();
+    // Only one stack present (partial rename) is still not trusted.
+    expect(yHistoryAvailability({ undoStack: [] })).toBeNull();
+  });
+
+  it("pin-test: a real yjs UndoManager still exposes undoStack/redoStack arrays", () => {
+    const doc = new Y.Doc();
+    const text = doc.getText("prosemirror");
+    const undoManager = new Y.UndoManager(text);
+
+    // Fresh manager: both stacks empty -> nothing to undo/redo.
+    expect(yHistoryAvailability(undoManager)).toEqual({
+      canUndo: false,
+      canRedo: false,
+    });
+
+    // A tracked edit must push onto the private undoStack. If a future yjs
+    // renames these fields, yHistoryAvailability(undoManager) returns null and
+    // the expectation below fails loudly.
+    text.insert(0, "hello");
+    undoManager.stopCapturing();
+    expect(yHistoryAvailability(undoManager)).toEqual({
+      canUndo: true,
+      canRedo: false,
+    });
+
+    // Undoing moves the item to the redoStack -> redo becomes available.
+    undoManager.undo();
+    expect(yHistoryAvailability(undoManager)).toEqual({
+      canUndo: false,
+      canRedo: true,
+    });
+  });
+});

apps/client/src/features/editor/components/fixed-toolbar/use-toolbar-state.ts

@@ -35,6 +35,30 @@ export interface ToolbarState {
 // When neither history backend is installed (the pre-sync static editor —
 // mainExtensions only, undoRedo disabled), both fall through to 0 -> false,
 // matching the previous `safeCan` behavior.
+// Reads the Yjs UndoManager's undo/redo availability from its stack lengths.
+//
+// `undoStack` / `redoStack` are PRIVATE y-undo / yjs internals, so we touch them
+// defensively: a yjs or y-undo upgrade that renames or restructures these fields
+// must not silently mis-drive the toolbar buttons (nor throw on `.length` of
+// `undefined`). We only trust them when they are actually arrays; otherwise this
+// returns null and the caller falls back to a safe default. The pin-test in
+// use-toolbar-state.test.ts asserts the current library shape, so an upgrade that
+// breaks this contract fails loudly there instead of failing silently in the UI.
+export function yHistoryAvailability(
+  undoManager: unknown,
+): { canUndo: boolean; canRedo: boolean } | null {
+  if (!undoManager || typeof undoManager !== "object") return null;
+  const { undoStack, redoStack } = undoManager as {
+    undoStack?: unknown;
+    redoStack?: unknown;
+  };
+  if (!Array.isArray(undoStack) || !Array.isArray(redoStack)) return null;
+  return {
+    canUndo: undoStack.length > 0,
+    canRedo: redoStack.length > 0,
+  };
+}
+
 function historyAvailability(editor: Editor): {
   canUndo: boolean;
   canRedo: boolean;
@@ -43,16 +67,14 @@ function historyAvailability(editor: Editor): {
 
   // Collaboration history (Yjs) takes precedence when present.
   const yState = yUndoPluginKey.getState(state) as
-    | { undoManager?: { undoStack: unknown[]; redoStack: unknown[] } }
+    | { undoManager?: unknown }
     | undefined;
-  if (yState?.undoManager) {
-    return {
-      canUndo: yState.undoManager.undoStack.length > 0,
-      canRedo: yState.undoManager.redoStack.length > 0,
-    };
-  }
+  const yAvail = yHistoryAvailability(yState?.undoManager);
+  if (yAvail) return yAvail;
 
   // Plain prosemirror-history (returns 0 when the history plugin is absent).
+  // This is also the safe default when a Yjs UndoManager is present but its
+  // private stack shape is no longer recognized (yHistoryAvailability -> null).
   return {
     canUndo: undoDepth(state) > 0,
     canRedo: redoDepth(state) > 0,

apps/client/src/features/editor/gitmost/gitmost-recording.test.ts

@@ -9,7 +9,7 @@ import { Italic } from "@tiptap/extension-italic";
 import { Link } from "@tiptap/extension-link";
 import { gitmostInsertTranscriptIntoEditor } from "./gitmost-recording.ts";
 
-const ZWSP = "​"; // U+200B, the helper's block-trigger neutralizer
+const ZWSP = "​"; // U+200B — asserted ABSENT (the block-escape lives in the serializer now)
 
 /**
  * #377 — the web-side bridge must append the native host's transcript below the
@@ -18,8 +18,9 @@ const ZWSP = "​"; // U+200B, the helper's block-trigger neutralizer
  * regression would be caught), asserting the resulting document rather than
  * mocking the editor: transcript present -> "Transcript" heading + one paragraph
  * per non-empty line; content is inserted as LITERAL TEXT (no HTML/markdown
- * parsing); col-0 markdown block triggers are neutralized so git-sync keeps them
- * paragraphs; absent/empty/non-string -> no-op.
+ * parsing); col-0 markdown block triggers are stored verbatim (the git-sync
+ * serializer block-escapes them, so no client-side ZWSP is needed);
+ * absent/empty/non-string -> no-op.
  */
 describe("gitmostInsertTranscriptIntoEditor", () => {
   const makeEditor = () =>
@@ -91,19 +92,22 @@ describe("gitmostInsertTranscriptIntoEditor", () => {
     editor.destroy();
   });
 
-  it("neutralizes col-0 markdown block triggers with a leading ZWSP (git-sync safety)", () => {
+  it("inserts col-0 markdown block triggers as verbatim paragraph text (no ZWSP workaround)", () => {
     const editor = makeEditor();
-    // Trigger lines (some with a leaked indent) + a normal prefixed line.
+    // Trigger lines (some with a leaked indent) + a normal prefixed line. The
+    // git-sync serializer now block-escapes a leading trigger itself, so the
+    // bridge inserts each line's TEXT byte-exact (only the leaked indent is
+    // trimmed) — no invisible ZWSP is prepended anymore.
     const inserted = gitmostInsertTranscriptIntoEditor(
       editor,
       [
         "- dash",
-        "  > quote", // leading indent must be trimmed then neutralized
+        "  > quote", // leading indent is trimmed, text otherwise verbatim
         "# hash",
         "1. one",
         "> [!info] note",
         "```js",
-        "---", // solid thematic break -> horizontalRule (text-losing) if unneutralized
+        "---",
         "***",
         "___",
         "You: normal line",
@@ -116,20 +120,23 @@ describe("gitmostInsertTranscriptIntoEditor", () => {
       .map((n: any) => n.content?.[0]?.text)
       .filter((t: any) => typeof t === "string") as string[];
 
-    // Every block-trigger line is prefixed with the invisible ZWSP (indent
-    // trimmed first); the normal `You:` line is left byte-exact.
+    // Each trigger line is stored as its own byte-exact text (indent trimmed);
+    // the git-sync round-trip keeps it a paragraph via the serializer's
+    // block-escape, so no ZWSP is needed here.
     expect(texts).toEqual([
-      ZWSP + "- dash",
-      ZWSP + "> quote",
-      ZWSP + "# hash",
-      ZWSP + "1. one",
-      ZWSP + "> [!info] note",
-      ZWSP + "```js",
-      ZWSP + "---",
-      ZWSP + "***",
-      ZWSP + "___",
+      "- dash",
+      "> quote",
+      "# hash",
+      "1. one",
+      "> [!info] note",
+      "```js",
+      "---",
+      "***",
+      "___",
       "You: normal line",
     ]);
+    // Guard: no invisible ZWSP leaked into any inserted line.
+    for (const t of texts) expect(t).not.toContain(ZWSP);
 
     editor.destroy();
   });

apps/client/src/features/editor/gitmost/gitmost-recording.ts

@@ -240,45 +240,22 @@ export async function gitmostUploadFileToEditor(
   }
 }
 
-// Zero-width space (U+200B). Prepended to a transcript line that begins with a
-// markdown BLOCK trigger: it is invisible in the rendered doc but shifts the
-// trigger off column 0, so the git-sync doc->markdown->doc round-trip keeps the
-// line a plain paragraph (see GITMOST_MD_BLOCK_TRIGGER_RE).
-const GITMOST_ZWSP = "​";
-
-// A markdown BLOCK-level construct that, sitting at column 0 of a paragraph
-// line, the git-sync markdown serializer (packages/prosemirror-markdown
-// markdown-converter.ts, `case "paragraph"`) would re-parse into a NON-paragraph
-// block on the doc->markdown->doc cycle. That serializer emits paragraph text
-// verbatim with NO block-escape (the pre-existing root cause), so a leading
-// `#`/`-`/`*`/`+`/`>`, an ordered-list `N.`/`N)`, a code fence ```/~~~, a table
-// `|`, or a `> [!info]` callout opener would silently become a heading / list /
-// quote / code block / table / callout. The final alternative matches a WHOLE-
-// LINE thematic break — solid `---`/`***`/`___` or spaced `- - -`/`_ _ _` (3+ of
-// the same `-`/`*`/`_`) — which round-trips into a `horizontalRule`; because
-// that node carries NO text, an un-neutralized separator line would LOSE its
-// text entirely (worse than the list/quote case). This matches a TRIMMED line's
-// start; the transcript's own `You:` / `Speaker N:` prefix begins with a letter
-// and never matches, so prefixed lines are left byte-exact.
-const GITMOST_MD_BLOCK_TRIGGER_RE =
-  /^(?:#{1,6}(?:\s|$)|[-*+](?:\s|$)|>|\d+[.)](?:\s|$)|```|~~~|\||([-*_])(?:\s*\1){2,}\s*$)/;
-
 // Append a transcript block BELOW the recording's audio node in a live editor:
 // a "Transcript" heading followed by one paragraph per non-empty transcript
 // line. The transcript is plain text, `\n`-separated, each line already
 // formatted as `You: ...` / `Speaker N: ...` by the native host — line text is
 // inserted as a TEXT node (never HTML/markdown), so there is no injection or
 // mark-parsing surface. Each kept line is trimmed (drops an indent that would
-// both leak into the display and, at col 0, form a markdown block trigger) and,
-// if it still begins with a col-0 markdown block trigger, gets an invisible
-// zero-width space prepended so the git-sync round-trip cannot turn it into a
-// list/quote/heading/callout/code/table (defensive boundary against the
-// serializer's missing block-escape). This is best-effort and meant to run
-// AFTER the audio has already been inserted; the caller must guard against a
-// throw so a transcript failure never fails the (already successful) recording.
-// Returns true when a block was inserted, false when there was nothing to
-// insert (transcript undefined/empty/not-a-string). A non-string value is a
-// no-op, not an error.
+// leak into the display). A line that begins with a col-0 markdown block
+// trigger (`#`/`-`/`>`/`1.`/fence/`---`/…) needs no client-side workaround: the
+// git-sync serializer (packages/prosemirror-markdown, `case "paragraph"`) now
+// block-escapes such a leading trigger, so the doc->markdown->doc round-trip
+// keeps the line a paragraph on its own — the former invisible-ZWSP defense is
+// gone. This is best-effort and meant to run AFTER the audio has already been
+// inserted; the caller must guard against a throw so a transcript failure never
+// fails the (already successful) recording. Returns true when a block was
+// inserted, false when there was nothing to insert (transcript
+// undefined/empty/not-a-string). A non-string value is a no-op, not an error.
 export function gitmostInsertTranscriptIntoEditor(
   editor: Editor,
   transcript: unknown,
@@ -288,13 +265,7 @@ export function gitmostInsertTranscriptIntoEditor(
     .split("\n")
     // Trim each line and drop blank (whitespace-only) ones.
     .map((line) => line.trim())
-    .filter((line) => line.length > 0)
-    // Neutralize a col-0 markdown block trigger with an invisible ZWSP so the
-    // git-sync round-trip keeps the line a paragraph. Host lines (`You:` /
-    // `Speaker N:`) never match and stay byte-exact.
-    .map((line) =>
-      GITMOST_MD_BLOCK_TRIGGER_RE.test(line) ? GITMOST_ZWSP + line : line,
-    );
+    .filter((line) => line.length > 0);
   if (lines.length === 0) return false;
 
   const content = [

apps/client/src/features/page/tree/components/space-tree.tsx

@@ -281,9 +281,11 @@ const SpaceTree = forwardRef<SpaceTreeApi, SpaceTreeProps>(function SpaceTree(
       setOpenTreeNodes((prev) => ({ ...prev, [id]: isOpen }));
       if (isOpen) {
         const node = treeModel.find(data, id) as SpaceTreeNode | null;
-        // Same "unloaded branch" predicate the insert paths use (`isUnloadedBranch`)
-        // so the lazy-load gate and the realtime/DnD inserts can never disagree
-        // about what counts as unloaded (#525).
+        // Same "unloaded branch" predicate the realtime insert paths use
+        // (`isUnloadedBranch`) so the lazy-load gate and the realtime inserts
+        // (`insertByPosition` / `placeByPosition`) can never disagree about what
+        // counts as unloaded (#525). Note: local raw `insert` (DnD/create-page)
+        // does not yet route through it — see #525 follow-up.
         if (treeModel.isUnloadedBranch(node)) {
           const fetched = await fetchAllAncestorChildren({
             pageId: id,

apps/client/src/features/page/tree/model/tree-model.ts

@@ -49,9 +49,11 @@ export const treeModel = {
   // resetting collapsed branches), NOT `children: undefined` — so a predicate that
   // only checks `=== undefined` misses the real case and materializes a misleading
   // partial list (#525). This is the SINGLE source of truth for "should a
-  // fetch/materialize be deferred?", shared by the lazy-load gate (`handleToggle`),
-  // the realtime insert path (`insertByPosition`) and the DnD move guard, so they
-  // can never drift apart again. A parent WITHOUT `hasChildren` is genuinely empty
+  // fetch/materialize be deferred?", shared by the lazy-load gate (`handleToggle`)
+  // and the realtime insert paths (`insertByPosition` / `placeByPosition`), so they
+  // can never drift apart again. (The local raw `insert` primitive and its DnD/
+  // create-page callers do NOT yet route through this predicate — see #525
+  // follow-up.) A parent WITHOUT `hasChildren` is genuinely empty
   // (no server children) — inserting its first child is correct, not deferred.
   isUnloadedBranch<T extends object>(
     node: TreeNode<T> | null | undefined,

apps/client/src/features/share/components/share-alias-section.test.tsx

@@ -13,8 +13,7 @@ let currentAlias: IShareAlias | null = null;
 let availabilityResult: {
   valid: boolean;
   available: boolean;
-  currentPageId: string | null;
-} = { valid: true, available: true, currentPageId: null };
+} = { valid: true, available: true };
 
 vi.mock("@/features/share/queries/share-query.ts", () => ({
   useShareAliasForPageQuery: () => ({ data: currentAlias }),
@@ -56,7 +55,7 @@ describe("ShareAliasSection — taken-name handling is never a dead end", () =>
   beforeEach(() => {
     setMutateAsync.mockReset();
     currentAlias = null;
-    availabilityResult = { valid: true, available: true, currentPageId: null };
+    availabilityResult = { valid: true, available: true };
   });
 
   it("shows a 'will move it here' HINT (not a terminal error) when the name belongs to another page, and keeps Save enabled", async () => {
@@ -65,7 +64,6 @@ describe("ShareAliasSection — taken-name handling is never a dead end", () =>
     availabilityResult = {
       valid: true,
       available: false,
-      currentPageId: "page-X",
     };
 
     renderSection("page-Y");
@@ -97,7 +95,6 @@ describe("ShareAliasSection — taken-name handling is never a dead end", () =>
     availabilityResult = {
       valid: true,
       available: false,
-      currentPageId: "page-X",
     };
     // The server rejects the un-confirmed save asking the client to confirm.
     setMutateAsync.mockRejectedValueOnce({
@@ -106,7 +103,6 @@ describe("ShareAliasSection — taken-name handling is never a dead end", () =>
         status: 409,
         data: {
           code: "ALIAS_REASSIGN_REQUIRED",
-          currentPageId: "page-X",
           currentPageTitle: "Alias Test Page X",
         },
       },

apps/client/src/features/share/components/share-alias-section.tsx

@@ -48,7 +48,6 @@ export default function ShareAliasSection({
   const [availability, setAvailability] = useState<{
     valid: boolean;
     available: boolean;
-    currentPageId: string | null;
   } | null>(null);
   const [reassign, setReassign] = useState<{
     alias: string;
@@ -76,7 +75,6 @@ export default function ShareAliasSection({
         setAvailability({
           valid: res.valid,
           available: res.available,
-          currentPageId: res.currentPageId,
         });
       } catch {
         setAvailability(null);

apps/client/src/features/share/types/share.types.ts

@@ -108,7 +108,6 @@ export interface IShareAliasAvailability {
   alias: string;
   valid: boolean;
   available: boolean;
-  currentPageId: string | null;
 }
 
 export interface ISharedPageTree {

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

@@ -28,6 +28,7 @@ import {
   IAiMcpServerCreate,
   IAiMcpServerUpdate,
 } from "@/features/workspace/services/ai-mcp-server-service.ts";
+import { resolveToolAllowlist } from "./ai-mcp-server-form.utils.ts";
 
 const formSchema = z.object({
   name: z.string().min(1),
@@ -121,13 +122,20 @@ export default function AiMcpServerForm({
   async function handleSubmit(values: FormValues) {
     const headers = resolveHeaders();
 
+    // An empty tag field means "no restriction" (sent as null) — since #476 the
+    // server persists a literal `[]` as deny-all (zero tools). But a server that
+    // was ALREADY deny-all loads into an empty field too; sending null there
+    // would silently widen it to allow-all on a routine edit, so preserve `[]`.
+    // See resolveToolAllowlist for the full rationale.
+    const toolAllowlist = resolveToolAllowlist(values.toolAllowlist, server);
+
     if (isEdit && server) {
       const payload: IAiMcpServerUpdate = {
         id: server.id,
         name: values.name,
         transport: values.transport,
         url: values.url,
-        toolAllowlist: values.toolAllowlist,
+        toolAllowlist,
         // Always sent: a blank value clears the stored guidance (server -> null).
         instructions: values.instructions,
         enabled: values.enabled,
@@ -140,7 +148,7 @@ export default function AiMcpServerForm({
         name: values.name,
         transport: values.transport,
         url: values.url,
-        toolAllowlist: values.toolAllowlist,
+        toolAllowlist,
         // Blank => server stores null (no guidance).
         instructions: values.instructions,
         enabled: values.enabled,

apps/client/src/features/workspace/components/settings/components/ai-mcp-server-form.utils.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import { resolveToolAllowlist } from "./ai-mcp-server-form.utils.ts";
+
+describe("resolveToolAllowlist", () => {
+  it("sends the typed tools when the field is non-empty", () => {
+    expect(resolveToolAllowlist(["a", "b"], { toolAllowlist: null })).toEqual([
+      "a",
+      "b",
+    ]);
+  });
+
+  it("creates as null (unrestricted) when empty and there is no server", () => {
+    expect(resolveToolAllowlist([], undefined)).toBeNull();
+  });
+
+  it("sends null for an empty field on a previously-unrestricted server", () => {
+    expect(resolveToolAllowlist([], { toolAllowlist: null })).toBeNull();
+  });
+
+  it("preserves deny-all: an empty field on a `[]` server stays `[]`, not null", () => {
+    // The core #476/#477 guard: editing a deny-all server (rename/toggle) with
+    // an empty tag field must NOT silently widen it to allow-all.
+    expect(resolveToolAllowlist([], { toolAllowlist: [] })).toEqual([]);
+  });
+
+  it("still sends explicit tools even if the server was deny-all", () => {
+    expect(resolveToolAllowlist(["x"], { toolAllowlist: [] })).toEqual(["x"]);
+  });
+});

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

@@ -0,0 +1,22 @@
+import { IAiMcpServer } from "@/features/workspace/services/ai-mcp-server-service.ts";
+
+// Resolve the tool allowlist value to persist from the form field.
+//
+// An empty tag field normally means "no restriction" and is sent as null so
+// the server drops the column (all tools allowed). But a server that was
+// ALREADY deny-all (a stored literal `[]`, meaning zero tools — creatable via
+// the API) loads into the form as an empty field too. Coercing that empty
+// field to null on submit would SILENTLY widen a deny-all server to allow-all
+// on any routine edit (rename, toggle) — the exact silent-widen class #476
+// closed on the read side. So when the edited server was deny-all, preserve
+// `[]` (deny-all); only a genuinely-unrestricted server (stored null/absent)
+// stays null.
+export function resolveToolAllowlist(
+  fieldValue: string[],
+  server?: Pick<IAiMcpServer, "toolAllowlist">,
+): string[] | null {
+  if (fieldValue.length > 0) return fieldValue;
+  const wasDenyAll =
+    Array.isArray(server?.toolAllowlist) && server.toolAllowlist.length === 0;
+  return wasDenyAll ? [] : null;
+}

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

@@ -6,6 +6,8 @@ import {
   nextReindexPollInterval,
   isReindexComplete,
   isReindexButtonLoading,
+  reindexRunKey,
+  isNewReindexRun,
 } from './ai-provider-settings';
 
 describe('resolveCardStatus', () => {
@@ -221,6 +223,128 @@ describe('isReindexComplete', () => {
   });
 });
 
+describe('reindexRunKey', () => {
+  it('is null when the status carries no run identity', () => {
+    expect(reindexRunKey(undefined)).toBeNull();
+    expect(
+      reindexRunKey({ reindexing: false, indexedPages: 5, totalPages: 5 }),
+    ).toBeNull();
+  });
+
+  it('is null for a legacy/degraded record with an empty runId', () => {
+    // The server sends runId='' for a record written before the field existed;
+    // the client must treat that as "no identity" (fall back to prior behaviour).
+    expect(
+      reindexRunKey({
+        reindexing: true,
+        indexedPages: 0,
+        totalPages: 10,
+        runId: '',
+        reindexStartedAt: 1000,
+      }),
+    ).toBeNull();
+  });
+
+  it('folds runId and startedAt into one stable key', () => {
+    expect(
+      reindexRunKey({
+        reindexing: true,
+        indexedPages: 0,
+        totalPages: 10,
+        runId: 'run-a',
+        reindexStartedAt: 1000,
+      }),
+    ).toBe('run-a:1000');
+  });
+
+  it('changes when the runId changes for the same startedAt', () => {
+    const a = reindexRunKey({
+      reindexing: true,
+      indexedPages: 0,
+      totalPages: 10,
+      runId: 'run-a',
+      reindexStartedAt: 1000,
+    });
+    const b = reindexRunKey({
+      reindexing: true,
+      indexedPages: 0,
+      totalPages: 10,
+      runId: 'run-b',
+      reindexStartedAt: 1000,
+    });
+    expect(a).not.toBe(b);
+  });
+
+  it('changes when the same runId restarts at a new startedAt', () => {
+    const a = reindexRunKey({
+      reindexing: true,
+      indexedPages: 0,
+      totalPages: 10,
+      runId: 'run-a',
+      reindexStartedAt: 1000,
+    });
+    const b = reindexRunKey({
+      reindexing: true,
+      indexedPages: 0,
+      totalPages: 10,
+      runId: 'run-a',
+      reindexStartedAt: 2000,
+    });
+    expect(a).not.toBe(b);
+  });
+});
+
+describe('isNewReindexRun (poll keying on runId)', () => {
+  // Derive the status shape from the helper itself so the test needs no export
+  // of the component-internal ReindexStatus type.
+  type ReindexStatusLike = NonNullable<Parameters<typeof reindexRunKey>[0]>;
+  const run = (runId: string, startedAt: number): ReindexStatusLike => ({
+    reindexing: true,
+    indexedPages: 0,
+    totalPages: 10,
+    runId,
+    reindexStartedAt: startedAt,
+  });
+
+  it('first identity after none latched is a NEW run', () => {
+    expect(isNewReindexRun(null, run('run-a', 1000))).toBe(true);
+  });
+
+  it('the SAME identity is not a new run (same run being watched)', () => {
+    const key = reindexRunKey(run('run-a', 1000));
+    expect(isNewReindexRun(key, run('run-a', 1000))).toBe(false);
+  });
+
+  it('a DIFFERENT runId is a new run (reset per-run poll state)', () => {
+    const key = reindexRunKey(run('run-a', 1000));
+    expect(isNewReindexRun(key, run('run-b', 1000))).toBe(true);
+  });
+
+  it('an identity-less poll (no runId / cleared record) is never a new run', () => {
+    const key = reindexRunKey(run('run-a', 1000));
+    expect(
+      isNewReindexRun(key, {
+        reindexing: false,
+        indexedPages: 10,
+        totalPages: 10,
+      }),
+    ).toBe(false);
+  });
+
+  it('a legacy empty-runId poll does not spuriously reset a latched run', () => {
+    const key = reindexRunKey(run('run-a', 1000));
+    expect(
+      isNewReindexRun(key, {
+        reindexing: true,
+        indexedPages: 3,
+        totalPages: 10,
+        runId: '',
+        reindexStartedAt: 1000,
+      }),
+    ).toBe(false);
+  });
+});
+
 describe('isReindexButtonLoading', () => {
   it('loads while the POST mutation is pending', () => {
     expect(

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

@@ -173,9 +173,43 @@ export function resolveKeyField(
 // Subset of the status payload that drives the reindex poll decisions.
 type ReindexStatus = Pick<
   IAiSettings,
-  "reindexing" | "indexedPages" | "totalPages"
+  "reindexing" | "indexedPages" | "totalPages" | "runId" | "reindexStartedAt"
 >;
 
+/**
+ * A stable per-RUN key for the reindex poll: `runId:startedAt`, or `null` when
+ * the status carries no run identity (no active run, or a legacy/degraded
+ * server record with an empty runId). Two polls of the SAME run share a key; a
+ * new run mints a fresh runId and so a different key.
+ *
+ * This is the single place the client turns the server's run identity into the
+ * value it keys on — it removes the "is this the same run I've been watching or
+ * a brand-new one?" ambiguity that made a class of reindex-status bugs (a stale
+ * pre-reindex snapshot vs a fresh run) get fixed twice (#262). `startedAt` is
+ * folded in so a run that somehow reuses a runId but restarted is still new.
+ */
+export function reindexRunKey(status: ReindexStatus | undefined): string | null {
+  const runId = status?.runId;
+  if (!runId) return null;
+  return `${runId}:${status?.reindexStartedAt ?? ""}`;
+}
+
+/**
+ * Decide whether the latest poll represents a NEW reindex run relative to the
+ * run key the client last latched (`prevKey`, `null` if none yet). True only
+ * when the status carries an identity AND it differs from the latched one — the
+ * signal to reset any per-run poll state (the "seen active" latch / progress the
+ * UI held). The same identity (or no identity) is NOT a new run, so an unchanged
+ * or identity-less poll never resets mid-run.
+ */
+export function isNewReindexRun(
+  prevKey: string | null,
+  status: ReindexStatus | undefined,
+): boolean {
+  const key = reindexRunKey(status);
+  return key !== null && key !== prevKey;
+}
+
 /**
  * Decide the TanStack Query `refetchInterval` while a reindex may be running.
  * Returns the poll interval (ms) to keep polling, or `false` to stop.
@@ -320,6 +354,13 @@ export default function AiProviderSettings() {
   // counter at 0 until a manual reload. A ref (not state) because it must not
   // trigger a render and is only ever read where `reindexing` is already false.
   const reindexSeenActiveRef = useRef(false);
+  // The run identity (runId:startedAt) the current poll window is keyed on. When
+  // a poll reports a DIFFERENT runId the server has started a NEW run, so we
+  // re-latch to it and reset `reindexSeenActiveRef` — a fresh run must never
+  // inherit the previous run's "seen active"/completion state (which would stop
+  // polling immediately or read the old run's counters as this run's). null =
+  // no run keyed yet (steady state, or a legacy record without a runId).
+  const reindexRunKeyRef = useRef<string | null>(null);
 
   // Only admins may read the (masked) AI settings; the server enforces this too.
   const { data: settings, isLoading } = useAiSettingsQuery(isAdmin, (query) =>
@@ -336,6 +377,14 @@ export default function AiProviderSettings() {
   // unmount because the deadline state goes away with the component.
   useEffect(() => {
     if (reindexDeadline === null) return;
+    // Key the poll on the run identity: if this poll carries a runId different
+    // from the one we latched, the server started a NEW run, so adopt it and
+    // drop the per-run "seen active" latch (a fresh run must not inherit the
+    // previous run's completion state). Same runId => same run, leave it alone.
+    if (isNewReindexRun(reindexRunKeyRef.current, settings)) {
+      reindexRunKeyRef.current = reindexRunKey(settings);
+      reindexSeenActiveRef.current = false;
+    }
     // Latch "we have seen the active run" the moment a poll reports it, so the
     // completion check below (and the refetchInterval's) only fires once the run
     // has genuinely started — never on the stale pre-reindex snapshot.
@@ -1220,6 +1269,10 @@ export default function AiProviderSettings() {
                   // immediately.
                   onSuccess: () => {
                     reindexSeenActiveRef.current = false;
+                    // Forget the previous run's identity so the first poll of
+                    // this window (carrying the new run's runId) is recognized
+                    // as a new run and keyed afresh.
+                    reindexRunKeyRef.current = null;
                     setReindexDeadline(Date.now() + REINDEX_POLL_CAP_MS);
                   },
                 })

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

@@ -27,7 +27,9 @@ export interface IAiMcpServerCreate {
   // Auth headers map (e.g. { Authorization: 'Bearer ...' }). Encrypted on save;
   // never returned.
   headers?: Record<string, string>;
-  toolAllowlist?: string[];
+  // Omit/null => no restriction; `[]` is persisted verbatim and means
+  // deny-all (zero tools) since #476.
+  toolAllowlist?: string[] | null;
   // Admin-authored prompt guidance (#180). Blank => stored as null.
   instructions?: string;
   enabled?: boolean;
@@ -43,7 +45,9 @@ export interface IAiMcpServerUpdate {
   transport?: McpTransport;
   url?: string;
   headers?: Record<string, string>;
-  toolAllowlist?: string[];
+  // Absent => unchanged; null => no restriction; `[]` is persisted verbatim
+  // and means deny-all (zero tools) since #476.
+  toolAllowlist?: string[] | null;
   // Admin-authored prompt guidance (#180). Absent => unchanged; blank => cleared.
   instructions?: string;
   enabled?: boolean;

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

@@ -51,6 +51,14 @@ export interface IAiSettings {
   // True while a full workspace reindex is actively running; the counts above
   // then reflect the live run progress (done climbs 0 -> total).
   reindexing?: boolean;
+  // Identity of the ACTIVE reindex run (present only while `reindexing`). The
+  // poll keys on `runId`: a changed value means a NEW run (reset the per-run
+  // poll state the UI latched), the same value is the run already being watched.
+  // Absent/empty ('') => no identity available; the client keeps prior behaviour.
+  runId?: string;
+  // Epoch-ms the active run started; paired with `runId` so a restart with a
+  // recycled id is still detected as a new run.
+  reindexStartedAt?: number;
 }
 
 // Update payload. Key semantics (same for `apiKey` and `embeddingApiKey`):

apps/client/src/lib/telemetry/route-template.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { templateRoute } from "./route-template";
+import { templateRoute, KNOWN_ROUTE_TEMPLATES } from "./route-template";
 
 describe("templateRoute", () => {
   it("templates a space page path (never leaks slugs)", () => {
@@ -32,4 +32,30 @@ describe("templateRoute", () => {
     expect(templateRoute("/weird/unknown/thing")).toBe("other");
     expect(templateRoute("/s/team/p/slug/extra/segments")).toBe("other");
   });
+
+  // The server's /api/telemetry/vitals mirror (ALLOWED_ROUTE_TEMPLATES) drops any
+  // route outside KNOWN_ROUTE_TEMPLATES, so templateRoute must NEVER emit a label
+  // that is not in that dictionary — otherwise legit client metrics get dropped.
+  it("only ever emits labels contained in KNOWN_ROUTE_TEMPLATES (#495)", () => {
+    const samples = [
+      "/",
+      "/home",
+      "/settings/members",
+      "/settings/groups/g-1",
+      "/s/team",
+      "/s/team/trash",
+      "/s/team/p/slug",
+      "/p/slug",
+      "/share/abc",
+      "/share/abc/p/slug",
+      "/share/p/slug",
+      "/labels/urgent",
+      "/invites/inv-1",
+      "/weird/unknown/thing", // -> "other"
+      "/deep/unmatched/x/y/z", // -> "other"
+    ];
+    for (const path of samples) {
+      expect(KNOWN_ROUTE_TEMPLATES.has(templateRoute(path))).toBe(true);
+    }
+  });
 });

apps/client/src/lib/telemetry/route-template.ts

@@ -44,6 +44,22 @@ const STATIC_ROUTES = new Set<string>([
   '/settings/sharing',
 ]);
 
+/**
+ * The COMPLETE, finite vocabulary `templateRoute` can ever emit: the two
+ * synthetic labels (`/` and `other`), the static routes, and the dynamic
+ * templates. Exported so the public `/api/telemetry/vitals` endpoint can reject
+ * any `route` outside this dictionary server-side (the endpoint is anonymous, so
+ * an un-checked `route` is a free-text write surface). The server keeps a mirror
+ * (`ALLOWED_ROUTE_TEMPLATES` in client-metrics.constants.ts) — this is the
+ * canonical source; keep them in lockstep.
+ */
+export const KNOWN_ROUTE_TEMPLATES: ReadonlySet<string> = new Set<string>([
+  '/',
+  'other',
+  ...STATIC_ROUTES,
+  ...ROUTE_PATTERNS.map((p) => p.template),
+]);
+
 export function templateRoute(pathname: string): string {
   // Normalise a trailing slash (except root).
   const path =

apps/client/src/main.tsx

@@ -3,6 +3,7 @@ import "@mantine/spotlight/styles.css";
 import "@mantine/notifications/styles.css";
 import '@mantine/dates/styles.css';
 import "@/styles/a11y-overrides.css";
+import "@/styles/notification-overrides.css";
 
 import ReactDOM from "react-dom/client";
 import App from "./App.tsx";
@@ -47,7 +48,15 @@ function renderApp() {
       <MantineProvider theme={theme} cssVariablesResolver={mantineCssResolver}>
         <ModalsProvider>
           <QueryClientProvider client={queryClient}>
-            <Notifications position="bottom-center" limit={3} zIndex={10000} />
+            {/* top-center: toasts sit in the top of the viewport, in the line
+                of sight, and no longer cover centered content (e.g. "Load
+                more"). The below-chrome vertical offset is applied via a
+                position-scoped CSS rule in notification-overrides.css (NOT an
+                inline `style`): Mantine renders all six position containers at
+                once and an inline root style would land on every one, giving the
+                bottom-* containers both top+bottom → full-viewport transparent
+                overlays that swallow clicks. */}
+            <Notifications position="top-center" limit={3} zIndex={10000} />
             <HelmetProvider>
               {/* Root boundary above every lazy route's Suspense: a stale-chunk
                   404 after a deploy is caught and recovered here instead of

apps/client/src/styles/notification-overrides.css

@@ -0,0 +1,64 @@
+/*
+ * Toast (Mantine Notification) visibility overrides.
+ * Mantine renders colorless toasts on --mantine-color-body (== the page
+ * background: white in light mode) with a faint shadow, so on white pages the
+ * card has no visible edge. These rules give every toast a type-tinted
+ * background, a WCAG-checked border and a stronger shadow so it separates from
+ * the page. The [data-mantine-color-scheme] + static-class selector (0,2,0)
+ * beats Mantine's own (0,1,0) rules regardless of stylesheet order (Mantine's
+ * bg/border rules wrap the scheme attribute in :where(), so they stay (0,1,0)).
+ * --notification-color is defined on the same element (defaults to primary,
+ * set per `color` prop), so tint/border follow the toast type. This also covers
+ * the loading/import toast (no accent bar, since the spinner takes the icon
+ * slot): its visibility comes from tone + border + shadow + the colored spinner.
+ */
+
+/*
+ * Push the top-anchored toast containers below the top chrome (fixed 45px
+ * header + optional 45px format toolbar + ~6px gap) so a toast (z-index 10000)
+ * neither covers nor intercepts clicks on the header/toolbar (both z-index 99).
+ *
+ * Scoped to [data-position^='top'] on purpose. Mantine renders ALL SIX position
+ * containers simultaneously (`position` only routes toasts into one via the
+ * store); the root `style` prop would be applied to every one of them by
+ * getStyles("root"). A blanket `top` would land on the bottom-* containers too
+ * (which carry `bottom:16px`) → position:fixed + both edges + height:auto makes
+ * them stretch the full viewport height, and the container root has neither
+ * pointer-events:none nor a background, so those transparent z-10000 overlays
+ * would swallow clicks across the whole page. Restricting to top-* leaves the
+ * bottom containers at height:0.
+ *
+ * Specificity: `.mantine-Notifications-root[data-position^='top']` is (0,2,0)
+ * (class + attribute) and beats Mantine's own top rule
+ * `.m_b37d9ac7:where([data-position='top-center']){top:16px}` which is (0,1,0)
+ * (the :where() contributes 0), regardless of stylesheet order.
+ */
+.mantine-Notifications-root[data-position^='top'] {
+  top: 96px;
+}
+
+[data-mantine-color-scheme='light'] .mantine-Notification-root {
+  /* ~10% type color over white: clearly off-white, text contrast preserved */
+  background-color: color-mix(in srgb, var(--notification-color) 10%, var(--mantine-color-white));
+  /* Border must clear WCAG 3:1 non-text contrast on white. The repo rejects
+     gray-4 for this (a11y-overrides.css); gray-6 base (~3.32:1) darkened by the
+     type color stays >= 3:1. */
+  border: 1px solid color-mix(in srgb, var(--notification-color) 45%, var(--mantine-color-gray-6));
+  box-shadow: var(--mantine-shadow-xl);
+}
+
+[data-mantine-color-scheme='dark'] .mantine-Notification-root {
+  /* Dark page (dark-7/8) vs toast (dark-6) already separate a little; border +
+     shadow carry the type cue here (a 7% dark tint was near-invisible). */
+  background-color: color-mix(in srgb, var(--notification-color) 14%, var(--mantine-color-dark-6));
+  border: 1px solid color-mix(in srgb, var(--notification-color) 45%, var(--mantine-color-dark-3));
+  box-shadow: var(--mantine-shadow-xl);
+}
+
+/* Mantine's message-with-title color is gray-6 (#868e96, already only ~3.32:1
+   on white — below AA 4.5:1); the new tint pushes it lower. Bump to gray-7 to
+   keep multi-line colored toasts readable, consistent with the repo's existing
+   WCAG tuning (theme.ts already bumps this same gray-6 up elsewhere). */
+[data-mantine-color-scheme='light'] .mantine-Notification-description[data-with-title] {
+  color: var(--mantine-color-gray-7);
+}

apps/server/package.json

@@ -23,7 +23,7 @@
     "migration:reset": "tsx src/database/migrate.ts down-to NO_MIGRATIONS",
     "migration:codegen": "kysely-codegen --dialect=postgres --camel-case --env-file=../../.env --out-file=./src/database/types/db.d.ts",
     "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
-    "pretest": "pnpm --filter @docmost/editor-ext build && pnpm --filter @docmost/prosemirror-markdown build",
+    "pretest": "pnpm --filter @docmost/editor-ext build && pnpm --filter @docmost/prosemirror-markdown build && pnpm --filter @docmost/token-estimate build",
     "test": "jest",
     "test:int": "jest --config test/jest-integration.json",
     "test:watch": "jest --watch",
@@ -44,6 +44,7 @@
     "@docmost/mcp": "workspace:*",
     "@docmost/pdf-inspector": "1.9.6",
     "@docmost/prosemirror-markdown": "workspace:*",
+    "@docmost/token-estimate": "workspace:*",
     "@fastify/compress": "^9.0.0",
     "@fastify/cookie": "^11.0.2",
     "@fastify/multipart": "^10.0.0",
@@ -206,6 +207,7 @@
       "^@docmost/db/(.*)$": "<rootDir>/database/$1",
       "^@docmost/transactional/(.*)$": "<rootDir>/integrations/transactional/$1",
       "^@docmost/ee/(.*)$": "<rootDir>/ee/$1",
+      "^@docmost/token-estimate$": "<rootDir>/../../../packages/token-estimate/src/index.ts",
       "^src/(.*)$": "<rootDir>/$1",
       "^@tiptap/react$": "<rootDir>/../test/stubs/tiptap-react.js"
     }

apps/server/src/app.module.ts

@@ -25,7 +25,7 @@ import { CacheModule } from '@nestjs/cache-manager';
 import KeyvRedis from '@keyv/redis';
 import { LoggerModule } from './common/logger/logger.module';
 import { ClsModule } from 'nestjs-cls';
-import { NoopAuditModule } from './integrations/audit/audit.module';
+import { AuditModule } from './integrations/audit/audit.module';
 import { ThrottleModule } from './integrations/throttle/throttle.module';
 import { McpModule } from './integrations/mcp/mcp.module';
 import { SandboxModule } from './integrations/sandbox/sandbox.module';
@@ -55,7 +55,7 @@ try {
       middleware: { mount: true },
     }),
     LoggerModule,
-    NoopAuditModule,
+    AuditModule,
     CoreModule,
     DatabaseModule,
     EnvironmentModule,

apps/server/src/collaboration/yjs.util.spec.ts

@@ -529,4 +529,107 @@ describe('replaceYjsMarkedText', () => {
     expect(result).toEqual({ applied: false, currentText: 'abcdef' });
     expect(text.toDelta()).toEqual(before);
   });
+
+  // #496: apply must NOT silently strip the replaced run's inline formatting.
+  // Build a paragraph and format the marked range with extra marks, then assert
+  // the replacement carries them.
+  function buildFormatted(
+    runs: Array<{ text: string; attrs?: Record<string, any> }>,
+  ): { fragment: Y.XmlFragment; text: Y.XmlText } {
+    const ydoc = new Y.Doc();
+    const fragment = ydoc.getXmlFragment('default');
+    const para = new Y.XmlElement('paragraph');
+    fragment.insert(0, [para]);
+    const text = new Y.XmlText();
+    para.insert(0, [text]);
+    text.insert(0, runs.map((r) => r.text).join(''));
+    let offset = 0;
+    for (const run of runs) {
+      if (run.attrs) text.format(offset, run.text.length, run.attrs);
+      offset += run.text.length;
+    }
+    return { fragment, text };
+  }
+
+  it('preserves the original run formatting (bold + link) on the replacement', () => {
+    const { fragment, text } = buildFormatted([
+      { text: 'see ' },
+      {
+        text: 'old',
+        attrs: {
+          comment: { commentId: 'c1', resolved: false },
+          bold: true,
+          link: { href: 'https://x.test' },
+        },
+      },
+      { text: ' end' },
+    ]);
+
+    const result = replaceYjsMarkedText(fragment, 'c1', 'old', 'new');
+
+    expect(result).toEqual({ applied: true, currentText: 'new' });
+    // The comment anchor AND the bold/link marks survive the delete+insert.
+    expect(text.toDelta()).toEqual([
+      { insert: 'see ' },
+      {
+        insert: 'new',
+        attributes: {
+          comment: { commentId: 'c1', resolved: false },
+          bold: true,
+          link: { href: 'https://x.test' },
+        },
+      },
+      { insert: ' end' },
+    ]);
+  });
+
+  it('mixed formatting under the mark: replacement takes the DOMINANT (longest) run, NOT the leading one', () => {
+    // Leading run is SHORT + plain ("x", 1 char); the following run is LONGER +
+    // bold ("bolded", 6 chars), same commentId. The longest run is deliberately
+    // NOT first: a "first-wins" pick would carry plain (no bold), so asserting
+    // bold on the result only holds if the code genuinely selects the LONGEST run.
+    const { fragment, text } = buildFormatted([
+      { text: 'x', attrs: { comment: { commentId: 'c1', resolved: false } } },
+      {
+        text: 'bolded',
+        attrs: { comment: { commentId: 'c1', resolved: false }, bold: true },
+      },
+    ]);
+
+    const result = replaceYjsMarkedText(fragment, 'c1', 'xbolded', 'Z');
+
+    expect(result).toEqual({ applied: true, currentText: 'Z' });
+    expect(text.toDelta()).toEqual([
+      {
+        insert: 'Z',
+        attributes: { comment: { commentId: 'c1', resolved: false }, bold: true },
+      },
+    ]);
+  });
+
+  it('mixed formatting under the mark: on a length tie the FIRST run wins', () => {
+    // Two equal-length runs (2 chars each) with different formatting, same
+    // commentId. The reduce keeps the accumulator on a tie, so the FIRST run
+    // (italic) prevails over the later bold one.
+    const { fragment, text } = buildFormatted([
+      {
+        text: 'AA',
+        attrs: { comment: { commentId: 'c1', resolved: false }, italic: true },
+      },
+      {
+        text: 'BB',
+        attrs: { comment: { commentId: 'c1', resolved: false }, bold: true },
+      },
+    ]);
+
+    const result = replaceYjsMarkedText(fragment, 'c1', 'AABB', 'Z');
+
+    expect(result).toEqual({ applied: true, currentText: 'Z' });
+    expect(text.toDelta()).toEqual([
+      {
+        insert: 'Z',
+        attributes: { comment: { commentId: 'c1', resolved: false }, italic: true },
+      },
+    ]);
+  });
 });

apps/server/src/collaboration/yjs.util.ts

@@ -145,6 +145,10 @@ type MarkedSegment = {
   length: number;
   text: string;
   markAttrs: Record<string, any>;
+  // The FULL attribute set of this delta run — the `comment` mark plus any
+  // inline formatting (bold/italic/code/link/…). Captured so apply can carry the
+  // original run's formatting onto the replacement instead of dropping it.
+  attributes: Record<string, any>;
 };
 
 /**
@@ -202,6 +206,7 @@ export function replaceYjsMarkedText(
             length,
             text: insert,
             markAttrs: markAttr,
+            attributes,
           });
         }
         offset += length;
@@ -251,15 +256,25 @@ export function replaceYjsMarkedText(
     return { applied: false, currentText: joinedText };
   }
 
-  // 3. All guards passed: delete the marked run and re-insert newText with the
-  // same comment attributes at the same offset. Atomic within the caller's
-  // transaction.
+  // 3. All guards passed: delete the marked run and re-insert newText at the
+  // same offset. Atomic within the caller's transaction.
   const start = segments[0].offset;
   const len = segments.reduce((sum, s) => sum + s.length, 0);
-  const markAttrs = segments[0].markAttrs;
+
+  // Carry the ORIGINAL run's formatting onto the replacement (#496): inserting
+  // with only the `comment` mark silently dropped bold/italic/code/link of the
+  // replaced text. Yjs applies one flat attribute set to the whole insert, so
+  // when the marked run mixes formatting we pick the DOMINANT segment (the one
+  // covering the most characters) and apply its attributes — a v1 that preserves
+  // the common single-format case exactly and, for a mixed run, keeps the
+  // prevailing style rather than losing all of it. `attributes` already carries
+  // the `comment` mark (every collected segment is filtered on it above), so the
+  // anchor is preserved by copying the run's attribute set verbatim.
+  const dominant = segments.reduce((a, b) => (b.length > a.length ? b : a));
+  const insertAttrs = { ...dominant.attributes };
 
   node.delete(start, len);
-  node.insert(start, newText, { comment: markAttrs });
+  node.insert(start, newText, insertAttrs);
 
   return { applied: true, currentText: newText };
 }

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

@@ -181,7 +181,7 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
       {} as never, // pageAccess
       { isAiChatDeferredToolsEnabled: () => false, isAiChatFinalStepLockdownEnabled: () => false } as never, // environment
     );
-    return { svc };
+    return { svc, aiChatMessageRepo };
   }
 
   const body = {
@@ -287,7 +287,7 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
   // Drive stream() to the point streamText is called, capturing the options object
   // (which carries onStepFinish/onFinish/onError/onAbort) and the run hooks.
   async function captureStreamCallbacks() {
-    const { svc } = makeService();
+    const { svc, aiChatMessageRepo } = makeService();
     let capturedOpts: any;
     streamTextMock.mockImplementation((opts: any) => {
       capturedOpts = opts;
@@ -314,7 +314,7 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
       runHooks: runHooks as never,
     });
     expect(capturedOpts).toBeDefined();
-    return { capturedOpts, runHooks };
+    return { capturedOpts, runHooks, aiChatMessageRepo };
   }
 
   it('F9: onStepFinish bumps the run step count, onFinish settles the run "completed" (the dominant autonomous-run path)', async () => {
@@ -369,6 +369,51 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
       expect.stringContaining('provider exploded'),
     );
   });
+
+  // #490 reactive branch: a provider CONTEXT-OVERFLOW 400 in onError is classified,
+  // records a distinguishable cause, and stamps metadata.replayOverflow so the NEXT
+  // turn's budgeter trims aggressively (the recovery that un-bricks the chat).
+  it('#490: a context-overflow 400 stamps replayOverflow on the finalized row', async () => {
+    jest
+      .spyOn(Logger.prototype, 'error')
+      .mockImplementation(() => undefined as never);
+    jest
+      .spyOn(Logger.prototype, 'warn')
+      .mockImplementation(() => undefined as never);
+    const { capturedOpts, aiChatMessageRepo } = await captureStreamCallbacks();
+
+    const overflow = Object.assign(new Error('too large'), {
+      statusCode: 400,
+      message:
+        "This model's maximum context length is 128000 tokens. However, your messages resulted in 214000 tokens. Please reduce the length.",
+    });
+    await capturedOpts.onError({ error: overflow });
+
+    // The seed row exists (finalizeOwner is the owner-write path).
+    expect(aiChatMessageRepo.finalizeOwner).toHaveBeenCalled();
+    const calls = aiChatMessageRepo.finalizeOwner.mock.calls as any[][];
+    const patch = calls[calls.length - 1][2] as {
+      status: string;
+      metadata: Record<string, unknown>;
+    };
+    expect(patch.status).toBe('error');
+    expect(patch.metadata.replayOverflow).toBe(true);
+    expect(patch.metadata.error).toContain('контекстное окно');
+  });
+
+  it('#490: a non-overflow error does NOT stamp replayOverflow', async () => {
+    jest
+      .spyOn(Logger.prototype, 'error')
+      .mockImplementation(() => undefined as never);
+    const { capturedOpts, aiChatMessageRepo } = await captureStreamCallbacks();
+    await capturedOpts.onError({ error: new Error('network reset') });
+    const calls = aiChatMessageRepo.finalizeOwner.mock.calls as any[][];
+    const patch = calls[calls.length - 1][2] as {
+      status: string;
+      metadata: Record<string, unknown>;
+    };
+    expect('replayOverflow' in patch.metadata).toBe(false);
+  });
 });
 
 /**

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

@@ -13,6 +13,7 @@ import {
   compactToolOutput,
   assistantParts,
   serializeSteps,
+  type StepPartsCache,
   rowToUiMessage,
   prepareAgentStep,
   stepBudgetWarning,
@@ -28,10 +29,14 @@ import {
   FINAL_STEP_NUDGE,
   STEP_LIMIT_NO_ANSWER_MARKER,
   OUTPUT_DEGENERATION_ERROR,
+  lastAssistantContextTokens,
+  lastAssistantReplayOverflow,
+  seedActivatedTools,
 } from './ai-chat.service';
 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';
+import { resolveEffectiveReplayThreshold } from './history-budget';
 
 /**
  * Unit tests for compactToolOutput: the pure helper that shrinks tool outputs
@@ -114,6 +119,54 @@ describe('compactToolOutput', () => {
 describe('assistantParts', () => {
   type AnyPart = Record<string, unknown>;
 
+  // #490 memoization: assistantParts builds each step's parts once and caches
+  // them by the step OBJECT's identity, so a mid-stream flush does not
+  // re-stringify every prior step's (large) output. Observable property: with a
+  // shared cache, the second call over the SAME step object returns the cached
+  // (identical) part array even if the step's underlying output was swapped —
+  // proving the work was memoized, not redone.
+  it('memoizes a step by identity (shared cache => one build per step)', () => {
+    const cache: StepPartsCache = new WeakMap();
+    const step = {
+      text: 'x',
+      toolCalls: [{ toolCallId: 'c1', toolName: 'getPage', input: {} }],
+      toolResults: [{ toolCallId: 'c1', toolName: 'getPage', output: { v: 1 } }],
+    };
+    const first = assistantParts([step], '', cache) as AnyPart[];
+    expect((first.find((p) => p.type === 'tool-getPage')!.output as any).v).toBe(
+      1,
+    );
+    // Swap the output for a NEW value; a re-build would pick it up, a cache hit
+    // keeps the first result.
+    step.toolResults[0] = {
+      toolCallId: 'c1',
+      toolName: 'getPage',
+      output: { v: 2 },
+    };
+    const second = assistantParts([step], '', cache) as AnyPart[];
+    expect((second.find((p) => p.type === 'tool-getPage')!.output as any).v).toBe(
+      1,
+    );
+    // Same cached part objects are reused.
+    expect(second.find((p) => p.type === 'tool-getPage')).toBe(
+      first.find((p) => p.type === 'tool-getPage'),
+    );
+  });
+
+  it('without a cache, each call rebuilds (no stale memo)', () => {
+    const step = {
+      text: 'x',
+      toolCalls: [{ toolCallId: 'c1', toolName: 'getPage', input: {} }],
+      toolResults: [{ toolCallId: 'c1', toolName: 'getPage', output: { v: 1 } }],
+    };
+    const first = assistantParts([step], '') as AnyPart[];
+    step.toolResults[0].output = { v: 2 };
+    const second = assistantParts([step], '') as AnyPart[];
+    expect((second.find((p) => p.type === 'tool-getPage')!.output as any).v).toBe(
+      2,
+    );
+  });
+
   it('emits output-available for a tool-call WITH a paired result', () => {
     const steps = [
       {
@@ -231,61 +284,320 @@ describe('assistantParts', () => {
   });
 });
 
-describe('serializeSteps', () => {
+// #490 trace format v2: per call the trace stores { input } for the call and an
+// OUTCOME element — { ok: true } on success, { error, kind: 'thrown' } on a
+// thrown tool-error, { error, kind: 'interrupted' } on a mid-step abort. The tool
+// OUTPUT is no longer duplicated here (it lives once in metadata.parts).
+describe('serializeSteps (trace v2)', () => {
   it('returns null when there are no calls or results', () => {
     expect(serializeSteps([])).toBeNull();
   });
 
-  it('flattens calls and results into a compact trace', () => {
+  it('pairs a successful call with an { ok: true } outcome and NO output', () => {
     const trace = serializeSteps([
       {
-        toolCalls: [{ toolName: 'getPage', input: { id: 'p1' } }],
-        toolResults: [{ toolName: 'getPage', output: { title: 'T' } }],
+        toolCalls: [{ toolCallId: 'c1', toolName: 'getPage', input: { id: 'p1' } }],
+        toolResults: [{ toolCallId: 'c1', toolName: 'getPage' }],
       },
     ]) as Array<Record<string, unknown>>;
     expect(trace).toHaveLength(2);
     expect(trace[0]).toEqual({ toolName: 'getPage', input: { id: 'p1' } });
-    expect(trace[1]).toEqual({ toolName: 'getPage', output: { title: 'T' } });
+    expect(trace[1]).toEqual({ toolName: 'getPage', ok: true });
+    // The output is NOT stored in the trace any more (dedup: it lives in parts).
+    expect(trace.some((e) => 'output' in e)).toBe(false);
   });
 
-  it('records a THROWN tool failure (tool-error part) with its error message', () => {
+  it('records a THROWN failure with { error, kind: "thrown" }', () => {
     const trace = serializeSteps([
       {
-        toolCalls: [{ toolName: 'editPageText', input: { id: 'p1' } }],
+        toolCalls: [
+          { toolCallId: 'c1', toolName: 'editPageText', input: { id: 'p1' } },
+        ],
         toolResults: [],
         content: [
           {
             type: 'tool-error',
+            toolCallId: 'c1',
             toolName: 'editPageText',
             error: new Error('page is locked'),
           },
         ],
       },
     ]) as Array<Record<string, unknown>>;
-    // The call element is followed by a paired error element (mirroring how a
-    // successful result is appended), so the failure survives in the trace.
     expect(trace).toHaveLength(2);
     expect(trace[0]).toEqual({ toolName: 'editPageText', input: { id: 'p1' } });
     expect(trace[1]).toEqual({
       toolName: 'editPageText',
       error: 'page is locked',
+      kind: 'thrown',
     });
   });
 
-  it('truncates a very long tool-error message to the tool-output limit', () => {
+  it('marks an interrupted call (no result, no throw) with kind "interrupted"', () => {
+    const trace = serializeSteps([
+      {
+        toolCalls: [
+          { toolCallId: 'c1', toolName: 'createComment', input: { x: 1 } },
+        ],
+        toolResults: [],
+        content: [],
+      },
+    ]) as Array<Record<string, unknown>>;
+    expect(trace).toHaveLength(2);
+    expect(trace[1]).toEqual({
+      toolName: 'createComment',
+      error: 'Tool call did not complete.',
+      kind: 'interrupted',
+    });
+    // Structurally distinct from a thrown hard-fail so it never inflates an
+    // error-rate scan.
+    expect((trace[1] as { kind: string }).kind).not.toBe('thrown');
+  });
+
+  it('truncates a very long thrown-error message to the tool-output limit', () => {
     const long = 'x'.repeat(5000);
     const trace = serializeSteps([
       {
-        toolCalls: [{ toolName: 'editPageText', input: {} }],
+        toolCalls: [{ toolCallId: 'c1', toolName: 'editPageText', input: {} }],
         toolResults: [],
-        content: [{ type: 'tool-error', toolName: 'editPageText', error: long }],
+        content: [
+          {
+            type: 'tool-error',
+            toolCallId: 'c1',
+            toolName: 'editPageText',
+            error: long,
+          },
+        ],
       },
     ]) as Array<Record<string, unknown>>;
     const errorText = trace[1].error as string;
-    // Truncated (not the full 5000 chars) and carries the omission marker.
     expect(errorText.length).toBeLessThan(long.length);
     expect(errorText).toContain('chars omitted');
   });
+
+  it('pairs parallel calls in one step with their outcomes by id', () => {
+    const trace = serializeSteps([
+      {
+        toolCalls: [
+          { toolCallId: 'a', toolName: 'getPage', input: {} },
+          { toolCallId: 'b', toolName: 'searchPages', input: {} },
+        ],
+        toolResults: [{ toolCallId: 'b', toolName: 'searchPages' }],
+        content: [
+          { type: 'tool-error', toolCallId: 'a', toolName: 'getPage', error: 'nope' },
+        ],
+      },
+    ]) as Array<Record<string, unknown>>;
+    // call a, outcome a (thrown), call b, outcome b (ok)
+    expect(trace).toHaveLength(4);
+    expect(trace[1]).toEqual({ toolName: 'getPage', error: 'nope', kind: 'thrown' });
+    expect(trace[3]).toEqual({ toolName: 'searchPages', ok: true });
+  });
+});
+
+// #490: every assistant row flushAssistant writes carries the v2 era marker so a
+// dual-shape diagnostic query can branch on the trace shape without inspecting it.
+describe('toolTraceVersion era marker (#490)', () => {
+  it('stamps metadata.toolTraceVersion = 2 on every flushed row', () => {
+    const seed = flushAssistant([], '', 'streaming');
+    expect(seed.metadata.toolTraceVersion).toBe(2);
+    const done = flushAssistant(
+      [
+        {
+          text: 'ok',
+          toolCalls: [{ toolCallId: 'c1', toolName: 'getPage', input: {} }],
+          toolResults: [{ toolCallId: 'c1', toolName: 'getPage' }],
+        },
+      ],
+      '',
+      'completed',
+      { finishReason: 'stop' },
+    );
+    expect(done.metadata.toolTraceVersion).toBe(2);
+  });
+});
+
+// #490 replay-budget signal helpers over persisted history.
+describe('lastAssistantContextTokens', () => {
+  const row = (
+    role: string,
+    metadata: Record<string, unknown> | null,
+  ): AiChatMessage => ({ role, metadata }) as unknown as AiChatMessage;
+
+  it('reads the most recent assistant turn contextTokens (provider fact)', () => {
+    const hist = [
+      row('user', null),
+      row('assistant', { contextTokens: 12000 }),
+      row('user', null),
+      row('assistant', { contextTokens: 41000 }),
+    ];
+    expect(lastAssistantContextTokens(hist)).toBe(41000);
+  });
+
+  it('returns undefined when the last assistant turn recorded no usage', () => {
+    const hist = [row('assistant', { error: 'boom' }), row('user', null)];
+    expect(lastAssistantContextTokens(hist)).toBeUndefined();
+    expect(lastAssistantContextTokens([])).toBeUndefined();
+  });
+});
+
+// #490 snapshotOpenPage fast-path: skip the full Markdown export + upsert when a
+// snapshot already exists at the page's CURRENT version (same updated_at instant).
+describe('snapshotOpenPage fast-path (#490)', () => {
+  function makeSvc(existingSnapshot: unknown, pageUpdatedAt: Date) {
+    const exportPageMarkdown = jest.fn(async () => '# md');
+    const upsert = jest.fn(async () => undefined);
+    const findByChatPage = jest.fn(async () => existingSnapshot);
+    const pageRepo = {
+      findById: jest.fn(async () => ({
+        id: 'p1',
+        workspaceId: 'ws1',
+        updatedAt: pageUpdatedAt,
+      })),
+    };
+    const svc = new AiChatService(
+      {} as never, // ai
+      {} as never, // aiChatRepo
+      {} as never, // aiChatMessageRepo
+      { findByChatPage, upsert } as never, // aiChatPageSnapshotRepo
+      {} as never, // aiSettings
+      { exportPageMarkdown } as never, // tools
+      {} as never, // mcpClients
+      {} as never, // aiAgentRoleRepo
+      pageRepo as never, // pageRepo
+      {} as never, // pageAccess
+      {} as never, // environment
+    );
+    return { svc, exportPageMarkdown, upsert, findByChatPage };
+  }
+
+  const args = () =>
+    [
+      'chat1',
+      'p1',
+      { id: 'ws1' } as never,
+      { id: 'u1' } as never,
+      'sess',
+    ] as const;
+
+  it('skips export + upsert when the snapshot is already at this page version', async () => {
+    const t = new Date('2026-07-07T10:00:00Z');
+    const { svc, exportPageMarkdown, upsert } = makeSvc(
+      { pageUpdatedAt: t, contentMd: '# md' },
+      t,
+    );
+    await (svc as unknown as { snapshotOpenPage: (...a: unknown[]) => Promise<void> })
+      .snapshotOpenPage(...args());
+    expect(exportPageMarkdown).not.toHaveBeenCalled();
+    expect(upsert).not.toHaveBeenCalled();
+  });
+
+  it('exports + upserts when the page advanced since the snapshot', async () => {
+    const { svc, exportPageMarkdown, upsert } = makeSvc(
+      { pageUpdatedAt: new Date('2026-07-07T10:00:00Z'), contentMd: 'old' },
+      new Date('2026-07-07T11:00:00Z'),
+    );
+    await (svc as unknown as { snapshotOpenPage: (...a: unknown[]) => Promise<void> })
+      .snapshotOpenPage(...args());
+    expect(exportPageMarkdown).toHaveBeenCalledTimes(1);
+    expect(upsert).toHaveBeenCalledTimes(1);
+  });
+
+  it('seeds (exports + upserts) on the first turn (no snapshot yet)', async () => {
+    const { svc, exportPageMarkdown, upsert } = makeSvc(
+      undefined,
+      new Date('2026-07-07T10:00:00Z'),
+    );
+    await (svc as unknown as { snapshotOpenPage: (...a: unknown[]) => Promise<void> })
+      .snapshotOpenPage(...args());
+    expect(exportPageMarkdown).toHaveBeenCalledTimes(1);
+    expect(upsert).toHaveBeenCalledTimes(1);
+  });
+});
+
+// #490 deferred-tool activation persisted across turns.
+describe('seedActivatedTools', () => {
+  const valid = new Set(['Search_web', 'getPageJson', 'diffPageVersions']);
+
+  it('seeds from persisted metadata, intersected with current valid names', () => {
+    expect(
+      seedActivatedTools(
+        { activatedTools: ['Search_web', 'getPageJson'] },
+        valid,
+      ),
+    ).toEqual(['Search_web', 'getPageJson']);
+  });
+
+  it('drops a stored tool that is no longer valid (allowlist/role changed)', () => {
+    // 'Habr_publish' was activated before but is not in the current allowlist.
+    expect(
+      seedActivatedTools({ activatedTools: ['Search_web', 'Habr_publish'] }, valid),
+    ).toEqual(['Search_web']);
+  });
+
+  it('is empty/robust for missing, non-array, or unknown-shaped metadata', () => {
+    expect(seedActivatedTools(undefined, valid)).toEqual([]);
+    expect(seedActivatedTools({}, valid)).toEqual([]);
+    expect(seedActivatedTools({ activatedTools: 'nope' }, valid)).toEqual([]);
+    expect(
+      seedActivatedTools({ activatedTools: [1, 'getPageJson', null] }, valid),
+    ).toEqual(['getPageJson']);
+  });
+
+  it('de-duplicates stored names', () => {
+    expect(
+      seedActivatedTools(
+        { activatedTools: ['getPageJson', 'getPageJson'] },
+        valid,
+      ),
+    ).toEqual(['getPageJson']);
+  });
+});
+
+describe('lastAssistantReplayOverflow', () => {
+  const row = (
+    role: string,
+    metadata: Record<string, unknown> | null,
+  ): AiChatMessage => ({ role, metadata }) as unknown as AiChatMessage;
+
+  it('is true only when the LAST assistant turn overflowed', () => {
+    expect(
+      lastAssistantReplayOverflow([
+        row('assistant', { replayOverflow: true }),
+        row('user', null),
+      ]),
+    ).toBe(true);
+    // A recovered (later, non-overflow) assistant turn clears it.
+    expect(
+      lastAssistantReplayOverflow([
+        row('assistant', { replayOverflow: true }),
+        row('user', null),
+        row('assistant', { contextTokens: 5 }),
+      ]),
+    ).toBe(false);
+    expect(lastAssistantReplayOverflow([])).toBe(false);
+  });
+
+  // #490 reactive recovery: a prior turn stamped `replayOverflow` must make the
+  // NEXT turn's effective budget the AGGRESSIVE 0.5x cut — that harder trim is
+  // what un-bricks a chat that just 400'd on the context window. This exercises
+  // the exact wiring the service uses: read the stamp, then scale the threshold.
+  it('#490: a prior replayOverflow drives the next turn to the 0.5x aggressive budget', () => {
+    const history = [
+      row('assistant', { replayOverflow: true }),
+      row('user', null),
+    ];
+    const priorOverflowed = lastAssistantReplayOverflow(history);
+    expect(priorOverflowed).toBe(true);
+    // Base budget 100k -> aggressive recovery halves it to 50k this turn.
+    expect(resolveEffectiveReplayThreshold(100_000, priorOverflowed)).toBe(50_000);
+    // Odd base floors, not rounds.
+    expect(resolveEffectiveReplayThreshold(99_999, true)).toBe(49_999);
+    // No prior overflow -> the base budget is used verbatim (no aggressive cut).
+    expect(resolveEffectiveReplayThreshold(100_000, false)).toBe(100_000);
+    // An explicit off-switch (null) is never overridden, even on recovery.
+    expect(resolveEffectiveReplayThreshold(null, true)).toBeNull();
+  });
 });
 
 describe('rowToUiMessage', () => {
@@ -618,6 +930,23 @@ describe('flushAssistant', () => {
     expect(flushed.metadata.error).toBe('boom');
   });
 
+  // #490 observability: the replay budgeter's decision is stamped on the turn.
+  it('records replayTrimmedToTokens + replayOverflow when provided', () => {
+    const f = flushAssistant([], '', 'error', {
+      error: 'ctx',
+      replayTrimmedToTokens: 42_000,
+      replayOverflow: true,
+    });
+    expect(f.metadata.replayTrimmedToTokens).toBe(42_000);
+    expect(f.metadata.replayOverflow).toBe(true);
+  });
+
+  it('omits the replay metadata when not provided', () => {
+    const f = flushAssistant([], '', 'completed', { finishReason: 'stop' });
+    expect('replayTrimmedToTokens' in f.metadata).toBe(false);
+    expect('replayOverflow' in f.metadata).toBe(false);
+  });
+
   // #274 observability: the page-change diff the agent saw this turn is persisted
   // to metadata.pageChanged when a non-empty diff was injected, and omitted when
   // the diff is empty/whitespace or the arg is not supplied.

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

@@ -55,6 +55,12 @@ import {
   type SelectionContext,
 } from './tools/current-page.util';
 import { roleModelOverride } from './roles/role-model-config';
+import {
+  resolveReplayBudget,
+  resolveEffectiveReplayThreshold,
+  isContextOverflowError,
+  trimHistoryForReplay,
+} from './history-budget';
 import {
   startSseHeartbeat,
   stripStreamingHopByHopHeaders,
@@ -117,9 +123,14 @@ const FINAL_STEP_NUDGE =
 // NO text at all (#444, mitigates the "empty turn" the lockdown used to prevent
 // when the toggle is OFF). Makes the exhausted-without-answer state explicit to
 // the user and, on replay, to the model on the next turn.
+// The persisted content is the app's base locale (en-US) — which is ALSO the
+// i18n key the client localizes through `t()` — instead of a hardcoded Russian
+// string (it used to render Russian for every locale, and fed Russian back to
+// the model on replay). Keep it a plain, model-readable English sentence so the
+// next turn's replay reads cleanly; the client resolves the locale.
 const STEP_LIMIT_NO_ANSWER_MARKER =
-  '(Достигнут лимит шагов — итоговый ответ не сформулирован; работа могла ' +
-  'остаться незавершённой. Напишите «продолжай», чтобы агент продолжил.)';
+  '(Step limit reached — no final answer was produced; the work may be ' +
+  'unfinished. Reply "continue" to let the agent carry on.)';
 
 // Reason recorded in ai_chat_runs.error / the assistant row when the token-
 // degeneration detector (#444) aborts a run. Distinct from a user Stop (no error)
@@ -127,6 +138,15 @@ const STEP_LIMIT_NO_ANSWER_MARKER =
 const OUTPUT_DEGENERATION_ERROR =
   'Output degeneration detected (repeated token loop)';
 
+// Prefix recorded on the assistant row when the provider rejected the turn for
+// CONTEXT OVERFLOW (#490): the replayed history exceeded the model's window. The
+// row is ALSO stamped `metadata.replayOverflow` so the NEXT turn's budgeter trims
+// aggressively (the reactive recovery — the overflowing turn had no usage signal
+// to trigger preventive trimming, so the classified 400 is what un-bricks it).
+export const CONTEXT_OVERFLOW_ERROR_PREFIX =
+  'Диалог превысил контекстное окно модели; история будет агрессивно ' +
+  'сокращена на следующем ходу.';
+
 /**
  * Compute the step-budget warning text (#444), or '' when this step is outside
  * the warning band. The warning fires on steps
@@ -882,6 +902,21 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       const freshPage = await this.pageRepo.findById(pageId);
       // Page deleted during the turn (or somehow foreign) => don't write.
       if (!freshPage || freshPage.workspaceId !== workspace.id) return;
+      // Fast-path (#490): if a snapshot already exists at THIS page version
+      // (same updated_at instant), its content is already current — skip the full
+      // Markdown export + upsert entirely. A turn that did NOT touch the open page
+      // (the common case) thus does no snapshot work. This mirrors the read-side
+      // fast path in detectPageChange (sameInstant): both trust that a page edit
+      // bumps updated_at. When the agent (or a human) DID edit the page this turn,
+      // updated_at advanced, so this does not match and we re-export as before.
+      const existing = await this.aiChatPageSnapshotRepo.findByChatPage(
+        chatId,
+        pageId,
+        workspace.id,
+      );
+      if (existing && sameInstant(existing.pageUpdatedAt, freshPage.updatedAt)) {
+        return;
+      }
       const currentMd = await this.tools.exportPageMarkdown(
         user,
         sessionId,
@@ -921,10 +956,17 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
     // supplied or the supplied one does not belong to this workspace.
     let isNewChat = false;
     let chatId = body.chatId;
+    // Persisted chat-level metadata bag (#490): read once here so the deferred-tool
+    // activation set can be seeded from the previous turn. Undefined for a new chat.
+    let chatMetadata: Record<string, unknown> | undefined;
     if (chatId) {
       const existing = await this.aiChatRepo.findById(chatId, workspace.id);
       if (!existing) {
         chatId = undefined;
+      } else {
+        chatMetadata = (existing.metadata ?? undefined) as
+          | Record<string, unknown>
+          | undefined;
       }
     }
     // The open page the client sent is attacker-controllable — BOTH its id and
@@ -1086,7 +1128,7 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       // per-row conversion and degraded to plain text with a "[tool context
       // omitted]" marker rather than 500-ing the whole turn (silent loss of tool
       // context is not acceptable — the model must see the truncation).
-      const messages = await convertHistoryResilient(uiMessages, (index, err) =>
+      let messages = await convertHistoryResilient(uiMessages, (index, err) =>
         this.logger.warn(
           `Degraded unconvertible history row ${index} on chat ${chatId} to text: ${
             err instanceof Error ? err.message : 'unknown error'
@@ -1135,6 +1177,56 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       // Here we only need the admin-configured system prompt.
       const resolved = await this.aiSettings.resolve(workspace.id);
 
+      // History-replay token budget (#490). The full conversation is replayed to
+      // the provider every turn, so a long chat eventually 400s on the context
+      // window — forever. Bound the REPLAYED history (never the persisted rows).
+      // PRIMARY signal is the provider's own fact: the last turn's contextTokens.
+      const replayBudget = resolveReplayBudget(resolved?.chatContextWindowRaw);
+      if (replayBudget.usedDefault) {
+        // The default fires precisely for installs with NO configured window —
+        // the ones that hit terminal overflow. Warn so it is observable.
+        this.logger.warn(
+          `AI chat (chat ${chatId}): no chatContextWindow configured; ` +
+            `applying the default replay budget (${replayBudget.thresholdTokens} tokens).`,
+        );
+      }
+      // Last turn's provider-reported context size (authoritative when present).
+      const priorContextTokens = lastAssistantContextTokens(oldHistory);
+      // Reactive recovery (#490): if the LAST turn was rejected for context
+      // overflow (stamped by onError), trim AGGRESSIVELY this turn — the
+      // overflowing turn produced no usage signal, so a normal-threshold trim may
+      // not shrink enough to fit. This is what un-bricks a chat that just 400'd.
+      const priorOverflowed = lastAssistantReplayOverflow(oldHistory);
+      const effectiveThreshold = resolveEffectiveReplayThreshold(
+        replayBudget.thresholdTokens,
+        priorOverflowed,
+      );
+      if (priorOverflowed) {
+        this.logger.warn(
+          `AI chat (chat ${chatId}): previous turn hit context overflow; ` +
+            `applying aggressive replay budget (${effectiveThreshold} tokens).`,
+        );
+      }
+      const preTrim = trimHistoryForReplay(
+        messages,
+        effectiveThreshold,
+        // A prior OVERFLOW means the provider count is stale/absent — force the
+        // char-estimate path by ignoring priorContextTokens on recovery.
+        priorOverflowed ? undefined : priorContextTokens,
+      );
+      messages = preTrim.messages;
+      // Observability (#490): record the budgeter's decision on the turn so the UI
+      // can surface "replay truncated at N tokens". Threaded into flushAssistant.
+      let replayTrimmedToTokens: number | undefined = preTrim.trimmed
+        ? preTrim.estimatedTokens
+        : undefined;
+      if (preTrim.trimmed) {
+        this.logger.log(
+          `AI chat (chat ${chatId}): replay history trimmed to ~${preTrim.estimatedTokens} ` +
+            `tokens (budget ${replayBudget.thresholdTokens}).`,
+        );
+      }
+
       // 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
@@ -1326,10 +1418,19 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       //    tools + ALL external MCP tools), computed from the ACTUAL toolset so an
       //    external tool is loadable by its namespaced name. loadTools rejects any
       //    name outside this set.
-      const activatedTools = new Set<string>();
       const validDeferredNames = new Set<string>(
         Object.keys(baseTools).filter((k) => !CORE_TOOL_SET.has(k)),
       );
+      // #490: seed the activation set from the chat's PERSISTED set so the model
+      // does not re-run loadTools every turn to re-activate the same tools. Only
+      // when deferred loading is enabled, and ALWAYS intersected with the CURRENT
+      // valid deferred names — an allowlist/role change must never resurrect a tool
+      // that no longer exists (prepareAgentStep would get a phantom active name).
+      const activatedTools = new Set<string>(
+        deferredEnabled
+          ? seedActivatedTools(chatMetadata, validDeferredNames)
+          : [],
+      );
       // Add the loadTools meta-tool ONLY when the feature is enabled; when off the
       // toolset and behavior are exactly as before.
       const tools = deferredEnabled
@@ -1339,6 +1440,39 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
           }
         : baseTools;
 
+      // #490: persist the (deterministically ordered) activation set back onto the
+      // chat metadata at turn end, so the NEXT turn seeds from it. Once-guarded and
+      // skipped when nothing new was activated (the set equals its seed) so an
+      // ordinary turn adds no extra write. Preserves other metadata keys.
+      let activatedToolsPersisted = false;
+      const persistActivatedTools = async (): Promise<void> => {
+        if (!deferredEnabled || activatedToolsPersisted || !chatId) return;
+        activatedToolsPersisted = true;
+        const current = [...activatedTools].sort();
+        const seeded = seedActivatedTools(chatMetadata, validDeferredNames).sort();
+        if (current.length === 0 || current.join('') === seeded.join('')) {
+          return; // nothing new activated -> no write
+        }
+        try {
+          await this.aiChatRepo.update(
+            chatId,
+            {
+              metadata: {
+                ...(chatMetadata ?? {}),
+                activatedTools: current,
+              },
+            } as never,
+            workspace.id,
+          );
+        } catch (err) {
+          this.logger.warn(
+            `Failed to persist activated tools (chat ${chatId}): ${
+              err instanceof Error ? err.message : 'unknown error'
+            }`,
+          );
+        }
+      };
+
       // Accumulate the turn's streamed output so a provider error / disconnect can
       // persist the PARTIAL answer the user already saw — the SDK's onError/onAbort
       // callbacks don't hand us the in-progress text. `capturedSteps` holds finished
@@ -1347,6 +1481,11 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       const capturedSteps: StepLike[] = [];
       let inProgressText = '';
 
+      // Per-turn step->parts memo (#490): shared across every flushAssistant call
+      // this turn so each finished step's (large) output is JSON-stringified ONCE,
+      // not re-stringified on every subsequent onStepFinish flush (was O(N²)).
+      const partsCache: StepPartsCache = new WeakMap();
+
       // Token-degeneration guard (#444). When the final-step lockdown is OFF, a
       // runaway repetition loop (the 255KB "loadTools." incident) is aborted via
       // this internal controller, unioned with the run/socket signal below. The
@@ -1416,7 +1555,10 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
           await this.aiChatMessageRepo.update(
             assistantId,
             workspace.id,
-            flushAssistant(capturedSteps, '', 'streaming', { pageChanged }),
+            flushAssistant(capturedSteps, '', 'streaming', {
+              pageChanged,
+              partsCache,
+            }),
             { onlyIfStreaming: true },
           );
         } catch (err) {
@@ -1514,6 +1656,13 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
           system,
           messages,
           tools,
+          // Pin the AI SDK per-request retry budget explicitly instead of relying
+          // on its default (which is also 2). Connection arithmetic per turn:
+          // (1 + maxRetries=2) × (1 + AI_STREAM_PRE_RESPONSE_RETRIES) network
+          // connects worst-case — the two retry layers compose, so making the SDK
+          // side explicit keeps that ceiling visible and pinned against SDK-default
+          // drift.
+          maxRetries: 2,
           // 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
@@ -1649,6 +1798,8 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
                 // closure scope here). Omitted/0 = no limit.
                 maxContextTokens: resolved?.chatContextWindow,
                 pageChanged,
+                partsCache,
+                replayTrimmedToTokens,
               }),
             );
             // #184/#487: the RUN is finalized ALWAYS (never gated on the message).
@@ -1673,6 +1824,8 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             // own edits are baked in — and this also SEEDS the snapshot on the first
             // turn. Runs once across every terminal path (see snapshotTurnEnd).
             await snapshotTurnEnd();
+            // #490: persist the deferred-tool activation set for the next turn.
+            await persistActivatedTools();
 
             // 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
@@ -1696,7 +1849,16 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             // 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));
+            // #490 reactive branch: classify a CONTEXT-OVERFLOW rejection (the
+            // replayed history exceeded the model window). The overflowing turn had
+            // no prior usage to trigger preventive trimming, so we record a clear,
+            // distinguishable cause AND stamp the row so the NEXT turn's budgeter
+            // trims aggressively — the reactive recovery that un-bricks the chat.
+            const overflow = isContextOverflowError(error);
+            const providerError = describeProviderError(error, String(error));
+            const errorText = overflow
+              ? `${CONTEXT_OVERFLOW_ERROR_PREFIX} (${providerError})`
+              : providerError;
             this.logger.error(`AI chat stream error: ${errorText}`, e?.stack);
             // DIAGNOSTIC (Safari stream-drop investigation) — temporary: timing of
             // an error-terminated stream.
@@ -1714,6 +1876,9 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
               flushAssistant(capturedSteps, inProgressText, 'error', {
                 error: errorText,
                 pageChanged,
+                partsCache,
+                replayTrimmedToTokens,
+                replayOverflow: overflow || undefined,
               }),
             );
             // #184: settle the RUN as failed, carrying the provider/transport cause.
@@ -1723,6 +1888,8 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             // committed before the error must be baked into the snapshot, or the
             // next turn would mis-report it as a user edit.
             await snapshotTurnEnd();
+            // #490: persist the deferred-tool activation set for the next turn.
+            await persistActivatedTools();
           },
           onAbort: async ({ steps }) => {
             // #444: distinguish a degeneration abort (our internal controller) from
@@ -1737,6 +1904,7 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
                 flushAssistant(capturedSteps, truncated, 'error', {
                   error: OUTPUT_DEGENERATION_ERROR,
                   pageChanged,
+                  partsCache,
                 }),
               );
               if (runId)
@@ -1747,6 +1915,8 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
                 );
               await closeExternalClients();
               await snapshotTurnEnd();
+              // #490: persist the deferred-tool activation set for the next turn.
+              await persistActivatedTools();
               return;
             }
             const partialChars =
@@ -1771,6 +1941,7 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             await finalizeAssistant(
               flushAssistant(capturedSteps, inProgressText, 'aborted', {
                 pageChanged,
+                partsCache,
               }),
             );
             // #184: settle the RUN as aborted (an explicit user stop reached the
@@ -1781,6 +1952,8 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             // committed before the client disconnect / stop() must be baked into the
             // snapshot, or the next turn would mis-report it as a user edit.
             await snapshotTurnEnd();
+            // #490: persist the deferred-tool activation set for the next turn.
+            await persistActivatedTools();
           },
         });
 
@@ -2091,6 +2264,70 @@ export function chatStreamMetadata(
   return undefined;
 }
 
+/**
+ * The provider-reported context size of the most recent assistant turn, read from
+ * its persisted `metadata.contextTokens` (#490 replay budgeter's PRIMARY signal —
+ * the provider's own fact, not an estimate). Returns undefined for a chat with no
+ * assistant turn yet, or one whose last turn recorded no usage (e.g. it errored),
+ * in which case the budgeter falls back to the char-estimate.
+ */
+export function lastAssistantContextTokens(
+  history: ReadonlyArray<AiChatMessage>,
+): number | undefined {
+  for (let i = history.length - 1; i >= 0; i--) {
+    const row = history[i];
+    if (row.role !== 'assistant') continue;
+    const meta = (row.metadata ?? {}) as { contextTokens?: unknown };
+    const n = meta.contextTokens;
+    return typeof n === 'number' && Number.isFinite(n) && n > 0 ? n : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Seed the per-turn deferred-tool activation set from a chat's persisted metadata
+ * (#490), INTERSECTED with the current valid deferred names. Persisting the set
+ * across turns saves the model re-running loadTools every turn to re-activate the
+ * same tools; intersecting on load means a changed allowlist / role can never
+ * resurrect a tool that no longer exists (which would hand prepareAgentStep a
+ * phantom active name). Tolerant of any stored shape — a non-array is ignored.
+ */
+export function seedActivatedTools(
+  metadata: Record<string, unknown> | undefined,
+  validDeferredNames: ReadonlySet<string>,
+): string[] {
+  const stored = metadata?.activatedTools;
+  if (!Array.isArray(stored)) return [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const name of stored) {
+    if (typeof name === 'string' && validDeferredNames.has(name) && !seen.has(name)) {
+      seen.add(name);
+      out.push(name);
+    }
+  }
+  return out;
+}
+
+/**
+ * Whether the most recent assistant turn was rejected for CONTEXT OVERFLOW
+ * (#490): its row carries `metadata.replayOverflow` (stamped by the stream's
+ * onError). The next turn's budgeter reads this to trim aggressively — the
+ * reactive recovery. Only the LAST assistant turn matters (an older overflow was
+ * already recovered), so we stop at the first assistant row scanning backwards.
+ */
+export function lastAssistantReplayOverflow(
+  history: ReadonlyArray<AiChatMessage>,
+): boolean {
+  for (let i = history.length - 1; i >= 0; i--) {
+    const row = history[i];
+    if (row.role !== 'assistant') continue;
+    const meta = (row.metadata ?? {}) as { replayOverflow?: unknown };
+    return meta.replayOverflow === true;
+  }
+  return false;
+}
+
 /** The last message with role 'user' from a useChat payload, if any. */
 function lastUserMessage(
   messages: UIMessage[] | undefined,
@@ -2152,6 +2389,15 @@ export function sanitizeUserParts(
 /** Marker for a history row whose tool parts could not be replayed (#489). */
 export const TOOL_CONTEXT_OMITTED_MARKER = '[tool context omitted]';
 
+/**
+ * Synthetic error text for a tool call that neither returned a result nor threw
+ * a `tool-error` — i.e. it was interrupted mid-step (an abort / server restart).
+ * Shared by `assistantParts` (the replayed `output-error` part) and
+ * `serializeSteps` (the `{ kind: 'interrupted' }` trace element) so the replay
+ * text and the trace stay in lockstep (#490).
+ */
+export const TOOL_CALL_INCOMPLETE_TEXT = 'Tool call did not complete.';
+
 /**
  * Convert persisted UI history to model messages, tolerating a single poisoned
  * row (#489). `convertToModelMessages` over the WHOLE array throws if ANY row is
@@ -2359,71 +2605,97 @@ function normalizeToolError(error: unknown): string {
  */
 // Exported only so the unit tests can import these pure helpers; exporting
 // them does not change runtime behavior.
+/**
+ * Per-turn memo for {@link assistantParts}: a step's rebuilt parts keyed by the
+ * step OBJECT's identity (#490). A finished step in `capturedSteps` keeps a stable
+ * reference across every mid-stream flush, and `compactToolOutput` inside it does a
+ * `JSON.stringify` of the whole (often 50–200 KB) output — so without a memo each
+ * `onStepFinish` re-stringifies EVERY prior step's output (O(N²) stringify over a
+ * turn). Keyed by step identity => one stringify per step per turn. WeakMap so a
+ * turn's steps are GC'd with the turn.
+ */
+export type StepPartsCache = WeakMap<object, Array<Record<string, unknown>>>;
+
+/** Build the parts for ONE step (text + a part per tool call). Pure. */
+function buildStepParts(step: StepLike): Array<Record<string, unknown>> {
+  const parts: Array<Record<string, unknown>> = [];
+  if (step.text) {
+    parts.push({ type: 'text', text: step.text });
+  }
+  // Index this step's results by tool call id to pair calls with outputs.
+  const resultsById = new Map<string, unknown>();
+  for (const r of step.toolResults ?? []) {
+    if (r.toolCallId) resultsById.set(r.toolCallId, r.output);
+  }
+  // Index this step's THROWN tool failures (ai@6 `tool-error` content parts)
+  // by tool call id, so a call that failed replays with its real error text.
+  const errorsById = new Map<string, unknown>();
+  for (const part of step.content ?? []) {
+    if (part.type === 'tool-error' && part.toolCallId) {
+      errorsById.set(part.toolCallId, part.error);
+    }
+  }
+  for (const call of step.toolCalls ?? []) {
+    if (!call.toolName || !call.toolCallId) continue;
+    const hasResult = resultsById.has(call.toolCallId);
+    if (hasResult) {
+      // output-available: the tool returned; the next turn replays its result.
+      parts.push({
+        type: `tool-${call.toolName}`,
+        toolCallId: call.toolCallId,
+        state: 'output-available',
+        input: call.input,
+        output: compactToolOutput(resultsById.get(call.toolCallId)),
+      });
+    } else if (errorsById.has(call.toolCallId)) {
+      // The tool THREW: replay the REAL error so the model on the next turn
+      // knows WHY the call failed (and does not blindly repeat it). An
+      // output-error round-trips through convertToModelMessages as a balanced
+      // tool-call + tool-result, keeping the rebuilt history valid.
+      parts.push({
+        type: `tool-${call.toolName}`,
+        toolCallId: call.toolCallId,
+        state: 'output-error',
+        input: call.input,
+        errorText: normalizeToolError(errorsById.get(call.toolCallId)),
+      });
+    } else {
+      // No paired result AND no tool-error (e.g. aborted mid-step). Persisting
+      // a bare tool-call (input-available) would replay as an unpaired call and
+      // throw MissingToolResultsError on the next turn (convertToModelMessages
+      // emits no tool-result for it). Emit a SYNTHETIC paired result instead:
+      // an output-error round-trips through convertToModelMessages as a
+      // balanced tool-call + tool-result, keeping the rebuilt history valid.
+      parts.push({
+        type: `tool-${call.toolName}`,
+        toolCallId: call.toolCallId,
+        state: 'output-error',
+        input: call.input,
+        errorText: TOOL_CALL_INCOMPLETE_TEXT,
+      });
+    }
+  }
+  return parts;
+}
+
 export function assistantParts(
   steps: ReadonlyArray<StepLike> | undefined,
   fallbackText: string,
+  cache?: StepPartsCache,
 ): UIMessage['parts'] {
   const parts: Array<Record<string, unknown>> = [];
-  let sawText = false;
   for (const step of steps ?? []) {
-    if (step.text) {
-      parts.push({ type: 'text', text: step.text });
-      sawText = true;
-    }
-    // Index this step's results by tool call id to pair calls with outputs.
-    const resultsById = new Map<string, unknown>();
-    for (const r of step.toolResults ?? []) {
-      if (r.toolCallId) resultsById.set(r.toolCallId, r.output);
-    }
-    // Index this step's THROWN tool failures (ai@6 `tool-error` content parts)
-    // by tool call id, so a call that failed replays with its real error text.
-    const errorsById = new Map<string, unknown>();
-    for (const part of step.content ?? []) {
-      if (part.type === 'tool-error' && part.toolCallId) {
-        errorsById.set(part.toolCallId, part.error);
-      }
-    }
-    for (const call of step.toolCalls ?? []) {
-      if (!call.toolName || !call.toolCallId) continue;
-      const hasResult = resultsById.has(call.toolCallId);
-      if (hasResult) {
-        // output-available: the tool returned; the next turn replays its result.
-        parts.push({
-          type: `tool-${call.toolName}`,
-          toolCallId: call.toolCallId,
-          state: 'output-available',
-          input: call.input,
-          output: compactToolOutput(resultsById.get(call.toolCallId)),
-        });
-      } else if (errorsById.has(call.toolCallId)) {
-        // The tool THREW: replay the REAL error so the model on the next turn
-        // knows WHY the call failed (and does not blindly repeat it). An
-        // output-error round-trips through convertToModelMessages as a balanced
-        // tool-call + tool-result, keeping the rebuilt history valid.
-        parts.push({
-          type: `tool-${call.toolName}`,
-          toolCallId: call.toolCallId,
-          state: 'output-error',
-          input: call.input,
-          errorText: normalizeToolError(errorsById.get(call.toolCallId)),
-        });
-      } else {
-        // No paired result AND no tool-error (e.g. aborted mid-step). Persisting
-        // a bare tool-call (input-available) would replay as an unpaired call and
-        // throw MissingToolResultsError on the next turn (convertToModelMessages
-        // emits no tool-result for it). Emit a SYNTHETIC paired result instead:
-        // an output-error round-trips through convertToModelMessages as a
-        // balanced tool-call + tool-result, keeping the rebuilt history valid.
-        parts.push({
-          type: `tool-${call.toolName}`,
-          toolCallId: call.toolCallId,
-          state: 'output-error',
-          input: call.input,
-          errorText: 'Tool call did not complete.',
-        });
-      }
+    // Memoize per step object (#490): a finished step is immutable and keeps its
+    // reference across flushes, so its parts (and the costly output stringify) are
+    // built exactly once per turn. A cache miss (or no cache) just rebuilds.
+    let stepParts = cache?.get(step as object);
+    if (!stepParts) {
+      stepParts = buildStepParts(step);
+      cache?.set(step as object, stepParts);
     }
+    parts.push(...stepParts);
   }
+  const sawText = parts.some((p) => p.type === 'text');
   if (!sawText && fallbackText) {
     // No per-step text (e.g. a single final block): append the final text after
     // any tool parts so the natural call -> result -> answer order is preserved.
@@ -2586,6 +2858,16 @@ export function flushAssistant(
     maxContextTokens?: number;
     error?: string;
     pageChanged?: { title: string; diff: string } | null;
+    // Per-turn step->parts memo (#490): pass the SAME cache on every flush of a
+    // turn so each finished step's output is stringified once, not once per flush.
+    partsCache?: StepPartsCache;
+    // #490 observability: when the replay budgeter trimmed this turn's history,
+    // the (estimated) token size it trimmed to — the UI can show "replay truncated
+    // at N tokens". Omitted when nothing was trimmed.
+    replayTrimmedToTokens?: number;
+    // #490 reactive branch: set when the provider rejected this turn for context
+    // overflow. Stamped into metadata so the NEXT turn's budgeter trims aggressively.
+    replayOverflow?: boolean;
   },
 ): AssistantFlush {
   const finished = capturedSteps ?? [];
@@ -2595,13 +2877,20 @@ export function flushAssistant(
   // in-progress step's text (the partial answer cut off by an error/abort, or
   // simply not yet flushed mid-stream) as the last text part so the persisted
   // parts match what streamed to the client.
-  const parts = assistantParts(finished, '') as unknown as Array<
-    Record<string, unknown>
-  >;
+  const parts = assistantParts(
+    finished,
+    '',
+    extra?.partsCache,
+  ) as unknown as Array<Record<string, unknown>>;
   if (trailing) parts.push({ type: 'text', text: trailing });
 
   const metadata: Record<string, unknown> = {
     parts: parts as unknown as UIMessage['parts'],
+    // Era marker for the `tool_calls` trace shape (#490): v2 stores outcome flags
+    // ({ ok } / { error, kind }) and NO tool output (the output lives once in
+    // `parts`). Old rows have no marker and the legacy { output } shape; a
+    // dual-shape query branches on this. Old rows are deliberately NOT migrated.
+    toolTraceVersion: 2,
   };
   // finishReason: prefer an explicit one; else derive a sensible value from the
   // terminal status (so onError/onAbort records keep their historical reason).
@@ -2617,6 +2906,9 @@ export function flushAssistant(
   if (extra?.contextTokens) metadata.contextTokens = extra.contextTokens;
   if (extra?.maxContextTokens)
     metadata.maxContextTokens = extra.maxContextTokens;
+  if (extra?.replayTrimmedToTokens)
+    metadata.replayTrimmedToTokens = extra.replayTrimmedToTokens;
+  if (extra?.replayOverflow) metadata.replayOverflow = true;
   if (extra?.error) metadata.error = extra.error;
   // Persist the page-change diff the agent saw this turn (#274 observability),
   // so history / the Markdown export can show what the user changed. Only when
@@ -2642,42 +2934,85 @@ export function flushAssistant(
 
 /**
  * Reduce SDK step objects to a compact, JSON-serializable trace for the
- * `tool_calls` column. Stores only what the UI action-log and history need —
- * never raw provider payloads or keys.
+ * `tool_calls` column — trace format **v2** (#490).
+ *
+ * v2 stores, per call, ONLY the metadata a queryable trace needs — never the
+ * tool OUTPUT. Before #490 each output was persisted TWICE: once here (compacted)
+ * and once in `metadata.parts` (via `assistantParts`), so a 50-step run with
+ * 50–200 KB outputs wrote hundreds of MB per turn (each `onStepFinish` rewrote
+ * the whole row). The parts copy is the one the model replays and the UI/Markdown
+ * export render, so the trace copy of the output was pure duplication. v2 keeps
+ * the output ONLY in parts and reduces the trace to outcome flags.
+ *
+ * Element shapes (paired per call, in order):
+ *  - `{ toolName, input }`                       — the call
+ *  - `{ toolName, ok: true }`                     — it returned a result (success)
+ *  - `{ toolName, error, kind: 'thrown' }`        — it threw a `tool-error`
+ *  - `{ toolName, error, kind: 'interrupted' }`   — no result and no throw (an
+ *      abort / server restart mid-step). `kind` is MANDATORY: without it a
+ *      synthetic "Tool call did not complete." is indistinguishable from a real
+ *      hard-fail and pollutes any error-rate scan. The distinction is STRUCTURAL
+ *      (an `errorsById` hit vs the synthetic fallback branch), NOT a per-tool
+ *      classifier — soft failures stay OUT of the trace (they live in
+ *      `metadata.parts` outputs; a per-tool mirror would persist its own bugs).
+ *
+ * Rows carry `metadata.toolTraceVersion: 2` (set by {@link flushAssistant}) so a
+ * dual-shape query can branch on the era. Old rows are NOT migrated (rewriting
+ * giant jsonb is the very WAL churn this removes); see docs/reading-ai-logs.md.
  */
 export function serializeSteps(
   steps: ReadonlyArray<{
-    toolCalls?: ReadonlyArray<{ toolName?: string; input?: unknown }>;
-    toolResults?: ReadonlyArray<{ toolName?: string; output?: unknown }>;
+    toolCalls?: ReadonlyArray<{
+      toolCallId?: string;
+      toolName?: string;
+      input?: unknown;
+    }>;
+    toolResults?: ReadonlyArray<{ toolCallId?: string; toolName?: string }>;
     content?: ReadonlyArray<{
       type?: string;
+      toolCallId?: string;
       toolName?: string;
       error?: unknown;
     }>;
   }>,
 ): unknown {
-  const calls: Array<{
-    toolName?: string;
-    input?: unknown;
-    output?: unknown;
-    error?: string;
-  }> = [];
+  const calls: Array<
+    | { toolName?: string; input?: unknown }
+    | { toolName?: string; ok: true }
+    | { toolName?: string; error: string; kind: 'thrown' | 'interrupted' }
+  > = [];
   for (const step of steps ?? []) {
+    // Index this step's results + thrown errors by tool call id, so each call is
+    // paired with its outcome (mirrors assistantParts' pairing exactly).
+    const resultIds = new Set<string>();
+    for (const r of step.toolResults ?? []) {
+      if (r.toolCallId) resultIds.add(r.toolCallId);
+    }
+    const errorsById = new Map<string, unknown>();
+    for (const part of step.content ?? []) {
+      if (part.type === 'tool-error' && part.toolCallId) {
+        errorsById.set(part.toolCallId, part.error);
+      }
+    }
     for (const call of step.toolCalls ?? []) {
       calls.push({ toolName: call.toolName, input: call.input });
-    }
-    for (const r of step.toolResults ?? []) {
-      calls.push({ toolName: r.toolName, output: compactToolOutput(r.output) });
-    }
-    // ai@6 surfaces a THROWN tool failure as a `tool-error` content part, NOT as
-    // a `toolResults` entry. Record it as its own paired element (mirroring how a
-    // successful result is appended) so the failure and its reason survive in the
-    // trace instead of leaving an orphaned call with no result.
-    for (const part of step.content ?? []) {
-      if (part.type === 'tool-error') {
+      if (call.toolCallId && resultIds.has(call.toolCallId)) {
+        // Success: the output itself lives in metadata.parts, not here.
+        calls.push({ toolName: call.toolName, ok: true });
+      } else if (call.toolCallId && errorsById.has(call.toolCallId)) {
+        // Hard fail: the tool threw. Persist the real (bounded) reason.
         calls.push({
-          toolName: part.toolName,
-          error: normalizeToolError(part.error),
+          toolName: call.toolName,
+          error: normalizeToolError(errorsById.get(call.toolCallId)),
+          kind: 'thrown',
+        });
+      } else {
+        // Neither a result nor a throw: interrupted mid-step (abort/restart).
+        // Marked structurally so it never inflates a thrown-error count.
+        calls.push({
+          toolName: call.toolName,
+          error: TOOL_CALL_INCOMPLETE_TEXT,
+          kind: 'interrupted',
         });
       }
     }

apps/server/src/core/ai-chat/ai-chat.write-volume.int-spec.ts

@@ -0,0 +1,209 @@
+import { randomBytes } from 'crypto';
+import { Client } from 'pg';
+import { flushAssistant, serializeSteps } from './ai-chat.service';
+
+/**
+ * #490 write-volume regression — an OBSERVABLE-PROPERTY test on a LIVE Postgres,
+ * not "bytes through a mock repo" (a mock measures exactly the thing that does not
+ * hurt). It drives a realistic 50-step run where each step returns a ~100 KB tool
+ * output and, at every `onStepFinish`, UPDATEs the assistant row the way the
+ * service does — then reads the REAL write volume via the `pg_current_wal_lsn()`
+ * delta around the run.
+ *
+ * The property proven: v2 stores each tool OUTPUT only in `metadata.parts`, no
+ * longer ALSO in the `tool_calls` trace. So:
+ *   1. the trace (`tool_calls`) column's write volume is now O(Σ steps) — tiny,
+ *      linear outcome flags — vs the pre-#490 O(N²) that re-persisted every prior
+ *      output on every step; and
+ *   2. the FULL-row write volume drops sharply (the duplicated output copy is gone).
+ *
+ * Connects to the local gitmost test Postgres (docker `gitmost-test-pg` on :5432);
+ * SKIPS cleanly when that DB is not reachable so it never breaks a DB-less CI.
+ */
+const CONN =
+  process.env.WAL_TEST_DATABASE_URL ??
+  'postgresql://docmost:docmost_dev_pw@localhost:5432/docmost';
+
+// A step whose tool output is ~100 KB (a page read), in the SDK StepLike shape.
+// The body is INCOMPRESSIBLE random text — a `'x'.repeat()` filler would TOAST-
+// compress to nothing and hide the real write volume (a page body does not).
+function makeStep(i: number, outputBytes = 100_000) {
+  const body = randomBytes(Math.ceil(outputBytes * 0.75)).toString('base64');
+  return {
+    text: `step ${i} reasoning`,
+    toolCalls: [{ toolCallId: `c${i}`, toolName: 'getPage', input: { id: `p${i}` } }],
+    toolResults: [
+      {
+        toolCallId: `c${i}`,
+        toolName: 'getPage',
+        output: { id: `p${i}`, title: `Page ${i}`, body },
+      },
+    ],
+  };
+}
+
+// The pre-#490 (v1) trace: outputs stored a SECOND time in `tool_calls`
+// (the duplication #490 removed). Mirrors the OLD serializeSteps shape.
+function v1Trace(steps: ReturnType<typeof makeStep>[]): unknown {
+  const calls: unknown[] = [];
+  for (const s of steps) {
+    for (const c of s.toolCalls) calls.push({ toolName: c.toolName, input: c.input });
+    for (const r of s.toolResults)
+      calls.push({ toolName: r.toolName, output: r.output });
+  }
+  return calls;
+}
+
+async function walDelta(
+  client: Client,
+  fn: () => Promise<void>,
+): Promise<number> {
+  const before = (await client.query('SELECT pg_current_wal_lsn() AS l')).rows[0]
+    .l as string;
+  await fn();
+  // NOTE: do NOT pg_switch_wal() here — a segment switch pads the LSN to the next
+  // 16 MB boundary and would swamp the actual write delta. The raw LSN advances by
+  // the bytes of WAL emitted, which is exactly what we want to measure.
+  const after = (await client.query('SELECT pg_current_wal_lsn() AS l')).rows[0]
+    .l as string;
+  return Number(
+    (await client.query('SELECT pg_wal_lsn_diff($1,$2) AS d', [after, before]))
+      .rows[0].d,
+  );
+}
+
+describe('#490 write-volume on a live Postgres (pg_current_wal_lsn delta)', () => {
+  let client: Client | undefined;
+  let available = false;
+
+  beforeAll(async () => {
+    try {
+      client = new Client(CONN);
+      await client.connect();
+      await client.query('SELECT pg_current_wal_lsn()');
+      available = true;
+    } catch {
+      available = false;
+      client = undefined;
+    }
+  });
+
+  afterAll(async () => {
+    await client?.end().catch(() => undefined);
+  });
+
+  const STEPS = 50;
+
+  it('v2 trace write volume is O(Σ steps) — a tiny fraction of the v1 duplicate', async () => {
+    if (!available || !client) {
+      console.warn('SKIP: gitmost-test-pg not reachable; skipping WAL test.');
+      return;
+    }
+    const c = client;
+    // Isolated table so we measure only the tool_calls (trace) column's writes.
+    await c.query('DROP TABLE IF EXISTS _wal_trace');
+    await c.query('CREATE TABLE _wal_trace(id int primary key, tool_calls jsonb)');
+    await c.query("INSERT INTO _wal_trace VALUES (1, '[]'::jsonb)");
+
+    const steps: ReturnType<typeof makeStep>[] = [];
+
+    // v1: each step re-persists ALL prior outputs into the trace (the O(N²) churn).
+    const v1 = await walDelta(c, async () => {
+      const acc: ReturnType<typeof makeStep>[] = [];
+      for (let i = 0; i < STEPS; i++) {
+        acc.push(makeStep(i));
+        await c.query('UPDATE _wal_trace SET tool_calls=$1 WHERE id=1', [
+          JSON.stringify(v1Trace(acc)),
+        ]);
+      }
+      steps.push(...acc);
+    });
+
+    await c.query("UPDATE _wal_trace SET tool_calls='[]'::jsonb WHERE id=1");
+
+    // v2: the REAL serializeSteps — outcome flags only, NO outputs.
+    const v2 = await walDelta(c, async () => {
+      const acc: ReturnType<typeof makeStep>[] = [];
+      for (let i = 0; i < STEPS; i++) {
+        acc.push(makeStep(i));
+        await c.query('UPDATE _wal_trace SET tool_calls=$1 WHERE id=1', [
+          JSON.stringify(serializeSteps(acc)),
+        ]);
+      }
+    });
+
+    await c.query('DROP TABLE IF EXISTS _wal_trace');
+
+    // eslint-disable-next-line no-console
+    console.log(
+      `[#490 WAL] trace column over ${STEPS} steps: v1=${(v1 / 1e6).toFixed(1)}MB ` +
+        `v2=${(v2 / 1e6).toFixed(2)}MB (${(v1 / v2).toFixed(0)}x smaller)`,
+    );
+
+    // The trace no longer carries outputs: v2 is a tiny fraction of v1's WAL.
+    expect(v2).toBeLessThan(v1 * 0.1);
+    // And v2's trace WAL is small in absolute terms — O(Σ steps) of flags, not
+    // O(N² × output). 50 steps of ~40-byte flags is well under a few MB of WAL.
+    expect(v2).toBeLessThan(5_000_000);
+    // v1's duplicate alone is huge (≈ the 100 KB output re-written N² times).
+    expect(v1).toBeGreaterThan(50_000_000);
+  }, 120_000);
+
+  it('the full assistant row write drops sharply once the duplicate is gone', async () => {
+    if (!available || !client) return;
+    const c = client;
+    await c.query('DROP TABLE IF EXISTS _wal_full');
+    await c.query(
+      'CREATE TABLE _wal_full(id int primary key, content text, tool_calls jsonb, metadata jsonb, status text)',
+    );
+    await c.query("INSERT INTO _wal_full VALUES (1, '', '[]'::jsonb, '{}'::jsonb, 'streaming')");
+
+    const writeRow = async (patch: {
+      content: string;
+      toolCalls: unknown;
+      metadata: unknown;
+      status: string;
+    }) =>
+      c.query(
+        'UPDATE _wal_full SET content=$1, tool_calls=$2, metadata=$3, status=$4 WHERE id=1',
+        [
+          patch.content,
+          JSON.stringify(patch.toolCalls ?? null),
+          JSON.stringify(patch.metadata),
+          patch.status,
+        ],
+      );
+
+    // v2 (real flushAssistant): outputs live once, in metadata.parts.
+    const v2 = await walDelta(c, async () => {
+      const acc: ReturnType<typeof makeStep>[] = [];
+      for (let i = 0; i < STEPS; i++) {
+        acc.push(makeStep(i));
+        await writeRow(flushAssistant(acc as never, '', 'streaming'));
+      }
+    });
+
+    await c.query("UPDATE _wal_full SET content='', tool_calls='[]'::jsonb, metadata='{}'::jsonb WHERE id=1");
+
+    // v1: same row PLUS the duplicated outputs in the trace column.
+    const v1 = await walDelta(c, async () => {
+      const acc: ReturnType<typeof makeStep>[] = [];
+      for (let i = 0; i < STEPS; i++) {
+        acc.push(makeStep(i));
+        const f = flushAssistant(acc as never, '', 'streaming');
+        await writeRow({ ...f, toolCalls: v1Trace(acc) });
+      }
+    });
+
+    await c.query('DROP TABLE IF EXISTS _wal_full');
+
+    // eslint-disable-next-line no-console
+    console.log(
+      `[#490 WAL] full row over ${STEPS} steps: v1=${(v1 / 1e6).toFixed(1)}MB ` +
+        `v2=${(v2 / 1e6).toFixed(1)}MB (saved ${((1 - v2 / v1) * 100).toFixed(0)}%)`,
+    );
+
+    // Removing the duplicated trace copy is a large, real write-volume reduction.
+    expect(v2).toBeLessThan(v1 * 0.75);
+  }, 120_000);
+});

apps/server/src/core/ai-chat/chat-markdown.util.spec.ts

@@ -1,5 +1,10 @@
-import { buildChatMarkdown, normalizeLang } from './chat-markdown.util';
+import {
+  buildChatMarkdown,
+  normalizeLang,
+  labelledToolNames,
+} from './chat-markdown.util';
 import type { AiChatMessage } from '@docmost/db/types/entity.types';
+import { SHARED_TOOL_SPECS } from '../../../../../packages/mcp/src/tool-specs';
 
 /**
  * normalizeLang: the client sends `i18n.language` — a FULL locale tag like
@@ -455,3 +460,43 @@ describe('buildChatMarkdown (server) — structure', () => {
     expect(md).toContain('````');
   });
 });
+
+/**
+ * #494 — REVERSE drift-guard for the export's friendly tool labels. A label keyed
+ * by a tool name that no longer exists silently degrades to the generic
+ * "Ran tool <name>" line; nothing reddened before. This asserts every labelled
+ * name is a real in-app tool and that both languages label the same set.
+ */
+describe('tool-label parity (#494)', () => {
+  // In-app tool names come from the shared registry (inAppKey, excluding
+  // mcpOnly specs) PLUS the inline in-app-only tools that carry a friendly label.
+  // The only labelled inline tool is the hybrid semantic search.
+  const INLINE_INAPP_LABELLED = new Set(['searchPages']);
+
+  function validInAppToolNames(): Set<string> {
+    const names = new Set<string>(INLINE_INAPP_LABELLED);
+    for (const spec of Object.values(SHARED_TOOL_SPECS)) {
+      if ((spec as { mcpOnly?: boolean }).mcpOnly) continue;
+      names.add((spec as { inAppKey: string }).inAppKey);
+    }
+    return names;
+  }
+
+  it('en and ru label the SAME set of tools', () => {
+    expect(labelledToolNames('en').sort()).toEqual(
+      labelledToolNames('ru').sort(),
+    );
+  });
+
+  it('every labelled tool name is a real in-app tool', () => {
+    const valid = validInAppToolNames();
+    const dead = labelledToolNames('en').filter((n) => !valid.has(n));
+    expect(dead).toEqual([]);
+  });
+
+  it('the guard REDDENS for an unknown label key (mutation check)', () => {
+    const valid = validInAppToolNames();
+    // A hypothetical renamed-away label must be caught.
+    expect(valid.has('getPageRenamedAway')).toBe(false);
+  });
+});

apps/server/src/core/ai-chat/chat-markdown.util.ts

@@ -154,6 +154,17 @@ function toolLabel(name: string, lang: ExportLang): string {
   return LABELS[lang].tools[name] ?? LABELS[lang].ranTool(name);
 }
 
+/**
+ * The tool names that carry a hand-written friendly export label, per language.
+ * Exported for the drift-guard (#494): a label keyed by a tool name that no
+ * longer exists is a DEAD entry (the tool was renamed and now silently falls back
+ * to the generic `ranTool(name)` line). The guard asserts every key here is a
+ * real in-app tool AND that the two languages label the SAME set of tools.
+ */
+export function labelledToolNames(lang: ExportLang): string[] {
+  return Object.keys(LABELS[lang].tools);
+}
+
 /**
  * Stringify an arbitrary tool input/output value for a fenced block. Strings
  * pass through as-is; everything else is pretty-printed JSON, falling back to

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

@@ -37,10 +37,13 @@ export class CreateMcpServerDto {
   @IsObject()
   headers?: Record<string, string>;
 
+  // Omit/null => no restriction; `[]` is persisted verbatim and means deny-all
+  // (zero tools) since #476. @IsOptional() skips validation for null as well,
+  // so an explicit null is accepted.
   @IsOptional()
   @IsArray()
   @IsString({ each: true })
-  toolAllowlist?: string[];
+  toolAllowlist?: string[] | null;
 
   // Admin-authored guidance ("how/when to use this server's tools") injected
   // into the agent system prompt next to the tool descriptions (#180). Trusted,

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

@@ -38,10 +38,13 @@ export class UpdateMcpServerDto {
   @IsObject()
   headers?: Record<string, string>;
 
+  // Absent => unchanged; null => no restriction; `[]` is persisted verbatim
+  // and means deny-all (zero tools) since #476. @IsOptional() skips validation
+  // for null as well, so an explicit null is accepted.
   @IsOptional()
   @IsArray()
   @IsString({ each: true })
-  toolAllowlist?: string[];
+  toolAllowlist?: string[] | null;
 
   // Admin-authored prompt guidance (#180). Absent => unchanged; blank => cleared
   // (stored as null by the repo). Capped to bound prompt/token size.

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

@@ -0,0 +1,169 @@
+import { type Tool } from 'ai';
+import { McpClientsService } from './mcp-clients.service';
+
+/**
+ * Tool-allowlist filtering semantics on the merged external toolset (#476).
+ *
+ * COVERAGE CHOICE (documented per issue #476): the full corrupt-row chain
+ * (DB value -> repo normalizeRow -> toolsFor filter) is covered on TWO levels
+ * instead of one live-stub-MCP-server integration test:
+ *   (a) apps/server/test/integration/ai-mcp-server-repo.int-spec.ts pins the
+ *       repo read/write semantics against a real Postgres — `[]` round-trips
+ *       as jsonb `[]`, a present-but-corrupt value fails CLOSED to `[]` with
+ *       an error log;
+ *   (b) THIS spec pins what the toolset builder does with the repo's output —
+ *       null = unrestricted, `['alpha']` = only alpha, `[]` (including the
+ *       corrupt-row fallback) = ZERO tools.
+ * Together they prove the end-to-end property "corrupt/empty allowlist can
+ * never widen to all tools" without a live stub HTTP MCP server.
+ *
+ * The drive path mirrors mcp-namespacing.spec.ts: stub the repo's listEnabled,
+ * spy the private `connect` to return a fake client, inspect the merged keys.
+ */
+
+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;
+}
+
+function server(
+  over: Partial<FakeServer> & { id: string; name: string },
+): FakeServer {
+  return {
+    transport: 'http',
+    url: 'https://example.com/mcp',
+    headersEnc: null,
+    toolAllowlist: null,
+    ...over,
+  };
+}
+
+/**
+ * Build a service whose repo returns `servers` and whose fake clients expose
+ * `rawTools` from tools(). Returns the merged tool keys produced by toolsFor.
+ */
+async function mergedKeysFor(
+  servers: FakeServer[],
+  rawTools: Record<string, Tool>,
+): Promise<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(() =>
+      Promise.resolve({
+        tools: () => Promise.resolve(rawTools),
+        close: () => Promise.resolve(),
+      }),
+    );
+
+  const toolset = await service.toolsFor('ws-1');
+  // Release the lease so the service does not hold the fake clients open.
+  await Promise.all(toolset.clients.map((c) => c.close()));
+  return Object.keys(toolset.tools);
+}
+
+describe('external MCP tool-allowlist filtering (via toolsFor, #476)', () => {
+  afterEach(() => jest.restoreAllMocks());
+
+  const RAW = () => ({
+    alpha: fakeTool(),
+    beta: fakeTool(),
+    gamma: fakeTool(),
+  });
+
+  it("['alpha'] lets ONLY alpha through", async () => {
+    const keys = await mergedKeysFor(
+      [server({ id: 'id-1', name: 'srv', toolAllowlist: ['alpha'] })],
+      RAW(),
+    );
+    expect(keys).toEqual(['srv_alpha']);
+  });
+
+  it('null (no restriction) lets every tool through', async () => {
+    const keys = await mergedKeysFor(
+      [server({ id: 'id-1', name: 'srv', toolAllowlist: null })],
+      RAW(),
+    );
+    expect(keys.sort()).toEqual(['srv_alpha', 'srv_beta', 'srv_gamma']);
+  });
+
+  it('[] (deny-all) yields ZERO tools — an empty array is authoritative, not falsy (#476)', async () => {
+    // This is the regression the #476 change guards: `[]` used to fall through
+    // the old `allow.length > 0` check and expose ALL tools. It must expose NONE.
+    const keys = await mergedKeysFor(
+      [server({ id: 'id-1', name: 'srv', toolAllowlist: [] })],
+      RAW(),
+    );
+    expect(keys).toEqual([]);
+  });
+
+  it('the corrupt-row fallback ([] from the repo) also yields ZERO tools (#476)', async () => {
+    // The repo turns a present-but-corrupt tool_allowlist into `[]` (fail-closed,
+    // see normalizeRow in ai-mcp-server.repo.ts + the int-spec); this pins that
+    // the toolset builder honours that fallback as deny-all rather than allow-all.
+    const corruptFallback: string[] = [];
+    const keys = await mergedKeysFor(
+      [server({ id: 'id-1', name: 'srv', toolAllowlist: corruptFallback })],
+      RAW(),
+    );
+    expect(keys).toEqual([]);
+  });
+
+  it('allowlisted names not exposed by the server are ignored (no phantom tools)', async () => {
+    const keys = await mergedKeysFor(
+      [
+        server({
+          id: 'id-1',
+          name: 'srv',
+          toolAllowlist: ['alpha', 'does-not-exist'],
+        }),
+      ],
+      RAW(),
+    );
+    expect(keys).toEqual(['srv_alpha']);
+  });
+
+  it('a deny-all server contributes no prompt instructions (0 tools merged)', async () => {
+    const repoStub = {
+      listEnabled: jest.fn().mockResolvedValue([
+        {
+          ...server({ id: 'id-1', name: 'srv', toolAllowlist: [] }),
+          instructions: 'use the tools wisely',
+        },
+      ]),
+    };
+    const service = new McpClientsService(repoStub as never, {} as never);
+    jest
+      .spyOn(
+        service as unknown as { connect: (s: FakeServer) => unknown },
+        'connect',
+      )
+      .mockImplementation(() =>
+        Promise.resolve({
+          tools: () => Promise.resolve(RAW()),
+          close: () => Promise.resolve(),
+        }),
+      );
+
+    const toolset = await service.toolsFor('ws-1');
+    await Promise.all(toolset.clients.map((c) => c.close()));
+    expect(Object.keys(toolset.tools)).toEqual([]);
+    // mergeNamespaced reported 0 contributed tools, so no guidance is attached.
+    expect(toolset.instructions).toEqual([]);
+  });
+});

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

@@ -444,9 +444,13 @@ export class McpClientsService {
       try {
         client = await this.connectWithTimeout(server, CONNECT_TIMEOUT_MS);
         const raw = await withTimeout(client.tools(), CONNECT_TIMEOUT_MS);
+        // Allowlist semantics (#476): null/absent = no restriction (all tools);
+        // ANY array — including `[]` — is authoritative, so an EMPTY allowlist
+        // yields ZERO tools (deny-all). Do NOT add a `.length > 0` escape here:
+        // that read `[]` as falsy and silently widened deny-all to allow-all
+        // (the repo also fails corrupt rows closed to `[]` for the same reason).
         const allow = server.toolAllowlist;
-        const picked =
-          Array.isArray(allow) && allow.length > 0 ? pick(raw, allow) : raw;
+        const picked = Array.isArray(allow) ? 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);

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

@@ -100,7 +100,8 @@ export class McpServersService {
       transport: dto.transport,
       url: dto.url,
       headersEnc,
-      // undefined => unchanged; [] / value handled by repo (empty => null).
+      // undefined => unchanged; null => no restriction; `[]` is persisted
+      // verbatim and means deny-all (#476).
       toolAllowlist: dto.toolAllowlist,
       // undefined => unchanged; blank => cleared (null) by the repo.
       instructions: dto.instructions,

apps/server/src/core/ai-chat/history-budget.spec.ts

@@ -0,0 +1,266 @@
+import type { ModelMessage } from 'ai';
+import {
+  resolveReplayBudget,
+  isContextOverflowError,
+  estimateMessagesTokens,
+  trimHistoryForReplay,
+  REPLAY_BUDGET_DEFAULT_TOKENS,
+  REPLAY_TRUNCATION_MARKER,
+  REPLAY_TURN_COLLAPSED_MARKER,
+} from './history-budget';
+
+describe('resolveReplayBudget', () => {
+  it('uses floor(0.7 x window) for a configured window (no cap)', () => {
+    // 0.7 x 60k = 42k
+    expect(resolveReplayBudget(60_000)).toEqual({
+      thresholdTokens: 42_000,
+      usedDefault: false,
+    });
+    // 0.7 x 1M = 700k — NOT capped (anti-brick vs the window, not a cost limiter).
+    expect(resolveReplayBudget(1_000_000)).toEqual({
+      thresholdTokens: 700_000,
+      usedDefault: false,
+    });
+  });
+
+  it('accepts the raw ::text stored form', () => {
+    expect(resolveReplayBudget('60000').thresholdTokens).toBe(42_000);
+  });
+
+  // The crux (#490): a chat with NO context window configured must STILL be
+  // budgeted — those are exactly the installs that hit terminal overflow.
+  it('applies the flat default when the window is unset/empty', () => {
+    expect(resolveReplayBudget(undefined)).toEqual({
+      thresholdTokens: REPLAY_BUDGET_DEFAULT_TOKENS,
+      usedDefault: true,
+    });
+    expect(resolveReplayBudget('')).toEqual({
+      thresholdTokens: REPLAY_BUDGET_DEFAULT_TOKENS,
+      usedDefault: true,
+    });
+    expect(resolveReplayBudget('   ')).toEqual({
+      thresholdTokens: REPLAY_BUDGET_DEFAULT_TOKENS,
+      usedDefault: true,
+    });
+  });
+
+  it('treats an explicit 0 as the off-switch (distinct from unset)', () => {
+    expect(resolveReplayBudget(0)).toEqual({
+      thresholdTokens: null,
+      usedDefault: false,
+    });
+    expect(resolveReplayBudget('0')).toEqual({
+      thresholdTokens: null,
+      usedDefault: false,
+    });
+  });
+
+  it('falls back to the default on a negative/garbage value', () => {
+    expect(resolveReplayBudget(-5).usedDefault).toBe(true);
+    expect(resolveReplayBudget('abc').usedDefault).toBe(true);
+  });
+});
+
+describe('isContextOverflowError', () => {
+  it('classifies a real provider 400 context-overflow shape', () => {
+    // OpenAI-compatible shape.
+    expect(
+      isContextOverflowError({
+        statusCode: 400,
+        message:
+          "This model's maximum context length is 128000 tokens. However, your messages resulted in 214000 tokens. Please reduce the length of the messages.",
+      }),
+    ).toBe(true);
+    // Anthropic-style wording.
+    expect(
+      isContextOverflowError({
+        status: 400,
+        message: 'prompt is too long: 250000 tokens > 200000 maximum',
+      }),
+    ).toBe(true);
+    // Nested body + string status.
+    expect(
+      isContextOverflowError({
+        response: { status: '400' },
+        message: 'input is too long for the requested model',
+      }),
+    ).toBe(true);
+    // Error instance with the cause carrying the body.
+    const e = new Error('Bad request');
+    (e as any).statusCode = 400;
+    (e as any).cause = new Error('maximum context window exceeded');
+    expect(isContextOverflowError(e)).toBe(true);
+  });
+
+  it('does NOT classify unrelated 400s or auth/rate-limit errors', () => {
+    expect(
+      isContextOverflowError({ statusCode: 400, message: 'invalid tool schema' }),
+    ).toBe(false);
+    expect(
+      isContextOverflowError({
+        statusCode: 429,
+        message: 'context length exceeded but rate limited',
+      }),
+    ).toBe(false);
+    expect(isContextOverflowError({ statusCode: 500, message: 'server error' })).toBe(
+      false,
+    );
+    expect(isContextOverflowError(undefined)).toBe(false);
+    expect(isContextOverflowError('some random string')).toBe(false);
+  });
+});
+
+// Helpers to build ModelMessage fixtures in the ai@6 shape.
+const userMsg = (text: string): ModelMessage =>
+  ({ role: 'user', content: [{ type: 'text', text }] }) as ModelMessage;
+const assistantMsg = (
+  text: string,
+  toolCallId?: string,
+  toolName?: string,
+): ModelMessage =>
+  ({
+    role: 'assistant',
+    content: [
+      { type: 'text', text },
+      ...(toolCallId
+        ? [{ type: 'tool-call', toolCallId, toolName, input: {} }]
+        : []),
+    ],
+  }) as ModelMessage;
+const toolMsg = (
+  toolCallId: string,
+  toolName: string,
+  value: unknown,
+): ModelMessage =>
+  ({
+    role: 'tool',
+    content: [
+      { type: 'tool-result', toolCallId, toolName, output: { type: 'json', value } },
+    ],
+  }) as ModelMessage;
+
+describe('trimHistoryForReplay', () => {
+  it('null budget disables trimming (returns the same reference)', () => {
+    const msgs = [userMsg('hi'), assistantMsg('yo')];
+    const r = trimHistoryForReplay(msgs, null);
+    expect(r.trimmed).toBe(false);
+    expect(r.messages).toBe(msgs);
+  });
+
+  it('leaves history under budget untouched (same reference)', () => {
+    const msgs = [userMsg('hi'), assistantMsg('a short answer')];
+    const r = trimHistoryForReplay(msgs, 100_000);
+    expect(r.trimmed).toBe(false);
+    expect(r.messages).toBe(msgs);
+  });
+
+  it('truncates OLD tool outputs but keeps recent turns full', () => {
+    const big = 'X'.repeat(40_000); // ~16k tokens on its own
+    const msgs: ModelMessage[] = [];
+    // 6 OLD turns (indices 0..5), each with a huge tool output.
+    for (let i = 0; i < 6; i++) {
+      msgs.push(userMsg(`old q${i}`));
+      msgs.push(assistantMsg('looking', `c${i}`, 'getPage'));
+      msgs.push(toolMsg(`c${i}`, 'getPage', { body: big }));
+      msgs.push(assistantMsg(`old a${i}`));
+    }
+    // 3 small recent turns, then the CURRENT turn with its own huge tool output.
+    // With REPLAY_KEEP_RECENT_TURNS=4 the last 4 user-turns stay full, so only
+    // these small recent turns + the current big one are kept full; the 6 old
+    // turns above fall in the trim region.
+    for (let i = 0; i < 3; i++) {
+      msgs.push(userMsg(`recent q${i}`));
+      msgs.push(assistantMsg(`recent a${i}`));
+    }
+    msgs.push(userMsg('current q'));
+    msgs.push(assistantMsg('looking', 'cR', 'getPage'));
+    msgs.push(toolMsg('cR', 'getPage', { body: big }));
+    msgs.push(assistantMsg('current a'));
+
+    // Budget large enough that phase-1 tool truncation alone brings it under.
+    const r = trimHistoryForReplay(msgs, 30_000);
+    expect(r.trimmed).toBe(true);
+    const flat = JSON.stringify(r.messages);
+    // The CURRENT turn's tool output survives in full.
+    expect(flat).toContain(big);
+    // Old outputs were truncated with the marker.
+    expect(flat).toContain(REPLAY_TRUNCATION_MARKER);
+    // Phase 1 sufficed: the oldest turns were NOT collapsed.
+    expect(flat).not.toContain(REPLAY_TURN_COLLAPSED_MARKER);
+    expect(estimateMessagesTokens(r.messages)).toBeLessThan(
+      estimateMessagesTokens(msgs),
+    );
+  });
+
+  it('collapses the oldest turns when tool truncation is not enough', () => {
+    // Many turns with LARGE assistant TEXT (not tool output) so phase 1 can't help.
+    const bigText = 'слово '.repeat(8_000); // large Cyrillic text per turn
+    const msgs: ModelMessage[] = [];
+    for (let i = 0; i < 12; i++) {
+      msgs.push(userMsg(`q${i}`));
+      msgs.push(assistantMsg(bigText));
+    }
+    const r = trimHistoryForReplay(msgs, 30_000);
+    expect(r.trimmed).toBe(true);
+    // Oldest turns collapsed; result fits (best-effort) and is much smaller.
+    expect(estimateMessagesTokens(r.messages)).toBeLessThan(
+      estimateMessagesTokens(msgs),
+    );
+    // The LAST turn's text is preserved in full (recent turns stay full).
+    expect(JSON.stringify(r.messages[r.messages.length - 1])).toContain(bigText);
+  });
+
+  it('is deterministic / byte-stable for identical inputs', () => {
+    const big = 'Y'.repeat(30_000);
+    const build = (): ModelMessage[] => {
+      const m: ModelMessage[] = [];
+      for (let i = 0; i < 10; i++) {
+        m.push(userMsg(`q${i}`));
+        m.push(assistantMsg('t', `c${i}`, 'getPage'));
+        m.push(toolMsg(`c${i}`, 'getPage', { body: big }));
+      }
+      return m;
+    };
+    const a = trimHistoryForReplay(build(), 15_000);
+    const b = trimHistoryForReplay(build(), 15_000);
+    expect(JSON.stringify(a.messages)).toBe(JSON.stringify(b.messages));
+  });
+
+  it('never leaves an unpaired tool-call after collapsing (balanced history)', () => {
+    const big = 'Z'.repeat(40_000);
+    const msgs: ModelMessage[] = [];
+    for (let i = 0; i < 10; i++) {
+      msgs.push(userMsg(`q${i}`));
+      msgs.push(assistantMsg('t', `c${i}`, 'getPage'));
+      msgs.push(toolMsg(`c${i}`, 'getPage', { body: big }));
+    }
+    const r = trimHistoryForReplay(msgs, 8_000);
+    // Count tool-call vs tool-result parts in the trimmed output.
+    let calls = 0;
+    let results = 0;
+    for (const m of r.messages) {
+      if (!Array.isArray(m.content)) continue;
+      for (const p of m.content as Array<{ type?: string }>) {
+        if (p.type === 'tool-call') calls++;
+        if (p.type === 'tool-result' || p.type === 'tool-error') results++;
+      }
+    }
+    // Every surviving tool-call has a surviving result (collapsing drops BOTH).
+    expect(calls).toBe(results);
+    // Collapsed turns carry the marker.
+    expect(JSON.stringify(r.messages)).toContain(REPLAY_TURN_COLLAPSED_MARKER);
+  });
+
+  it('respects the provider fact: under-budget contextTokens skips trimming', () => {
+    const big = 'W'.repeat(60_000);
+    const msgs = [
+      userMsg('q'),
+      assistantMsg('t', 'c1', 'getPage'),
+      toolMsg('c1', 'getPage', { body: big }),
+    ];
+    // char-estimate is high, but the provider says we are well under budget.
+    const r = trimHistoryForReplay(msgs, 100_000, 5_000);
+    expect(r.trimmed).toBe(false);
+    expect(r.messages).toBe(msgs);
+  });
+});

apps/server/src/core/ai-chat/history-budget.ts

@@ -0,0 +1,375 @@
+/**
+ * History-replay token budget (#490).
+ *
+ * The whole persisted conversation is replayed to the provider on EVERY turn, so
+ * a long chat eventually exceeds the model's context window and the provider 400s
+ * on every turn — terminally (the chat "bricks"). This module bounds the replayed
+ * history at REPLAY TIME only: it never mutates what is persisted (the DB stays
+ * the full record), and its output is a deterministic, byte-stable function of its
+ * input so the trimmed prefix is identical turn to turn (provider prompt-cache
+ * friendliness — real money on long chats).
+ *
+ * The PRIMARY signal is the provider's own fact: `metadata.contextTokens` from the
+ * last turn. The chars-based {@link estimateTokens} (shared with the client) is
+ * used only for the DELTA of not-yet-sent messages, to decide WHAT to trim, and as
+ * the fallback for chats with no usage yet.
+ */
+import type { ModelMessage } from 'ai';
+import { estimateTokens } from '@docmost/token-estimate';
+
+/** Flat default budget when no context window is configured (tokens). */
+export const REPLAY_BUDGET_DEFAULT_TOKENS = 100_000;
+/** Fraction of a configured context window used as the budget. */
+export const REPLAY_BUDGET_WINDOW_FRACTION = 0.7;
+/**
+ * Fraction of the normal budget used for the REACTIVE re-trim after a provider
+ * context-overflow 400 — the preventive estimate under-counted, so cut harder.
+ */
+export const REPLAY_AGGRESSIVE_FRACTION = 0.5;
+/**
+ * Turns (a user message + its assistant/tool replies) kept FULL at the tail,
+ * including the current one — never trimmed. Older turns are compacted first.
+ */
+export const REPLAY_KEEP_RECENT_TURNS = 4;
+/** Leading chars kept from a truncated old tool output. */
+export const REPLAY_TOOL_OUTPUT_HEAD = 800;
+/** Trailing chars kept from a truncated old tool output. */
+export const REPLAY_TOOL_OUTPUT_TAIL = 300;
+/** Marker inserted where an old tool output was truncated for replay. */
+export const REPLAY_TRUNCATION_MARKER =
+  '[…truncated for replay; call the tool again to read the full output]';
+/** Marker for a whole old turn collapsed to its text. */
+export const REPLAY_TURN_COLLAPSED_MARKER =
+  '[earlier tool activity omitted for replay]';
+
+export interface ReplayBudget {
+  /** Token threshold above which replay history is trimmed; `null` = OFF. */
+  thresholdTokens: number | null;
+  /** True when the flat default was used (no context window configured). */
+  usedDefault: boolean;
+}
+
+/**
+ * Resolve the replay budget from the RAW stored `chatContextWindow` (text/number).
+ *  - a positive value  -> `floor(fraction × window)` (NO cap — the budgeter is
+ *    anti-brick protection against the window itself, not a cost/economy limiter,
+ *    exactly as the codebase already treats maxOutputTokens; the reactive branch
+ *    still guarantees anti-brick regardless of how high this budget is)
+ *  - explicit `0`       -> OFF (admin opt-out; `null` threshold)
+ *  - unset/empty/invalid-> the flat default (still protects — the installations
+ *    that hit terminal overflow are exactly the ones that never set a window)
+ *
+ * Note the raw value is needed because the parsed `chatContextWindow` collapses
+ * both `0` and unset to `undefined`, which would erase the explicit off-switch.
+ */
+export function resolveReplayBudget(rawContextWindow: unknown): ReplayBudget {
+  let n: number | undefined;
+  if (typeof rawContextWindow === 'number') {
+    n = rawContextWindow;
+  } else if (typeof rawContextWindow === 'string') {
+    const t = rawContextWindow.trim();
+    n = t === '' ? undefined : Number(t);
+  }
+  // Unset / empty / non-numeric / negative -> flat default (the protective case).
+  if (n === undefined || !Number.isFinite(n) || n < 0) {
+    return { thresholdTokens: REPLAY_BUDGET_DEFAULT_TOKENS, usedDefault: true };
+  }
+  // Explicit 0 -> off-switch.
+  if (n === 0) {
+    return { thresholdTokens: null, usedDefault: false };
+  }
+  return {
+    thresholdTokens: Math.floor(REPLAY_BUDGET_WINDOW_FRACTION * n),
+    usedDefault: false,
+  };
+}
+
+/**
+ * The effective replay threshold for THIS turn, given the base budget and whether
+ * the PREVIOUS turn hit a context-overflow 400 (the reactive-recovery signal,
+ * `metadata.replayOverflow`). On recovery the base budget is scaled down by
+ * {@link REPLAY_AGGRESSIVE_FRACTION}: the overflowing turn produced no usage
+ * signal, so the preventive estimate under-counted and a normal-threshold trim may
+ * not shrink enough to fit — this harder cut is what un-bricks the chat.
+ *
+ * A `null` base budget (trimming OFF) is passed through unchanged: an explicit
+ * off-switch is never overridden by the recovery path.
+ */
+export function resolveEffectiveReplayThreshold(
+  thresholdTokens: number | null,
+  priorOverflowed: boolean,
+): number | null {
+  if (!priorOverflowed || thresholdTokens == null) return thresholdTokens;
+  return Math.floor(thresholdTokens * REPLAY_AGGRESSIVE_FRACTION);
+}
+
+/**
+ * True when a provider error is a CONTEXT-OVERFLOW rejection (the prompt exceeds
+ * the model's window). Providers surface this as an HTTP 400 with a recognizable
+ * message; match both the status and the message patterns robustly across
+ * OpenAI-compatible / Anthropic / Gemini wordings, since the exact shape varies.
+ */
+export function isContextOverflowError(error: unknown): boolean {
+  const status = extractStatus(error);
+  const msg = extractMessage(error).toLowerCase();
+  // Message patterns seen across providers for "prompt too long".
+  const overflowPattern =
+    /context (?:length|window)|maximum context|too many tokens|too large for|reduce the length|prompt is too long|input (?:is )?too long|exceeds? the (?:maximum )?(?:context|token)|maximum.*tokens|string too long/;
+  if (!overflowPattern.test(msg)) return false;
+  // A 400/413 with an overflow-shaped message is an overflow. Some providers
+  // omit/rewrite the status, so accept the message match when the status is
+  // unknown, but reject it for auth/rate-limit statuses that never mean overflow.
+  if (status === 400 || status === 413) return true;
+  if (status === 401 || status === 403 || status === 429) return false;
+  return true;
+}
+
+function extractStatus(error: unknown): number | undefined {
+  if (!error || typeof error !== 'object') return undefined;
+  const e = error as Record<string, unknown>;
+  for (const k of ['statusCode', 'status']) {
+    const v = e[k];
+    if (typeof v === 'number') return v;
+    if (typeof v === 'string' && /^\d+$/.test(v)) return Number(v);
+  }
+  // Nested (e.g. { response: { status } } / { cause: { statusCode } }).
+  for (const k of ['response', 'cause', 'data']) {
+    const nested = e[k];
+    if (nested && typeof nested === 'object') {
+      const s = extractStatus(nested);
+      if (s !== undefined) return s;
+    }
+  }
+  return undefined;
+}
+
+function extractMessage(error: unknown): string {
+  if (error == null) return '';
+  if (typeof error === 'string') return error;
+  if (error instanceof Error) {
+    // Include nested causes (provider libs wrap the real body in `cause`).
+    const cause = (error as { cause?: unknown }).cause;
+    return `${error.message} ${cause ? extractMessage(cause) : ''}`;
+  }
+  if (typeof error === 'object') {
+    const e = error as Record<string, unknown>;
+    const parts: string[] = [];
+    for (const k of ['message', 'error', 'body', 'responseBody', 'data']) {
+      const v = e[k];
+      if (typeof v === 'string') parts.push(v);
+      else if (v && typeof v === 'object') parts.push(extractMessage(v));
+    }
+    return parts.join(' ');
+  }
+  return String(error);
+}
+
+/** Rough token size of a ModelMessage array via the shared chars estimator. */
+export function estimateMessagesTokens(
+  messages: ReadonlyArray<ModelMessage>,
+): number {
+  let total = 0;
+  for (const m of messages) {
+    total += estimateTokens(serializeContent(m.content));
+  }
+  return total;
+}
+
+function serializeContent(content: unknown): string {
+  if (typeof content === 'string') return content;
+  try {
+    return JSON.stringify(content) ?? '';
+  } catch {
+    return '';
+  }
+}
+
+/** Deep JSON string of an arbitrary value, bounded so estimation never throws. */
+function stringifyValue(value: unknown): string {
+  if (typeof value === 'string') return value;
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+export interface TrimResult {
+  messages: ModelMessage[];
+  /** Whether any trimming was applied. */
+  trimmed: boolean;
+  /** Estimated tokens of the returned messages (chars-based). */
+  estimatedTokens: number;
+}
+
+/**
+ * Bound the replayed history to `budgetTokens`, deterministically. Returns the
+ * SAME array reference (no copy) when nothing needs trimming, so the common case
+ * is free and byte-identical. Trimming order (spec #490):
+ *   1. truncate OLD turns' tool outputs (head+tail + marker) — the bulk of the size
+ *   2. mechanically collapse the OLDEST turns to their text (concatenation, no LLM)
+ *   3. the current + last {@link REPLAY_KEEP_RECENT_TURNS} turns stay FULL
+ *
+ * `budgetTokens === null` disables trimming. `priorContextTokens` (the provider's
+ * fact from last turn) short-circuits the decision: when it is known and already
+ * under budget we skip trimming even if the char-estimate is higher (the provider
+ * count is authoritative). The char-estimate drives WHAT to cut.
+ */
+export function trimHistoryForReplay(
+  messages: ModelMessage[],
+  budgetTokens: number | null,
+  priorContextTokens?: number,
+): TrimResult {
+  if (budgetTokens == null) {
+    return { messages, trimmed: false, estimatedTokens: 0 };
+  }
+  const estimated = estimateMessagesTokens(messages);
+  // Decision signal: prefer the provider's fact (last turn's contextTokens) plus
+  // the estimated delta of the messages appended since; fall back to the pure
+  // char-estimate for a chat with no usage yet.
+  const projected =
+    priorContextTokens != null
+      ? Math.max(priorContextTokens, estimated)
+      : estimated;
+  if (projected <= budgetTokens) {
+    return { messages, trimmed: false, estimatedTokens: estimated };
+  }
+
+  // The tail we always keep full: from the Nth-from-last user message onward.
+  const boundary = recentBoundaryIndex(messages, REPLAY_KEEP_RECENT_TURNS);
+  const tail = messages.slice(boundary);
+  let head = messages.slice(0, boundary).map(cloneMessage);
+
+  // Phase 1: truncate old tool outputs.
+  for (const m of head) {
+    if (m.role === 'tool') truncateToolMessage(m);
+  }
+  let out = [...head, ...tail];
+  let est = estimateMessagesTokens(out);
+  if (est <= budgetTokens) {
+    return { messages: out, trimmed: true, estimatedTokens: est };
+  }
+
+  // Phase 2: collapse the oldest turns (in `head`) to their text, one at a time,
+  // from the oldest, until we fit or the whole head is collapsed.
+  const turns = splitTurns(head);
+  const collapsed: ModelMessage[] = [];
+  let i = 0;
+  for (; i < turns.length; i++) {
+    if (est <= budgetTokens) break;
+    collapsed.push(...collapseTurn(turns[i]));
+    // Re-estimate the whole prospective output.
+    const remaining = turns.slice(i + 1).flat();
+    out = [...collapsed, ...remaining, ...tail];
+    est = estimateMessagesTokens(out);
+  }
+  // Include any turns we didn't need to collapse.
+  const remaining = turns.slice(i).flat();
+  out = [...collapsed, ...remaining, ...tail];
+  est = estimateMessagesTokens(out);
+  return { messages: out, trimmed: true, estimatedTokens: est };
+}
+
+/** Index of the first message of the Nth-from-last user turn (0 if fewer). */
+function recentBoundaryIndex(
+  messages: ReadonlyArray<ModelMessage>,
+  keepTurns: number,
+): number {
+  const userIdx: number[] = [];
+  for (let i = 0; i < messages.length; i++) {
+    if (messages[i].role === 'user') userIdx.push(i);
+  }
+  if (userIdx.length <= keepTurns) return 0;
+  return userIdx[userIdx.length - keepTurns];
+}
+
+/** Split a message list into turns; each turn starts at a `user` message. */
+function splitTurns(messages: ModelMessage[]): ModelMessage[][] {
+  const turns: ModelMessage[][] = [];
+  for (const m of messages) {
+    if (m.role === 'user' || turns.length === 0) turns.push([m]);
+    else turns[turns.length - 1].push(m);
+  }
+  return turns;
+}
+
+/**
+ * Collapse a whole turn to its plain text (mechanical concatenation, not an LLM
+ * summary). Keeps the user message; replaces the assistant/tool messages with a
+ * single assistant text message = the assistant's concatenated text + a marker
+ * when tool activity was dropped. Dropping BOTH the tool-call and tool-result
+ * parts together keeps the rebuilt history balanced (no unpaired calls).
+ */
+function collapseTurn(turn: ModelMessage[]): ModelMessage[] {
+  const out: ModelMessage[] = [];
+  let assistantText = '';
+  let hadTools = false;
+  for (const m of turn) {
+    if (m.role === 'user') {
+      out.push(m);
+    } else if (m.role === 'assistant') {
+      const { text, tools } = extractAssistantText(m.content);
+      assistantText += text;
+      hadTools = hadTools || tools;
+    } else if (m.role === 'tool') {
+      hadTools = true;
+    } else {
+      out.push(m);
+    }
+  }
+  const note =
+    (assistantText ? assistantText.trimEnd() : '') +
+    (hadTools
+      ? `${assistantText ? '\n\n' : ''}${REPLAY_TURN_COLLAPSED_MARKER}`
+      : '');
+  if (note) out.push({ role: 'assistant', content: note } as ModelMessage);
+  return out;
+}
+
+function extractAssistantText(content: unknown): {
+  text: string;
+  tools: boolean;
+} {
+  if (typeof content === 'string') return { text: content, tools: false };
+  if (!Array.isArray(content)) return { text: '', tools: false };
+  let text = '';
+  let tools = false;
+  for (const part of content) {
+    const type = (part as { type?: string })?.type;
+    if (type === 'text') text += (part as { text?: string }).text ?? '';
+    else if (type === 'tool-call') tools = true;
+  }
+  return { text, tools };
+}
+
+/** Truncate every tool-result output in a `tool` message to head+tail+marker. */
+function truncateToolMessage(message: ModelMessage): void {
+  const content = message.content;
+  if (!Array.isArray(content)) return;
+  for (const part of content) {
+    const p = part as { type?: string; output?: { type?: string; value?: unknown } };
+    if (p.type !== 'tool-result' && p.type !== 'tool-error') continue;
+    if (!p.output) continue;
+    const raw = stringifyValue(p.output.value);
+    const budget = REPLAY_TOOL_OUTPUT_HEAD + REPLAY_TOOL_OUTPUT_TAIL;
+    if (raw.length <= budget + REPLAY_TRUNCATION_MARKER.length) continue;
+    const truncated =
+      raw.slice(0, REPLAY_TOOL_OUTPUT_HEAD) +
+      `\n${REPLAY_TRUNCATION_MARKER}\n` +
+      raw.slice(raw.length - REPLAY_TOOL_OUTPUT_TAIL);
+    // Represent the shrunk output as a text output (a valid tool-result output).
+    p.output = { type: 'text', value: truncated };
+  }
+}
+
+/** Shallow-ish clone so trimming never mutates the caller's (persisted-derived)
+ *  message objects — only the OLD region is cloned before it is edited. */
+function cloneMessage(m: ModelMessage): ModelMessage {
+  if (typeof m.content === 'string') return { ...m };
+  return {
+    ...m,
+    content: (m.content as unknown[]).map((p) =>
+      p && typeof p === 'object' ? { ...(p as object) } : p,
+    ),
+  } as ModelMessage;
+}

apps/server/src/core/ai-chat/output-degeneration.spec.ts

@@ -9,9 +9,73 @@ import {
   DEGENERATION_CHECK_STEP,
   REPEATED_LINES_THRESHOLD,
   MIN_PERIOD_REPEATS,
+  degenerationThresholds,
 } from './output-degeneration';
 import { AiChatService } from './ai-chat.service';
 
+// Part A (#495 iter10): the detector thresholds are env-tunable. These drive the
+// resolver against real repeat-count shapes and mutation-verify that the env
+// override actually changes the trigger point (not a vacuous read).
+describe('degeneration thresholds are env-configurable', () => {
+  const VARS = [
+    'AI_CHAT_DEGENERATION_REPEATED_LINES',
+    'AI_CHAT_DEGENERATION_PERIOD_MAX_LEN',
+    'AI_CHAT_DEGENERATION_PERIOD_MIN_REPEATS',
+    'AI_CHAT_DEGENERATION_CHECK_STEP',
+  ];
+  const saved: Record<string, string | undefined> = {};
+  beforeEach(() => {
+    for (const v of VARS) saved[v] = process.env[v];
+  });
+  afterEach(() => {
+    for (const v of VARS) {
+      if (saved[v] === undefined) delete process.env[v];
+      else process.env[v] = saved[v];
+    }
+  });
+
+  it('defaults to the compiled constants when unset', () => {
+    for (const v of VARS) delete process.env[v];
+    expect(degenerationThresholds()).toEqual({
+      repeatedLines: REPEATED_LINES_THRESHOLD,
+      maxPeriodLen: 150,
+      minPeriodRepeats: MIN_PERIOD_REPEATS,
+      checkStep: DEGENERATION_CHECK_STEP,
+    });
+  });
+
+  it('falls back to the default on blank / invalid / non-positive values', () => {
+    for (const bad of ['', '  ', 'abc', '0', '-3', '1.5']) {
+      process.env.AI_CHAT_DEGENERATION_REPEATED_LINES = bad;
+      // '1.5' floors to 1 (still ≥1, valid); every other bad value → default.
+      const expected = bad === '1.5' ? 1 : REPEATED_LINES_THRESHOLD;
+      expect(degenerationThresholds().repeatedLines).toBe(expected);
+    }
+  });
+
+  it('a RAISED check-step suppresses a burst the default would have flagged', () => {
+    // A ~3.3KB periodic burst is periodic-degenerate, but shouldCheckDegeneration
+    // is the throttle gate. Default checkStep=2000 arms on it; raising the step
+    // above the burst size means the throttle never re-fires for it.
+    const burstLen = 'loadTools.\n'.repeat(300).length; // ~3300
+    delete process.env.AI_CHAT_DEGENERATION_CHECK_STEP;
+    expect(shouldCheckDegeneration(burstLen, 0)).toBe(true); // default 2000
+    process.env.AI_CHAT_DEGENERATION_CHECK_STEP = String(burstLen + 1);
+    expect(shouldCheckDegeneration(burstLen, 0)).toBe(false); // raised gate
+  });
+
+  it('a LOWERED repeated-lines threshold trips on a shorter identical-line run', () => {
+    // 8 identical lines: below the default 25 (rule 1) and below the periodic
+    // rule's 20 repeats — so isDegenerateOutput is false by default.
+    const shortRun = 'x\n'.repeat(8);
+    delete process.env.AI_CHAT_DEGENERATION_REPEATED_LINES;
+    expect(isDegenerateOutput(shortRun)).toBe(false);
+    // Lower rule 1 to 5 → the 8-line run now trips.
+    process.env.AI_CHAT_DEGENERATION_REPEATED_LINES = '5';
+    expect(isDegenerateOutput(shortRun)).toBe(true);
+  });
+});
+
 // Mock ONLY streamText so we can capture the onChunk/onStepFinish callbacks the
 // service registers and drive them by hand; every other `ai` export the service
 // uses (convertToModelMessages, stepCountIs, …) stays real.

apps/server/src/core/ai-chat/output-degeneration.ts

@@ -23,6 +23,54 @@ export const MAX_PERIOD_LEN = 150;
 /** Rule 2: minimum number of consecutive block repeats to trigger. */
 export const MIN_PERIOD_REPEATS = 20;
 
+/**
+ * Read a positive-integer threshold from an env var, falling back to `fallback`
+ * on unset/blank/invalid/non-positive. Mirrors the `AI_STREAM_PRE_RESPONSE_RETRIES`
+ * resolver in `ai-streaming-fetch.ts`: read the RAW string first so a blank value
+ * is treated as "unset" (→ fallback) rather than coercing to 0. Thresholds must
+ * stay ≥ 1 — a 0/negative would make the detector fire on any text (or never), so
+ * a bad value degrades to the safe compiled default instead. Env-tunable so an
+ * operator can retune the anti-babble guard (#444) without a redeploy, following
+ * the `AI_CHAT_FINAL_STEP_LOCKDOWN` toggle convention.
+ */
+function envThreshold(name: string, fallback: number): number {
+  const rawStr = process.env[name];
+  if (rawStr === undefined || rawStr.trim() === '') return fallback;
+  const raw = Number(rawStr);
+  return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : fallback;
+}
+
+/**
+ * Resolve the degeneration-detector thresholds from the environment, each
+ * defaulting to the compiled constant above. Read fresh per call (not cached at
+ * import) so a test — or a runtime env change — takes effect deterministically.
+ */
+export function degenerationThresholds(): {
+  repeatedLines: number;
+  maxPeriodLen: number;
+  minPeriodRepeats: number;
+  checkStep: number;
+} {
+  return {
+    repeatedLines: envThreshold(
+      'AI_CHAT_DEGENERATION_REPEATED_LINES',
+      REPEATED_LINES_THRESHOLD,
+    ),
+    maxPeriodLen: envThreshold(
+      'AI_CHAT_DEGENERATION_PERIOD_MAX_LEN',
+      MAX_PERIOD_LEN,
+    ),
+    minPeriodRepeats: envThreshold(
+      'AI_CHAT_DEGENERATION_PERIOD_MIN_REPEATS',
+      MIN_PERIOD_REPEATS,
+    ),
+    checkStep: envThreshold(
+      'AI_CHAT_DEGENERATION_CHECK_STEP',
+      DEGENERATION_CHECK_STEP,
+    ),
+  };
+}
+
 /**
  * Rule 1 — ≥`REPEATED_LINES_THRESHOLD` consecutive IDENTICAL non-empty lines at
  * the tail. Catches the classic newline-delimited loop ("loadTools.\n" ×N).
@@ -128,7 +176,11 @@ export function hasPeriodicTail(
  * Pure — the caller owns the abort side effect.
  */
 export function isDegenerateOutput(text: string): boolean {
-  return hasRepeatedLineRun(text) || hasPeriodicTail(text);
+  const cfg = degenerationThresholds();
+  return (
+    hasRepeatedLineRun(text, cfg.repeatedLines) ||
+    hasPeriodicTail(text, cfg.maxPeriodLen, cfg.minPeriodRepeats)
+  );
 }
 
 /**
@@ -154,7 +206,7 @@ export function shouldCheckDegeneration(
   textLen: number,
   lastCheckLen: number,
 ): boolean {
-  return textLen - lastCheckLen >= DEGENERATION_CHECK_STEP;
+  return textLen - lastCheckLen >= degenerationThresholds().checkStep;
 }
 
 /**

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

@@ -307,6 +307,10 @@ export class PublicShareChatService {
         system,
         messages: modelMessages,
         tools,
+        // Pin the AI SDK per-request retry budget explicitly (matches the SDK
+        // default of 2). Connection arithmetic: (1 + maxRetries) × (1 +
+        // AI_STREAM_PRE_RESPONSE_RETRIES) worst-case connects per turn.
+        maxRetries: 2,
         // Bound the agent loop for anonymous callers.
         stopWhen: stepCountIs(5),
         // Cap per-request output so one anonymous call cannot run up the provider

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

@@ -426,6 +426,7 @@ export class AiChatToolsService {
     const {
       sharedToolSpecs,
       createCommentSignalTracker,
+      createListCommentsProbe,
       searchShapes,
       getGuideSection,
     } = await loadDocmostMcp();
@@ -718,7 +719,11 @@ export class AiChatToolsService {
       if (spec.mcpOnly) continue;
       if (spec.inlineBothHosts) continue;
       const run = spec.inAppExecute ?? spec.execute;
-      if (!run) continue; // defensive: a shared spec always carries one of them.
+      // Guaranteed present by assertEverySpecIsRegisterable() (#494), which runs
+      // at tool-specs module load and throws if a non-inline spec the in-app host
+      // registers carries neither inAppExecute nor execute — so this can no longer
+      // silently drop a mis-declared tool. Kept as a type-narrowing guard.
+      if (!run) continue;
       tools[spec.inAppKey] = sharedTool(
         spec,
         (async (args) =>
@@ -764,35 +769,21 @@ export class AiChatToolsService {
     // wrapper below) so the race governs the whole call. The client carries the
     // per-call composite signal via setToolAbortSignal.
     const capMs = inAppToolCallCapMs();
-    if (!createCommentSignalTracker) {
+    // The signal needs BOTH the tracker factory AND the shared count-source probe
+    // factory (#494). Either being absent (a stale @docmost/mcp build or a mocked
+    // loader) => signal disabled, tool results byte-identical.
+    if (!createCommentSignalTracker || !createListCommentsProbe) {
       return wrapInAppToolsWithCap(tools, client, capMs);
     }
 
+    // Shared probe (#494): the SAME factory the standalone MCP host uses, so the
+    // in-app probe body is no longer a hand-mirror that could drift (counting the
+    // full feed newer than the watermark, labelling a hit with the light page
+    // title). `client` supplies the loopback listComments/getPageRaw reads.
     const tracker = createCommentSignalTracker({
-      probe: async (pageId: string, sinceMs: number) => {
-        const { items } = await client.listComments(pageId, true);
-        const count = (items as Array<{ createdAt?: string }>).filter((c) => {
-          const created = c?.createdAt ? new Date(c.createdAt).getTime() : NaN;
-          return Number.isFinite(created) && created > sinceMs;
-        }).length;
-        let title: string | undefined;
-        if (count > 0) {
-          // Title labels the signal; untrusted, defanged by the shared builder.
-          // Fetched only on a hit so the no-signal path never pays for it. Uses
-          // the LIGHT raw page info (title only) — mirroring the standalone MCP
-          // probe's getPageRaw — instead of the heavy getPage (which also renders
-          // Markdown + subpages) just to read one field.
-          try {
-            const res = (await client.getPageRaw(pageId)) as {
-              title?: string;
-            } | null;
-            title = res?.title ?? undefined;
-          } catch {
-            // Title is optional — omit it when the page can't be fetched.
-          }
-        }
-        return { count, title };
-      },
+      probe: createListCommentsProbe(
+        client as unknown as Parameters<typeof createListCommentsProbe>[0],
+      ),
     });
 
     return wrapInAppToolsWithCap(

apps/server/src/core/ai-chat/tools/comment-signal-inapp.spec.ts

@@ -21,7 +21,10 @@ import { SHARED_TOOL_SPECS } from '../../../../../../packages/mcp/src/tool-specs
 // The REAL shared tracker factory, imported from source (same cross-boundary
 // approach the tool-specs spec uses) so the in-app wiring is exercised against
 // exactly the watermark/debounce/injection-safe logic the package ships.
-import { createCommentSignalTracker } from '../../../../../../packages/mcp/src/comment-signal';
+import {
+  createCommentSignalTracker,
+  createListCommentsProbe,
+} from '../../../../../../packages/mcp/src/comment-signal';
 // The REAL client-side citation extractor: proves that the passive signal does
 // NOT strip a tool's citations (the #417 in-app regression this spec guards).
 import { toolCitations } from '../../../../../../apps/client/src/features/ai-chat/utils/tool-parts';
@@ -284,9 +287,13 @@ describe('AiChatToolsService forUser + comment signal (real tracker)', () => {
         return fakeClient as DocmostClientLike;
       } as unknown as loader.DocmostClientCtor,
       sharedToolSpecs: SHARED_TOOL_SPECS as unknown as Record<string, loader.SharedToolSpec>,
-      // Wire the REAL factory so the in-app path is exercised end to end.
+      // Wire the REAL factories so the in-app path is exercised end to end —
+      // including the shared count-source probe (#494) the service now builds the
+      // tracker's `probe` from.
       createCommentSignalTracker:
         createCommentSignalTracker as unknown as loader.CommentSignalTrackerFactory,
+      createListCommentsProbe:
+        createListCommentsProbe as unknown as loader.CreateListCommentsProbeFn,
       // Pure no-network draw.io helpers (#424) — required on the loader return;
       // this comment-signal test doesn't exercise them, so no-op stubs suffice.
       searchShapes: (() => []) as unknown as loader.SearchShapesFn,

apps/server/src/core/ai-chat/tools/docmost-client.loader.ts

@@ -150,6 +150,27 @@ export type CommentSignalTrackerFactory = (options: {
   debounceMs?: number;
 }) => CommentSignalTrackerLike;
 
+/**
+ * Local mirror of `@docmost/mcp`'s `createListCommentsProbe` (#494): the SHARED
+ * count-source probe both hosts use, so the in-app probe body is no longer a
+ * hand-copy of the standalone MCP one. Given a client with the light comment feed
+ * + raw-page-title reads, it returns the tracker's `probe` (count comments newer
+ * than the watermark, label a hit with the page title). Loosely typed at this
+ * cross-package boundary, like the rest of this loader.
+ */
+export type CreateListCommentsProbeFn = (client: {
+  listComments(
+    pageId: string,
+    includeResolved: boolean,
+  ): Promise<{ items: Array<{ createdAt?: string | null }> }>;
+  getPageRaw(
+    pageId: string,
+  ): Promise<{ title?: string | null } | null | undefined>;
+}) => (
+  pageId: string,
+  sinceMs: number,
+) => Promise<CommentSignalProbeResultLike>;
+
 // Pure, no-network draw.io helpers (#424). These are plain functions on the
 // module (NOT DocmostClient methods) — the in-app AI-SDK service calls them
 // directly to wire drawioShapes / drawioGuide, mirroring the MCP server.
@@ -170,6 +191,10 @@ interface DocmostMcpModule {
   // loader in unit tests. The in-app layer treats an absent factory as "signal
   // disabled" — a pure no-op that leaves tool results byte-identical.
   createCommentSignalTracker?: CommentSignalTrackerFactory;
+  // Optional (#494): the shared count-source probe factory. Absent on a pre-#494
+  // build or a mocked loader; the in-app layer only builds a probe when the
+  // signal factory above is also present.
+  createListCommentsProbe?: CreateListCommentsProbeFn;
   // Optional (#447): a deterministic hash of the tool-specs registry content,
   // generated into build/ by the package's build. Absent on a pre-#447 build (or
   // the mocked loader in unit tests) — the stale-check below is a NO-OP when it
@@ -284,6 +309,7 @@ export async function loadDocmostMcp(): Promise<{
   DocmostClient: DocmostClientCtor;
   sharedToolSpecs: Record<string, SharedToolSpec>;
   createCommentSignalTracker?: CommentSignalTrackerFactory;
+  createListCommentsProbe?: CreateListCommentsProbeFn;
   searchShapes: SearchShapesFn;
   getGuideSection: GetGuideSectionFn;
 }> {
@@ -331,6 +357,9 @@ export async function loadDocmostMcp(): Promise<{
     // Optional: forwarded when present so the in-app layer can build the passive
     // comment signal (#417); undefined on a stale build => signal disabled.
     createCommentSignalTracker: mod.createCommentSignalTracker,
+    // Optional (#494): the shared count-source probe factory; undefined on a
+    // stale build => the in-app layer falls back to no signal.
+    createListCommentsProbe: mod.createListCommentsProbe,
     // Pure no-network draw.io helpers (#424); not client methods.
     searchShapes: mod.searchShapes,
     getGuideSection: mod.getGuideSection,

apps/server/src/core/comment/comment.controller.ts

@@ -16,6 +16,7 @@ import { UpdateCommentDto } from './dto/update-comment.dto';
 import { ResolveCommentDto } from './dto/resolve-comment.dto';
 import { ApplySuggestionDto } from './dto/apply-suggestion.dto';
 import { DismissSuggestionDto } from './dto/dismiss-suggestion.dto';
+import { ResyncSuggestionAnchorDto } from './dto/resync-suggestion-anchor.dto';
 import { PageIdDto, CommentIdDto } from './dto/comments.input';
 import { AuthUser } from '../../common/decorators/auth-user.decorator';
 import { AuthWorkspace } from '../../common/decorators/auth-workspace.decorator';
@@ -235,6 +236,39 @@ export class CommentController {
     return this.commentService.applySuggestion(comment, user, provenance);
   }
 
+  @HttpCode(HttpStatus.OK)
+  @Post('resync-suggestion-anchor')
+  async resyncSuggestionAnchor(
+    @Body() dto: ResyncSuggestionAnchorDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    const comment = await this.commentRepo.findById(dto.commentId, {
+      includeCreator: true,
+      includeResolvedBy: true,
+    });
+    if (!comment) {
+      throw new NotFoundException('Comment not found');
+    }
+
+    const page = await this.pageRepo.findById(comment.pageId);
+    if (!page || page.deletedAt) {
+      throw new NotFoundException('Page not found');
+    }
+
+    // Authorize BEFORE revealing structural detail (mirrors apply/dismiss).
+    // Re-anchoring does NOT change the page text — it only corrects the stored
+    // selection metadata — so the page-level gate is comment access. The service
+    // further restricts it to the suggestion's own author.
+    await this.pageAccessService.validateCanComment(page, user, workspace.id);
+
+    return this.commentService.resyncSuggestionAnchor(
+      comment,
+      dto.selection,
+      user,
+    );
+  }
+
   @HttpCode(HttpStatus.OK)
   @Post('dismiss-suggestion')
   async dismissSuggestion(

apps/server/src/core/comment/comment.service.apply-suggestion.spec.ts

@@ -146,11 +146,19 @@ describe('CommentService — applySuggestion', () => {
       'page-1',
       expect.objectContaining({ operation: 'commentDeleted', commentId: 'c-1' }),
     );
+    // #496: hard-deleted row → the audit payload is the only surviving record.
     expect(auditService.log).toHaveBeenCalledWith(
       expect.objectContaining({
         event: AuditEvent.COMMENT_SUGGESTION_APPLIED,
         resourceType: AuditResource.COMMENT,
         resourceId: 'c-1',
+        metadata: expect.objectContaining({
+          pageId: 'page-1',
+          suggestedText: 'new text',
+          selection: 'old text',
+          commentAuthor: 'user-1',
+          decidedBy: 'user-1',
+        }),
       }),
     );
     expect(result.outcome).toBe('deleted');
@@ -189,17 +197,25 @@ describe('CommentService — applySuggestion', () => {
     expect(resolvePatch.resolvedAt).toBeInstanceOf(Date);
     expect(resolvePatch.resolvedById).toBe('user-1');
 
-    // NOT deleted; broadcast an update, not a deletion.
+    // NOT deleted.
     expect(commentRepo.deleteComment).not.toHaveBeenCalled();
     expect(collaborationGateway.handleYjsEvent).not.toHaveBeenCalledWith(
       'deleteCommentMark',
       expect.anything(),
       expect.anything(),
     );
+    // #496 dedup: resolveComment broadcasts `commentResolved` with the enriched
+    // row; finalize must NOT ALSO emit a redundant `commentUpdated`. So the
+    // thread receives exactly ONE resolve broadcast and no update broadcast.
     expect(wsService.emitCommentEvent).toHaveBeenCalledWith(
       'space-1',
       'page-1',
-      expect.objectContaining({ operation: 'commentUpdated', comment: UPDATED }),
+      expect.objectContaining({ operation: 'commentResolved', comment: UPDATED }),
+    );
+    expect(wsService.emitCommentEvent).not.toHaveBeenCalledWith(
+      'space-1',
+      'page-1',
+      expect.objectContaining({ operation: 'commentUpdated' }),
     );
 
     expect(auditService.log).toHaveBeenCalledWith(
@@ -211,6 +227,36 @@ describe('CommentService — applySuggestion', () => {
     expect(result.outcome).toBe('resolved');
   });
 
+  it('re-entry: already applied+resolved WITH replies → emits commentUpdated (dedup does not over-suppress)', async () => {
+    // suggestionAppliedAt set → idempotent finalize; resolvedAt set → resolveComment
+    // is skipped, so there is NO commentResolved broadcast. The applied-stamp state
+    // must still reach clients via a single commentUpdated.
+    const { service, wsService } = makeService(
+      { applied: false, currentText: 'new text' },
+      true,
+    );
+
+    await service.applySuggestion(
+      suggestionComment({
+        suggestionAppliedAt: new Date(),
+        resolvedAt: new Date(),
+      }),
+      user(),
+    );
+
+    expect(wsService.emitCommentEvent).toHaveBeenCalledWith(
+      'space-1',
+      'page-1',
+      expect.objectContaining({ operation: 'commentUpdated', comment: UPDATED }),
+    );
+    // Nothing resolved this time (already resolved) → no resolve broadcast.
+    expect(wsService.emitCommentEvent).not.toHaveBeenCalledWith(
+      'space-1',
+      'page-1',
+      expect.objectContaining({ operation: 'commentResolved' }),
+    );
+  });
+
   // --- error / rejection branches -----------------------------------------
 
   it('applied=false and currentText differs → ConflictException with currentText in payload', async () => {

apps/server/src/core/comment/comment.service.dismiss-suggestion.spec.ts

@@ -107,11 +107,21 @@ describe('CommentService — dismissSuggestion', () => {
       'page-1',
       expect.objectContaining({ operation: 'commentDeleted', commentId: 'c-1' }),
     );
+    // #496: the row is hard-deleted, so the audit payload must carry the
+    // decision's substance (what was suggested, the anchored text, who authored
+    // it, who decided) — it is the only surviving record.
     expect(auditService.log).toHaveBeenCalledWith(
       expect.objectContaining({
         event: AuditEvent.COMMENT_SUGGESTION_DISMISSED,
         resourceType: AuditResource.COMMENT,
         resourceId: 'c-1',
+        metadata: expect.objectContaining({
+          pageId: 'page-1',
+          suggestedText: 'new text',
+          selection: 'old text',
+          commentAuthor: 'user-1',
+          decidedBy: 'user-1',
+        }),
       }),
     );
     expect(result.outcome).toBe('deleted');

apps/server/src/core/comment/comment.service.resync-anchor.spec.ts

@@ -0,0 +1,126 @@
+import { BadRequestException, ForbiddenException } from '@nestjs/common';
+import { CommentService } from './comment.service';
+
+/**
+ * Coverage for CommentService.resyncSuggestionAnchor (#496): re-anchoring a
+ * suggestion's stored selection (== apply-time expectedText) to the live-doc
+ * substring. The service is built directly with jest-mocked deps (the
+ * @InjectQueue tokens can't be resolved by Test.createTestingModule — see the
+ * sibling specs).
+ */
+describe('CommentService — resyncSuggestionAnchor', () => {
+  const UPDATED = { id: 'c-1', selection: 'new anchor', __updated: true } as any;
+
+  function makeService() {
+    const commentRepo: any = {
+      updateComment: jest.fn(async () => undefined),
+      findById: jest.fn(async () => UPDATED),
+    };
+    const service = new CommentService(
+      commentRepo,
+      {} as any,
+      { emitCommentEvent: jest.fn() } as any,
+      {} as any,
+      { add: jest.fn() } as any,
+      { add: jest.fn() } as any,
+      { log: jest.fn() } as any,
+    );
+    return { service, commentRepo };
+  }
+
+  const suggestion = (over?: Partial<any>): any => ({
+    id: 'c-1',
+    creatorId: 'user-1',
+    parentCommentId: null,
+    selection: 'old anchor',
+    suggestedText: 'new text',
+    suggestionAppliedAt: null,
+    resolvedAt: null,
+    ...over,
+  });
+  const user = (over?: Partial<any>): any => ({ id: 'user-1', ...over });
+
+  it('persists the new selection and returns the enriched comment', async () => {
+    const { service, commentRepo } = makeService();
+
+    const out = await service.resyncSuggestionAnchor(
+      suggestion(),
+      'new anchor',
+      user(),
+    );
+
+    expect(commentRepo.updateComment).toHaveBeenCalledWith(
+      { selection: 'new anchor' },
+      'c-1',
+    );
+    expect(out).toBe(UPDATED);
+  });
+
+  it('is idempotent: no write when the anchor already matches', async () => {
+    const { service, commentRepo } = makeService();
+
+    const out = await service.resyncSuggestionAnchor(
+      suggestion({ selection: 'same' }),
+      'same',
+      user(),
+    );
+
+    expect(commentRepo.updateComment).not.toHaveBeenCalled();
+    expect(out).toEqual(suggestion({ selection: 'same' }));
+  });
+
+  it('rejects a non-author (only the suggestion owner may re-anchor)', async () => {
+    const { service, commentRepo } = makeService();
+    await expect(
+      service.resyncSuggestionAnchor(suggestion(), 'new anchor', user({ id: 'other' })),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(commentRepo.updateComment).not.toHaveBeenCalled();
+  });
+
+  it('rejects a reply / a comment with no suggestion', async () => {
+    const { service } = makeService();
+    await expect(
+      service.resyncSuggestionAnchor(
+        suggestion({ parentCommentId: 'p-1' }),
+        'x',
+        user(),
+      ),
+    ).rejects.toBeInstanceOf(BadRequestException);
+    await expect(
+      service.resyncSuggestionAnchor(
+        suggestion({ suggestedText: null }),
+        'x',
+        user(),
+      ),
+    ).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it('rejects re-anchoring an already applied or resolved suggestion', async () => {
+    const { service } = makeService();
+    await expect(
+      service.resyncSuggestionAnchor(
+        suggestion({ suggestionAppliedAt: new Date() }),
+        'x',
+        user(),
+      ),
+    ).rejects.toBeInstanceOf(BadRequestException);
+    await expect(
+      service.resyncSuggestionAnchor(
+        suggestion({ resolvedAt: new Date() }),
+        'x',
+        user(),
+      ),
+    ).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it('rejects a no-op selection equal to the suggested text', async () => {
+    const { service } = makeService();
+    await expect(
+      service.resyncSuggestionAnchor(
+        suggestion({ suggestedText: 'new text' }),
+        'new text',
+        user(),
+      ),
+    ).rejects.toBeInstanceOf(BadRequestException);
+  });
+});

apps/server/src/core/comment/comment.service.ts

@@ -370,6 +370,76 @@ export class CommentService {
     return updatedComment;
   }
 
+  /**
+   * Re-sync a suggestion's stored `selection` (== apply-time expectedText) to the
+   * RAW substring the inline mark actually covers in the LIVE document (#496).
+   *
+   * The MCP client creates the comment from a DEBOUNCED REST snapshot, then
+   * anchors the mark in the live collab doc. When the two disagree (the doc moved
+   * on in the debounce window) the stored selection no longer equals the marked
+   * text, so EVERY apply 409s ("the commented text changed"). After anchoring the
+   * client re-reads the exact marked substring and calls this to store it, making
+   * apply's strict equality hold.
+   *
+   * Only meaningful for an un-settled top-level suggestion authored by the
+   * caller: applying/resolving freezes the anchor, and a reply-carrying thread is
+   * preserved rather than mutated. The new text must still differ from the
+   * suggestion (else "apply" would be a no-op), preserving create()'s invariant.
+   */
+  async resyncSuggestionAnchor(
+    comment: Comment,
+    selection: string,
+    user: User,
+  ): Promise<Comment> {
+    if (comment.creatorId !== user.id) {
+      throw new ForbiddenException(
+        'You can only re-anchor your own suggestion',
+      );
+    }
+    if (comment.parentCommentId) {
+      throw new BadRequestException(
+        'Only a top-level comment can carry a suggested edit',
+      );
+    }
+    if (!comment.suggestedText) {
+      throw new BadRequestException('This comment has no suggested edit');
+    }
+    // A settled suggestion's anchor is frozen: re-anchoring an applied/resolved
+    // thread is meaningless and could resurrect a stale expectedText.
+    if (comment.suggestionAppliedAt || comment.resolvedAt) {
+      throw new BadRequestException(
+        'Cannot re-anchor a suggestion that was already applied or resolved',
+      );
+    }
+    const trimmed = selection.trim();
+    if (trimmed.length === 0) {
+      throw new BadRequestException('The re-anchored selection cannot be empty');
+    }
+    // Same no-op guard as create(): the suggestion must differ from the text it
+    // replaces, or apply becomes indistinguishable from already-applied.
+    if (trimmed === comment.suggestedText.trim()) {
+      throw new BadRequestException(
+        'A suggested edit must differ from the selected text',
+      );
+    }
+
+    // Idempotent: nothing to persist when the anchor already matches.
+    if (comment.selection === selection) {
+      return comment;
+    }
+
+    await this.commentRepo.updateComment({ selection }, comment.id);
+
+    const updatedComment = await this.commentRepo.findById(comment.id, {
+      includeCreator: true,
+      includeResolvedBy: true,
+    });
+
+    // Re-anchoring only corrects stored metadata; it does not change the page
+    // text or the comment body, so no ws broadcast / notification is warranted.
+    return updatedComment;
+  }
+
   /**
    * Apply the suggested edit carried by a top-level inline comment: atomically
    * replace the text under the comment mark in the collaborative document with
@@ -524,7 +594,7 @@ export class CommentService {
         resourceType: AuditResource.COMMENT,
         resourceId: comment.id,
         spaceId: comment.spaceId,
-        metadata: { pageId: comment.pageId },
+        metadata: this.suggestionAuditMetadata(comment, user),
       });
       return { ...updatedComment, outcome: 'resolved' };
     }
@@ -538,7 +608,7 @@ export class CommentService {
       resourceType: AuditResource.COMMENT,
       resourceId: comment.id,
       spaceId: comment.spaceId,
-      metadata: { pageId: comment.pageId },
+      metadata: this.suggestionAuditMetadata(comment, user),
     });
     return settled;
   }
@@ -577,8 +647,10 @@ export class CommentService {
 
       // Auto-resolve the thread. resolveComment handles the resolve mark, its ws
       // broadcast and the resolve notification. Stay defensive on re-entry.
+      let didResolveBroadcast = false;
       if (!comment.resolvedAt) {
         await this.resolveComment(comment, true, user, provenance);
+        didResolveBroadcast = true;
       }
 
       const updatedComment = await this.commentRepo.findById(comment.id, {
@@ -586,18 +658,27 @@ export class CommentService {
         includeResolvedBy: true,
       });
 
-      this.wsService.emitCommentEvent(comment.spaceId, comment.pageId, {
-        operation: 'commentUpdated',
-        pageId: comment.pageId,
-        comment: updatedComment,
-      });
+      // #496 dedup: resolveComment already broadcast `commentResolved` carrying
+      // the fully-enriched row (the applied stamps were persisted above, before
+      // that call, so its re-read reflects them). Emitting `commentUpdated` here
+      // too made the client receive TWO events for one apply. Broadcast the
+      // update ONLY when we did NOT resolve — i.e. the rare re-entry on an
+      // already-resolved thread, where the applied-stamp change still needs a
+      // broadcast and resolveComment did not run.
+      if (!didResolveBroadcast) {
+        this.wsService.emitCommentEvent(comment.spaceId, comment.pageId, {
+          operation: 'commentUpdated',
+          pageId: comment.pageId,
+          comment: updatedComment,
+        });
+      }
 
       this.auditService.log({
         event: AuditEvent.COMMENT_SUGGESTION_APPLIED,
         resourceType: AuditResource.COMMENT,
         resourceId: comment.id,
         spaceId: comment.spaceId,
-        metadata: { pageId: comment.pageId },
+        metadata: this.suggestionAuditMetadata(comment, user),
       });
 
       return { ...updatedComment, outcome: 'resolved' };
@@ -616,7 +697,7 @@ export class CommentService {
       resourceType: AuditResource.COMMENT,
       resourceId: comment.id,
       spaceId: comment.spaceId,
-      metadata: { pageId: comment.pageId },
+      metadata: this.suggestionAuditMetadata(comment, user),
     });
 
     return settled;
@@ -627,14 +708,17 @@ export class CommentService {
    * inline `comment` anchor mark, then ATOMICALLY hard-delete the row only if it
    * is still childless. Shared by the apply/dismiss no-replies branches (#329).
    *
-   * ORDER MATTERS: the anchor mark is removed FIRST and FATALLY (mirrors
-   * applySuggestion, which mutates the doc before writing the DB). The row
-   * delete is irreversible, so if the mark removal fails — including the
-   * COLLAB_DISABLE_REDIS "no live instance" hard-error — we must NOT delete the
-   * row and report success, or the document is left with a permanent orphan
-   * anchor pointing at a comment that no longer exists (the exact data-integrity
-   * bug #329 targets). Let the exception propagate (→ 5xx); the operation is
-   * then repeatable with row + mark still consistent.
+   * ORDER MATTERS (updated #399 → #496): what runs FIRST and FATALLY here is the
+   * mark-removal ENQUEUE (a fast, durable Redis add), NOT the mark op itself.
+   * deleteCommentMark awaits only the enqueue, so a failed add throws BEFORE the
+   * irreversible row delete — the row + mark stay consistent and the operation is
+   * repeatable. The actual anchor strip then runs off the HTTP path in the worker
+   * (idempotent, 3 retries). Only an EXHAUSTED-retries job could leave the doc
+   * with an orphan anchor pointing at a hard-deleted comment (the data-integrity
+   * bug #329 targets); that residual divergence is now self-healed by the
+   * resolve/unresolve mark worker, which strips an orphan mark whenever its
+   * comment row is gone (#496), and it is meanwhile VISIBLE via BullMQ failed-job
+   * metrics rather than a silently-swallowed warn.
    *
    * RACE (#338 F4): the caller read `hasChildren` BEFORE the (slow) mark
    * removal, so a reply can land in that window. `comments.parent_comment_id` is
@@ -732,6 +816,27 @@ export class CommentService {
     return this.generalQueue.add(QueueJob.COMMENT_MARK_UPDATE, jobData);
   }
 
+  /**
+   * Build the audit metadata for a suggestion apply/dismiss decision (#496).
+   * The subject comment is HARD-DELETED on the childless path, so the audit row
+   * is the only surviving record — capture the decision's substance (what was
+   * suggested, the anchored text it replaced, who authored it, who decided)
+   * before the row can vanish. `decidedBy` is the acting user; `commentAuthor`
+   * is the suggestion's creator.
+   */
+  private suggestionAuditMetadata(
+    comment: Comment,
+    user: User,
+  ): Record<string, any> {
+    return {
+      pageId: comment.pageId,
+      suggestedText: comment.suggestedText ?? null,
+      selection: comment.selection ?? null,
+      commentAuthor: comment.creatorId ?? null,
+      decidedBy: user.id,
+    };
+  }
+
   private async queueCommentNotification(
     content: any,
     oldMentionIds: string[],

apps/server/src/core/comment/dto/resync-suggestion-anchor.dto.ts

@@ -0,0 +1,20 @@
+import { IsString, IsUUID, MaxLength, MinLength } from 'class-validator';
+
+/**
+ * #496: after the MCP client anchors a suggestion in the LIVE collab doc, it
+ * re-reads the exact substring under the new mark and syncs it here as the
+ * comment's stored `selection` (== apply-time expectedText). Fixes the perpetual
+ * 409 where expectedText came from a debounced REST snapshot while the mark sat
+ * in the live doc.
+ */
+export class ResyncSuggestionAnchorDto {
+  @IsUUID()
+  commentId: string;
+
+  // The raw substring the mark now covers in the live document. Bounded like the
+  // create-time selection (2000) so a legitimate anchored span is never cut.
+  @IsString()
+  @MinLength(1)
+  @MaxLength(2000)
+  selection: string;
+}

apps/server/src/core/page/dto/move-page.dto.spec.ts

@@ -17,9 +17,10 @@ import { MovePageDto } from './move-page.dto';
 //     a valid ordering key the server itself generated would be refused on move.
 //
 // The tests below assert the CORRECT contract: any key the generator can produce
-// must satisfy the DTO. The genuinely-failing case is marked `test.failing` so the
-// suite stays green while locking the bug; it flips red (alerting us) once the DTO
-// bounds are widened to cover the generator's real range.
+// must satisfy the DTO. FIXED (#495 item 9): the DTO now validates `position` by
+// CHARSET ([0-9A-Za-z], the generator's base-62 alphabet) instead of the wrong
+// @MaxLength(12) length bound, so dense between-inserts are accepted; the former
+// `test.failing` bug-lock is now a passing assertion.
 
 function constraintErrors(position: unknown) {
   const dto = plainToInstance(MovePageDto, {
@@ -47,24 +48,33 @@ describe('MovePageDto.position vs generateJitteredKeyBetween parity', () => {
     expect(hasError(errors, 'position')).toBe(false);
   });
 
-  // BUG LOCK: dense between-inserts produce keys longer than 12 chars, which
-  // MaxLength(12) rejects even though they are valid ordering keys. This SHOULD
-  // pass; it currently fails. Flips green when the DTO bound is fixed.
-  test.failing(
-    'accepts dense between-inserted keys (currently rejected by MaxLength(12))',
-    async () => {
-      let lo = generateJitteredKeyBetween(null, null);
-      let hi = generateJitteredKeyBetween(lo, null);
-      // Repeatedly insert just above `lo`, shrinking the gap so the key grows.
-      let longest = lo;
-      for (let i = 0; i < 40; i++) {
-        const mid = generateJitteredKeyBetween(lo, hi);
-        if (mid.length > longest.length) longest = mid;
-        hi = mid;
-      }
-      expect(longest.length).toBeGreaterThan(12); // sanity: we produced a long key
-      const errors = await constraintErrors(longest);
-      expect(hasError(errors, 'position')).toBe(false);
-    },
-  );
+  // FIXED: dense between-inserts produce keys longer than 12 chars, which the old
+  // MaxLength(12) rejected even though they are valid ordering keys. Now accepted.
+  it('accepts dense between-inserted keys longer than 12 chars', async () => {
+    let lo = generateJitteredKeyBetween(null, null);
+    let hi = generateJitteredKeyBetween(lo, null);
+    // Repeatedly insert just above `lo`, shrinking the gap so the key grows. The
+    // generator is JITTERED (random), so use enough iterations that the longest
+    // key reliably clears the old 12-char bound: measured min-over-50-trials is
+    // ~11 at 40 iterations (flaky) but ~36 at 200 (robust margin).
+    let longest = lo;
+    for (let i = 0; i < 200; i++) {
+      const mid = generateJitteredKeyBetween(lo, hi);
+      if (mid.length > longest.length) longest = mid;
+      hi = mid;
+    }
+    expect(longest.length).toBeGreaterThan(12); // sanity: we produced a long key
+    const errors = await constraintErrors(longest);
+    expect(hasError(errors, 'position')).toBe(false);
+  });
+
+  // The charset guard replaces the length bound: reject anything outside the
+  // generator's [0-9A-Za-z] alphabet (control chars, separators, injection) and
+  // the empty string, while still accepting every real key.
+  it('rejects a position with characters outside the fractional-index alphabet', async () => {
+    for (const bad of ['a0/b', 'a b', 'a\n0', 'a.b', '', "a';--"]) {
+      const errors = await constraintErrors(bad);
+      expect(hasError(errors, 'position')).toBe(true);
+    }
+  });
 });

apps/server/src/core/page/dto/move-page.dto.ts

@@ -1,8 +1,8 @@
 import {
   IsString,
   IsOptional,
-  MinLength,
   MaxLength,
+  Matches,
   IsNotEmpty,
 } from 'class-validator';
 
@@ -10,9 +10,19 @@ export class MovePageDto {
   @IsString()
   pageId: string;
 
+  // `position` is a fractional-indexing key from `generateJitteredKeyBetween`
+  // (the SAME generator page.service uses). Validate by CHARSET, not length: the
+  // generator's default base-62 alphabet is [0-9A-Za-z], and DENSE between-inserts
+  // legitimately grow a key well past a dozen chars (measured >40), so the old
+  // @MinLength(5)/@MaxLength(12) bounds wrongly 400'd valid ordering keys the
+  // server itself produced (Gitea #139 item 6). The charset regex rejects control
+  // chars / separators / injection, and a generous MaxLength stays only as a
+  // DoS guard — far above any realistic key, so it never rejects a real move.
   @IsString()
-  @MinLength(5)
-  @MaxLength(12)
+  @Matches(/^[0-9A-Za-z]+$/, {
+    message: 'position must be a fractional-index key ([0-9A-Za-z])',
+  })
+  @MaxLength(256)
   position: string;
 
   @IsOptional()

apps/server/src/core/page/dto/page-identity.dto.spec.ts

@@ -0,0 +1,49 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import { PageIdDto } from './page.dto';
+
+// #435: PageIdDto.pageId carries a page's DOUBLE identity (internal UUID OR
+// public 10-char slugId), both as bare strings. The DTO must accept exactly
+// those two FORMATS and reject a malformed / swapped identity at the boundary.
+async function pageIdErrors(pageId: unknown) {
+  const dto = plainToInstance(PageIdDto, { pageId });
+  const errors = await validate(dto as object);
+  return errors.some((e) => e.property === 'pageId');
+}
+
+const UUID = '019f499a-9f8c-7d68-b7be-ce100d7c6c56';
+const SLUG = 'aB3xQ7kR2p';
+
+describe('PageIdDto pageId format validation', () => {
+  it('accepts a canonical page UUID', async () => {
+    expect(await pageIdErrors(UUID)).toBe(false);
+  });
+
+  it('accepts a 10-char slugId', async () => {
+    expect(await pageIdErrors(SLUG)).toBe(false);
+  });
+
+  it('rejects a truncated / wrong-length slug', async () => {
+    expect(await pageIdErrors('aB3xQ7kR2')).toBe(true); // 9 chars
+    expect(await pageIdErrors('aB3xQ7kR2pX')).toBe(true); // 11 chars
+  });
+
+  it('rejects a slug with an illegal character', async () => {
+    expect(await pageIdErrors('aB3xQ7kR2!')).toBe(true);
+  });
+
+  it('rejects a full URL / path-shaped identity (not the bare id)', async () => {
+    expect(await pageIdErrors(`my-page-title-${SLUG}`)).toBe(true);
+    expect(await pageIdErrors(`https://x/p/${SLUG}`)).toBe(true);
+  });
+
+  it('rejects a malformed UUID', async () => {
+    expect(await pageIdErrors('019f499a-9f8c-7d68-b7be')).toBe(true);
+    expect(await pageIdErrors('not-a-uuid-at-all-really')).toBe(true);
+  });
+
+  it('rejects an empty string', async () => {
+    expect(await pageIdErrors('')).toBe(true);
+  });
+});

apps/server/src/core/page/dto/page-identity.validator.ts

@@ -0,0 +1,39 @@
+import { applyDecorators } from '@nestjs/common';
+import { Matches, ValidationOptions } from 'class-validator';
+
+/**
+ * A page identity at the API boundary is EITHER the internal page UUID or the
+ * public 10-char slugId (page.repo.findById matches a non-UUID input as a
+ * slugId). Both arrive as bare strings, which is exactly how the two got swapped
+ * silently (incident family #435). This regex pins the two accepted FORMATS so a
+ * malformed / cross-wired identity (a truncated slug, a full URL, an email, an
+ * id from another entity kind that isn't even shaped like either) is rejected at
+ * the boundary instead of falling through to a confusing 404.
+ *
+ *   - UUID:    canonical 8-4-4-4-12 hex (version-agnostic — page ids are UUIDv7,
+ *              so only the shape/length is enforced, matching the MCP's UUID_RE
+ *              and the server's isValidUUID acceptance).
+ *   - slugId:  exactly 10 chars over [0-9A-Za-z] (nanoid `generateSlugId`).
+ *
+ * The two are disjoint (a UUID is 36 chars WITH dashes, a slugId 10 chars
+ * WITHOUT), so a value can only satisfy one branch.
+ */
+export const PAGE_ID_OR_SLUG_ID_REGEX =
+  /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9A-Za-z]{10})$/i;
+
+/**
+ * Validate that a DTO string field is a well-formed page identity (page UUID OR
+ * 10-char slugId). Composed decorator so the same format rule is applied
+ * consistently wherever a DTO accepts a `pageId` that may be either form.
+ */
+export function IsPageIdOrSlugId(
+  validationOptions?: ValidationOptions,
+): PropertyDecorator {
+  return applyDecorators(
+    Matches(PAGE_ID_OR_SLUG_ID_REGEX, {
+      message:
+        'pageId must be a page UUID or a 10-character slugId',
+      ...validationOptions,
+    }),
+  );
+}

apps/server/src/core/page/dto/page.dto.ts

@@ -9,10 +9,16 @@ import {
 import { Transform } from 'class-transformer';
 
 import { ContentFormat } from './create-page.dto';
+import { IsPageIdOrSlugId } from './page-identity.validator';
 
 export class PageIdDto {
   @IsString()
   @IsNotEmpty()
+  // Format-validate the double identity (#435): accept only a page UUID or a
+  // 10-char slugId so a malformed / swapped identity is rejected at the boundary
+  // rather than passed to the repo as a bare string. Base for PageInfoDto,
+  // DeletePageDto, BacklinksListDto, AddLabelsDto/RemoveLabelDto, etc.
+  @IsPageIdOrSlugId()
   pageId: string;
 }
 

apps/server/src/core/page/services/page.service.ts

@@ -53,8 +53,10 @@ import {
   extractPageSlugId,
 } from '../../../integrations/export/utils';
 import { canonicalizeFootnotes } from '@docmost/editor-ext';
-import { markdownToProseMirror } from '@docmost/prosemirror-markdown';
-import { normalizeForeignMarkdown } from '../../../integrations/import/utils/foreign-markdown';
+import {
+  markdownToProseMirror,
+  normalizeForeignMarkdown,
+} from '@docmost/prosemirror-markdown';
 import { WatcherService } from '../../watcher/watcher.service';
 import { sql } from 'kysely';
 import { TransclusionService } from '../transclusion/transclusion.service';

apps/server/src/core/page/services/spec/temporary-note-cleanup.service.spec.ts

@@ -1,19 +1,38 @@
 import { TemporaryNoteCleanupService } from '../temporary-note-cleanup.service';
 
 /**
- * Chainable Kysely stub that records every `.where(...)` call so the test can
- * assert the sweep only selects armed, expired, not-yet-trashed notes. The
- * terminal `.execute()` resolves the configured expired rows (the batch SELECT);
- * `.executeTakeFirst()` resolves the per-row deadline re-read done just before
- * each `removePage`. By default the re-read reports the note as still armed and
- * still expired (epoch deadline < now), so the sweep proceeds to delete it;
- * tests override `reReadFirst` to simulate a concurrent "Make permanent".
+ * Chainable Kysely stub for the temporary-note sweep.
+ *
+ * `this.db` serves the non-locking candidate SELECT (selectFrom/select/where/
+ * limit/execute -> the configured expired rows) AND `.transaction().execute(cb)`,
+ * which runs `cb` with a separate `trx` builder. The `trx` builder serves the
+ * per-row LOCKED re-check (selectFrom/select/where/forUpdate/skipLocked/
+ * executeTakeFirst). `lockedRows` drives what that locked re-check returns per
+ * candidate — an id/creator/workspace row means "still expired, delete it";
+ * `undefined` means the predicate no longer matched (made permanent / re-armed /
+ * already trashed) or the row was SKIP-LOCKED by another worker, so it is skipped.
  */
-function makeDbStub(expiredRows: any[]) {
+function makeDbStub(expiredRows: any[], lockedRows?: any[]) {
   const whereCalls: any[][] = [];
-  const reReadFirst = jest
-    .fn()
-    .mockResolvedValue({ temporaryExpiresAt: new Date(0), deletedAt: null });
+  const locked = [
+    ...(lockedRows ??
+      expiredRows.map((r) => ({
+        id: r.id,
+        creatorId: r.creatorId,
+        workspaceId: r.workspaceId,
+      }))),
+  ];
+  const lockedTakeFirst = jest.fn(() => Promise.resolve(locked.shift()));
+  const forUpdate = jest.fn(() => trxBuilder);
+  const skipLocked = jest.fn(() => trxBuilder);
+  const trxBuilder: any = {
+    selectFrom: jest.fn(() => trxBuilder),
+    select: jest.fn(() => trxBuilder),
+    where: jest.fn(() => trxBuilder),
+    forUpdate,
+    skipLocked,
+    executeTakeFirst: lockedTakeFirst,
+  };
   const builder: any = {
     selectFrom: jest.fn(() => builder),
     select: jest.fn(() => builder),
@@ -23,9 +42,11 @@ function makeDbStub(expiredRows: any[]) {
     }),
     limit: jest.fn(() => builder),
     execute: jest.fn().mockResolvedValue(expiredRows),
-    executeTakeFirst: reReadFirst,
+    transaction: jest.fn(() => ({
+      execute: (cb: (trx: any) => Promise<any>) => Promise.resolve(cb(trxBuilder)),
+    })),
   };
-  return { builder, whereCalls, reReadFirst };
+  return { builder, whereCalls, lockedTakeFirst, forUpdate, skipLocked };
 }
 
 describe('TemporaryNoteCleanupService.sweepExpiredTemporaryNotes', () => {
@@ -52,20 +73,36 @@ describe('TemporaryNoteCleanupService.sweepExpiredTemporaryNotes', () => {
     expect(builder.limit.mock.calls[0][0]).toBeGreaterThan(0);
   });
 
-  it('soft-deletes each expired note via removePage, attributed to its creator', async () => {
+  it('soft-deletes each expired note via removePage under a row lock, attributed to its creator', async () => {
     const expired = [
       { id: 'p1', creatorId: 'u1', workspaceId: 'w1' },
       { id: 'p2', creatorId: 'u2', workspaceId: 'w1' },
     ];
-    const { builder } = makeDbStub(expired);
+    const { builder, forUpdate, skipLocked } = makeDbStub(expired);
     const pageRepo = { removePage: jest.fn().mockResolvedValue(undefined) } as any;
     const service = new TemporaryNoteCleanupService(builder, pageRepo);
 
     await service.sweepExpiredTemporaryNotes();
 
     expect(pageRepo.removePage).toHaveBeenCalledTimes(2);
-    expect(pageRepo.removePage).toHaveBeenNthCalledWith(1, 'p1', 'u1', 'w1');
-    expect(pageRepo.removePage).toHaveBeenNthCalledWith(2, 'p2', 'u2', 'w1');
+    // The 4th arg is the locking transaction — the delete runs inside it.
+    expect(pageRepo.removePage).toHaveBeenNthCalledWith(
+      1,
+      'p1',
+      'u1',
+      'w1',
+      expect.anything(),
+    );
+    expect(pageRepo.removePage).toHaveBeenNthCalledWith(
+      2,
+      'p2',
+      'u2',
+      'w1',
+      expect.anything(),
+    );
+    // The re-check acquired a FOR UPDATE SKIP LOCKED lock (once per candidate).
+    expect(forUpdate).toHaveBeenCalledTimes(2);
+    expect(skipLocked).toHaveBeenCalledTimes(2);
   });
 
   it('continues past a failing note (one bad removePage does not abort the sweep)', async () => {
@@ -86,60 +123,29 @@ describe('TemporaryNoteCleanupService.sweepExpiredTemporaryNotes', () => {
       service.sweepExpiredTemporaryNotes(),
     ).resolves.toBeUndefined();
     expect(pageRepo.removePage).toHaveBeenCalledTimes(2);
-    expect(pageRepo.removePage).toHaveBeenNthCalledWith(2, 'good', 'u2', 'w1');
+    expect(pageRepo.removePage).toHaveBeenNthCalledWith(
+      2,
+      'good',
+      'u2',
+      'w1',
+      expect.anything(),
+    );
   });
 
-  it('does NOT trash a note made permanent in the race window', async () => {
-    // The batch SELECT saw the note as expired, but before its turn in the loop
-    // the user clicked "Make permanent" (temporary_expires_at -> null). The
-    // deadline re-read must catch this and skip the delete so the keep wins.
+  it('does NOT trash a note made permanent / re-armed / already trashed (locked re-check returns nothing)', async () => {
+    // The batch SELECT saw the note as expired, but by the time the LOCKED
+    // re-check runs the row no longer matches the still-armed+expired+not-trashed
+    // predicate (make-permanent, re-arm to a future deadline, or already trashed),
+    // OR another worker holds the row (SKIP LOCKED). In every case the locked
+    // SELECT returns nothing and the delete is skipped so the keep/other worker wins.
     const expired = [{ id: 'p1', creatorId: 'u1', workspaceId: 'w1' }];
-    const { builder, reReadFirst } = makeDbStub(expired);
-    reReadFirst.mockResolvedValueOnce({
-      temporaryExpiresAt: null,
-      deletedAt: null,
-    });
+    const { builder, lockedTakeFirst } = makeDbStub(expired, [undefined]);
     const pageRepo = { removePage: jest.fn() } as any;
     const service = new TemporaryNoteCleanupService(builder, pageRepo);
 
     await service.sweepExpiredTemporaryNotes();
 
-    expect(reReadFirst).toHaveBeenCalledTimes(1);
-    expect(pageRepo.removePage).not.toHaveBeenCalled();
-  });
-
-  it('skips a note already trashed since the batch SELECT', async () => {
-    const expired = [{ id: 'p1', creatorId: 'u1', workspaceId: 'w1' }];
-    const { builder, reReadFirst } = makeDbStub(expired);
-    reReadFirst.mockResolvedValueOnce({
-      temporaryExpiresAt: new Date(0),
-      deletedAt: new Date(),
-    });
-    const pageRepo = { removePage: jest.fn() } as any;
-    const service = new TemporaryNoteCleanupService(builder, pageRepo);
-
-    await service.sweepExpiredTemporaryNotes();
-
-    expect(pageRepo.removePage).not.toHaveBeenCalled();
-  });
-
-  it('does NOT trash a note re-armed to a future deadline in the race window', async () => {
-    // The batch SELECT saw the note as expired, but before its turn in the loop
-    // the user disarmed it and re-armed it to a fresh, still-future deadline
-    // (temporary_expires_at -> now + 1h). The deadline re-read must catch that
-    // the note is no longer expired and skip the delete so the keep wins.
-    const expired = [{ id: 'p1', creatorId: 'u1', workspaceId: 'w1' }];
-    const { builder, reReadFirst } = makeDbStub(expired);
-    reReadFirst.mockResolvedValueOnce({
-      temporaryExpiresAt: new Date(Date.now() + 60 * 60 * 1000),
-      deletedAt: null,
-    });
-    const pageRepo = { removePage: jest.fn() } as any;
-    const service = new TemporaryNoteCleanupService(builder, pageRepo);
-
-    await service.sweepExpiredTemporaryNotes();
-
-    expect(reReadFirst).toHaveBeenCalledTimes(1);
+    expect(lockedTakeFirst).toHaveBeenCalledTimes(1);
     expect(pageRepo.removePage).not.toHaveBeenCalled();
   });
 
@@ -151,4 +157,31 @@ describe('TemporaryNoteCleanupService.sweepExpiredTemporaryNotes', () => {
     await service.sweepExpiredTemporaryNotes();
     expect(pageRepo.removePage).not.toHaveBeenCalled();
   });
+
+  it('sweeps once on application bootstrap (catches notes expired during downtime)', async () => {
+    const expired = [{ id: 'p1', creatorId: 'u1', workspaceId: 'w1' }];
+    const { builder } = makeDbStub(expired);
+    const pageRepo = { removePage: jest.fn().mockResolvedValue(undefined) } as any;
+    const service = new TemporaryNoteCleanupService(builder, pageRepo);
+
+    await service.onApplicationBootstrap();
+
+    expect(pageRepo.removePage).toHaveBeenCalledTimes(1);
+    expect(pageRepo.removePage).toHaveBeenCalledWith(
+      'p1',
+      'u1',
+      'w1',
+      expect.anything(),
+    );
+  });
+
+  it('a startup-sweep failure never blocks application boot', async () => {
+    const { builder } = makeDbStub([]);
+    // Make the candidate SELECT throw to simulate a boot-time DB hiccup.
+    builder.execute.mockRejectedValueOnce(new Error('db not ready'));
+    const pageRepo = { removePage: jest.fn() } as any;
+    const service = new TemporaryNoteCleanupService(builder, pageRepo);
+
+    await expect(service.onApplicationBootstrap()).resolves.toBeUndefined();
+  });
 });

apps/server/src/core/page/services/temporary-note-cleanup.service.ts

@@ -1,8 +1,13 @@
-import { Injectable, Logger } from '@nestjs/common';
+import {
+  Injectable,
+  Logger,
+  OnApplicationBootstrap,
+} from '@nestjs/common';
 import { Interval } from '@nestjs/schedule';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB } from '@docmost/db/types/kysely.types';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { executeTx } from '@docmost/db/utils';
 
 /**
  * Background sweeper for temporary notes ("structure or die"). A note whose
@@ -11,7 +16,7 @@ import { PageRepo } from '@docmost/db/repos/page/page.repo';
  * TrashCleanupService; `@nestjs/schedule` is already enabled globally.
  */
 @Injectable()
-export class TemporaryNoteCleanupService {
+export class TemporaryNoteCleanupService implements OnApplicationBootstrap {
   private readonly logger = new Logger(TemporaryNoteCleanupService.name);
 
   // Cap a single sweep so a large backlog (e.g. many notes created during
@@ -24,6 +29,20 @@ export class TemporaryNoteCleanupService {
     private readonly pageRepo: PageRepo,
   ) {}
 
+  // Sweep once at startup so notes that expired during downtime are trashed
+  // right away instead of waiting up to an hour for the first @Interval tick.
+  // Best-effort: never let a startup-sweep failure block application boot.
+  async onApplicationBootstrap() {
+    try {
+      await this.sweepExpiredTemporaryNotes();
+    } catch (error) {
+      this.logger.error(
+        'Temporary-note startup sweep failed',
+        error instanceof Error ? error.stack : undefined,
+      );
+    }
+  }
+
   // Hourly granularity: lifetimes are configured in hours, so a sub-hour
   // overshoot past the deadline is acceptable.
   @Interval('temporary-note-cleanup', 60 * 60 * 1000)
@@ -31,9 +50,11 @@ export class TemporaryNoteCleanupService {
     try {
       const now = new Date();
 
+      // Candidate ids (non-locking). The authoritative re-check happens per row
+      // under a row lock below, so this cheap pass just bounds the batch.
       const expired = await this.db
         .selectFrom('pages')
-        .select(['id', 'creatorId', 'workspaceId'])
+        .select(['id'])
         .where('temporaryExpiresAt', 'is not', null)
         .where('temporaryExpiresAt', '<', now)
         .where('deletedAt', 'is', null) // not already in trash
@@ -41,50 +62,53 @@ export class TemporaryNoteCleanupService {
         .execute();
 
       let trashed = 0;
-      for (const page of expired) {
+      for (const candidate of expired) {
         try {
-          // Re-check the deadline at deletion time. The SELECT above is not
-          // transactional, so a user may click "Make permanent"
-          // (toggleTemporary sets temporary_expires_at = null) in the window
-          // between the SELECT and this per-row removePage. removePage deletes
-          // by id with only a `deletedAt IS NULL` filter and never re-reads the
-          // deadline, so without this guard a concurrently-kept note would
-          // still be trashed. Re-read the row and skip it unless it is still
-          // armed AND still expired, so a concurrent make-permanent wins.
-          const current = await this.db
-            .selectFrom('pages')
-            .select(['temporaryExpiresAt', 'deletedAt'])
-            .where('id', '=', page.id)
-            .executeTakeFirst();
+          const didTrash = await executeTx(this.db, async (trx) => {
+            // Re-check the row UNDER A LOCK inside the transaction. `FOR UPDATE
+            // SKIP LOCKED`:
+            //  - serialises against a concurrent "Make permanent"
+            //    (toggleTemporary UPDATE takes the same row lock): if it commits
+            //    first, the deadline predicate below no longer matches and we
+            //    skip; if we lock first, it waits until this delete commits.
+            //  - SKIP LOCKED lets a second worker/instance skip a row another
+            //    sweeper already claimed instead of blocking on it (no double
+            //    processing, no thundering herd).
+            // The predicate re-asserts still-armed AND still-expired AND
+            // not-already-trashed, so a make-permanent / prior sweep drops the row.
+            const locked = await trx
+              .selectFrom('pages')
+              .select(['id', 'creatorId', 'workspaceId'])
+              .where('id', '=', candidate.id)
+              .where('temporaryExpiresAt', 'is not', null)
+              .where('temporaryExpiresAt', '<', now)
+              .where('deletedAt', 'is', null)
+              .forUpdate()
+              .skipLocked()
+              .executeTakeFirst();
 
-          if (
-            !current ||
-            current.deletedAt !== null ||
-            current.temporaryExpiresAt === null ||
-            new Date(current.temporaryExpiresAt) >= now
-          ) {
-            // Made permanent, already trashed, or no longer expired since the
-            // SELECT — leave it alone.
-            continue;
-          }
+            if (!locked) return false;
 
-          // Reuse the exact soft-delete path: recursive over children, removes
-          // shares in a transaction, and emits PAGE_SOFT_DELETED (tree
-          // invalidation + watcher notifications). Attribute the automatic
-          // deletion to the note's creator (no schema change). Both the SELECT
-          // above and removePage filter `deletedAt IS NULL`, so a double sweep
-          // is idempotent.
-          await this.pageRepo.removePage(
-            page.id,
-            // creatorId is set on every created page; a temporary note always
-            // has one. Cast to satisfy the non-null deletedById parameter.
-            page.creatorId as string,
-            page.workspaceId,
-          );
-          trashed++;
+            // Reuse the exact soft-delete path (recursive children + share
+            // removal + PAGE_SOFT_DELETED broadcast), running IN this locked
+            // transaction so the delete is atomic with the re-check and cannot
+            // deadlock on a nested independent transaction. The broadcast is
+            // deferred by removePage to this transaction's commit. Attribute the
+            // automatic deletion to the note's creator (no schema change).
+            await this.pageRepo.removePage(
+              locked.id,
+              // creatorId is set on every created page; a temporary note always
+              // has one. Cast to satisfy the non-null deletedById parameter.
+              locked.creatorId as string,
+              locked.workspaceId,
+              trx,
+            );
+            return true;
+          });
+          if (didTrash) trashed++;
         } catch (error) {
           this.logger.error(
-            `Failed to trash expired temporary note ${page.id}`,
+            `Failed to trash expired temporary note ${candidate.id}`,
             error instanceof Error ? error.stack : undefined,
           );
         }

apps/server/src/core/share/share-alias.controller.spec.ts

@@ -133,6 +133,9 @@ describe('ShareAliasController authz gates', () => {
         creatorId: 'u-1',
         alias: 'promo',
         confirmReassign: true,
+        // The requesting user is forwarded so setAlias can gate the reassign
+        // 409 title disclosure on target-page view permission (#495).
+        user,
       });
       expect(result).toEqual({ id: 'alias-1' });
     });

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

@@ -79,6 +79,9 @@ export class ShareAliasController {
       creatorId: user.id,
       alias: dto.alias,
       confirmReassign: dto.confirmReassign,
+      // Gates whether the reassign 409 may reveal the current target's title
+      // (view-permission check on that page) — see setAlias (#495).
+      user,
     });
   }
 

apps/server/src/core/share/share-alias.service.spec.ts

@@ -1,4 +1,8 @@
-import { BadRequestException, ConflictException } from '@nestjs/common';
+import {
+  BadRequestException,
+  ConflictException,
+  ForbiddenException,
+} from '@nestjs/common';
 import { NoResultError } from 'kysely';
 import { ShareAliasService } from './share-alias.service';
 
@@ -7,6 +11,8 @@ import { ShareAliasService } from './share-alias.service';
  * 409 reassign guard, uniqueness-race handling, availability probe, and the
  * request-time readable-target resolution (which re-runs the share boundary).
  */
+const USER = { id: 'u-1' } as any;
+
 describe('ShareAliasService', () => {
   // Sentinel handed to repo calls so tests can assert they ran inside the tx.
   const trx = { __trx: true };
@@ -27,6 +33,10 @@ describe('ShareAliasService', () => {
       resolveReadableSharePage: jest.fn(),
       isSharingAllowed: jest.fn(),
     };
+    // Default: the requester CAN view the target page (validateCanView resolves),
+    // so the reassign 409 may disclose its title. Tests override to reject to
+    // assert the no-leak path.
+    const pageAccessService = { validateCanView: jest.fn().mockResolvedValue(undefined) };
     // Fake kysely db: only .transaction().execute(cb) is used by setAlias.
     const db = {
       transaction: jest.fn(() => ({
@@ -37,9 +47,10 @@ describe('ShareAliasService', () => {
       shareAliasRepo as any,
       pageRepo as any,
       shareService as any,
+      pageAccessService as any,
       db as any,
     );
-    return { service, shareAliasRepo, pageRepo, shareService, db };
+    return { service, shareAliasRepo, pageRepo, shareService, pageAccessService, db };
   }
 
   describe('setAlias', () => {
@@ -50,6 +61,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'A', // too short + uppercase
         }),
       ).rejects.toBeInstanceOf(BadRequestException);
@@ -66,6 +78,7 @@ describe('ShareAliasService', () => {
         workspaceId: 'ws-1',
         pageId: 'p-1',
         creatorId: 'u-1',
+        user: USER,
         alias: '  My Page ',
       });
 
@@ -114,6 +127,7 @@ describe('ShareAliasService', () => {
         workspaceId: 'ws-1',
         pageId: 'p-1',
         creatorId: 'u-1',
+        user: USER,
         alias: 'ted',
       });
 
@@ -144,6 +158,7 @@ describe('ShareAliasService', () => {
         workspaceId: 'ws-1',
         pageId: 'p-1',
         creatorId: 'u-1',
+        user: USER,
         alias: 'foo',
       });
 
@@ -179,6 +194,7 @@ describe('ShareAliasService', () => {
         workspaceId: 'ws-1',
         pageId: 'p-1',
         creatorId: 'u-1',
+        user: USER,
         alias: 'new',
       });
 
@@ -190,30 +206,77 @@ describe('ShareAliasService', () => {
       );
     });
 
-    it('throws 409 with current target when name is taken and not confirmed', async () => {
-      const { service, shareAliasRepo, pageRepo } = makeService();
+    it('throws 409 with the target TITLE (never its id) when the requester CAN view it', async () => {
+      const { service, shareAliasRepo, pageRepo, pageAccessService } =
+        makeService();
       shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
         id: 'a-1',
         alias: 'foo',
         pageId: 'p-other',
       });
       pageRepo.findById.mockResolvedValue({ id: 'p-other', title: 'Other' });
+      pageAccessService.validateCanView.mockResolvedValue(undefined); // can view
 
       try {
         await service.setAlias({
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'foo',
         });
         fail('expected ConflictException');
       } catch (err) {
         expect(err).toBeInstanceOf(ConflictException);
-        expect((err as ConflictException).getResponse()).toMatchObject({
+        const body = (err as ConflictException).getResponse();
+        expect(body).toMatchObject({
           code: 'ALIAS_REASSIGN_REQUIRED',
-          currentPageId: 'p-other',
           currentPageTitle: 'Other',
         });
+        // SECURITY (#495): the page id is NEVER disclosed, even to a viewer.
+        expect(body).not.toHaveProperty('currentPageId');
+        expect(pageAccessService.validateCanView).toHaveBeenCalledWith(
+          expect.objectContaining({ id: 'p-other' }),
+          USER,
+        );
+      }
+      expect(shareAliasRepo.updatePageId).not.toHaveBeenCalled();
+    });
+
+    it('throws 409 WITHOUT the title or id when the requester CANNOT view the target (#495)', async () => {
+      const { service, shareAliasRepo, pageRepo, pageAccessService } =
+        makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
+        id: 'a-1',
+        alias: 'foo',
+        pageId: 'p-secret',
+      });
+      pageRepo.findById.mockResolvedValue({ id: 'p-secret', title: 'Secret' });
+      // No view permission on the target page -> validateCanView throws.
+      pageAccessService.validateCanView.mockRejectedValue(
+        new ForbiddenException(),
+      );
+
+      try {
+        await service.setAlias({
+          workspaceId: 'ws-1',
+          pageId: 'p-1',
+          creatorId: 'u-1',
+          user: USER,
+          alias: 'foo',
+        });
+        fail('expected ConflictException');
+      } catch (err) {
+        expect(err).toBeInstanceOf(ConflictException);
+        const body = (err as ConflictException).getResponse() as Record<
+          string,
+          unknown
+        >;
+        expect(body).toMatchObject({ code: 'ALIAS_REASSIGN_REQUIRED' });
+        // The enumeration hole: neither the id nor the title of a page the
+        // requester cannot see may leak.
+        expect(body).not.toHaveProperty('currentPageId');
+        expect(body.currentPageTitle ?? null).toBeNull();
       }
       expect(shareAliasRepo.updatePageId).not.toHaveBeenCalled();
     });
@@ -231,6 +294,7 @@ describe('ShareAliasService', () => {
         workspaceId: 'ws-1',
         pageId: 'p-1',
         creatorId: 'u-1',
+        user: USER,
         alias: 'foo',
         confirmReassign: true,
       });
@@ -269,6 +333,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'foo',
         });
         fail('expected ConflictException');
@@ -294,6 +359,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'foo',
         });
         fail('expected ConflictException');
@@ -317,6 +383,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'foo',
         });
         fail('expected ConflictException');
@@ -346,6 +413,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'foo',
         });
         fail('expected ConflictException');
@@ -375,6 +443,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'foo',
           confirmReassign: true,
         });
@@ -406,6 +475,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'ted',
         });
         fail('expected ConflictException');
@@ -428,6 +498,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'foo',
         }),
       ).rejects.toBeInstanceOf(BadRequestException);
@@ -450,18 +521,22 @@ describe('ShareAliasService', () => {
         alias: 'free-name',
         valid: true,
         available: true,
-        currentPageId: null,
       });
+      // SECURITY (#495): the availability probe must NOT leak any page id.
+      expect(res).not.toHaveProperty('currentPageId');
     });
 
-    it('reports taken with the current target page', async () => {
+    it('reports taken WITHOUT leaking the current target page id (#495)', async () => {
       const { service, shareAliasRepo } = makeService();
       shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
         id: 'a-1',
         pageId: 'p-9',
       });
       const res = await service.checkAvailability('taken', 'ws-1');
-      expect(res).toMatchObject({ available: false, currentPageId: 'p-9' });
+      expect(res).toMatchObject({ available: false });
+      // The row exists (available:false) but its pageId is never returned — an
+      // authenticated member cannot map an alias name to a page id it can't view.
+      expect(res).not.toHaveProperty('currentPageId');
     });
   });
 

apps/server/src/core/share/share-alias.service.ts

@@ -7,7 +7,8 @@ import {
 import { ShareAliasRepo } from '@docmost/db/repos/share-alias/share-alias.repo';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
 import { ShareService } from './share.service';
-import { Page, ShareAlias } from '@docmost/db/types/entity.types';
+import { PageAccessService } from '../page/page-access/page-access.service';
+import { Page, ShareAlias, User } from '@docmost/db/types/entity.types';
 import { isValidShareAlias, normalizeShareAlias } from './share-alias.util';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB } from '@docmost/db/types/kysely.types';
@@ -43,6 +44,7 @@ export class ShareAliasService {
     private readonly shareAliasRepo: ShareAliasRepo,
     private readonly pageRepo: PageRepo,
     private readonly shareService: ShareService,
+    private readonly pageAccessService: PageAccessService,
     @InjectKysely() private readonly db: KyselyDB,
   ) {}
 
@@ -55,9 +57,13 @@ export class ShareAliasService {
    *     `/l/<old>` link survives
    *   - name already points at pageId    -> no-op (idempotent)
    *   - name points at ANOTHER page      -> the "swap". Without confirmReassign
-   *     we throw 409 carrying the current target so the client can confirm;
-   *     with it we UPDATE the single row's page_id (every /l/<alias> link
-   *     follows the 302 to the new page instantly — no stale cache).
+   *     we throw 409 so the client can confirm. SECURITY (#495): the 409 reveals
+   *     the current target's title ONLY when `user` may VIEW that page, and never
+   *     its id — otherwise any member with one editable+shared page could iterate
+   *     alias names with confirmReassign=false and map them to (id, title) of
+   *     pages they cannot see. With confirmReassign we UPDATE the single row's
+   *     page_id (every /l/<alias> link follows the 302 to the new page instantly
+   *     — no stale cache).
    *
    * To keep the invariant self-healing we DELETE every other alias row still
    * pointing at this page (a legacy duplicate, or the target page's own former
@@ -77,8 +83,12 @@ export class ShareAliasService {
     creatorId: string;
     alias: string;
     confirmReassign?: boolean;
+    // The requesting user — used ONLY to gate whether the reassign 409 may reveal
+    // the current target page's title (view-permission check). Not an authz gate
+    // for the write itself (the controller already validated edit on `pageId`).
+    user: User;
   }): Promise<ShareAlias> {
-    const { workspaceId, pageId, creatorId, confirmReassign } = opts;
+    const { workspaceId, pageId, creatorId, confirmReassign, user } = opts;
     const alias = normalizeShareAlias(opts.alias);
     if (!isValidShareAlias(alias)) {
       throw new BadRequestException(
@@ -97,14 +107,30 @@ export class ShareAliasService {
         // The name is occupied by a DIFFERENT (or dangling) target page.
         if (byName && byName.pageId !== pageId) {
           if (!confirmReassign) {
+            // SECURITY (#495): only disclose the current target's TITLE, and only
+            // when the requester may VIEW that page. Never disclose its id (the
+            // client's confirm-reassign UX doesn't use it, and it is an enumerable
+            // identity). A member with one editable+shared page must NOT be able to
+            // iterate alias names and map them to (id, title) of pages they cannot
+            // see. When view is denied (or the alias is dangling) the 409 is the
+            // bare "occupied" fact — the client still shows a generic confirm modal.
             const currentPage = byName.pageId
               ? await this.pageRepo.findById(byName.pageId)
               : null;
+            let currentPageTitle: string | null = null;
+            if (currentPage) {
+              try {
+                await this.pageAccessService.validateCanView(currentPage, user);
+                currentPageTitle = currentPage.title ?? null;
+              } catch {
+                // No view permission on the target -> do not reveal its title.
+                currentPageTitle = null;
+              }
+            }
             throw new ConflictException({
               message: 'Alias already in use',
               code: 'ALIAS_REASSIGN_REQUIRED',
-              currentPageId: byName.pageId,
-              currentPageTitle: currentPage?.title ?? null,
+              currentPageTitle,
             });
           }
           // Confirmed swap. ORDER MATTERS: the partial unique index on
@@ -223,21 +249,27 @@ export class ShareAliasService {
     alias: string;
     valid: boolean;
     available: boolean;
-    currentPageId: string | null;
   }> {
     const alias = normalizeShareAlias(rawAlias);
     if (!isValidShareAlias(alias)) {
-      return { alias, valid: false, available: false, currentPageId: null };
+      return { alias, valid: false, available: false };
     }
     const existing = await this.shareAliasRepo.findByAliasAndWorkspace(
       alias,
       workspaceId,
     );
+    // SECURITY (#495): return ONLY the boolean availability. The previous shape
+    // leaked `currentPageId` — the id of whatever page the alias already targets —
+    // to ANY authenticated workspace member, with no view-permission check on that
+    // page. An attacker could enumerate alias names and map them to page ids they
+    // have no access to. The taken/free bit is all the "is this address free"
+    // probe needs. The reassign flow (setAlias 409) may surface the target's
+    // TITLE, but only behind a `validateCanView` on that page (see setAlias); it
+    // never returns the page id.
     return {
       alias,
       valid: true,
       available: !existing,
-      currentPageId: existing?.pageId ?? null,
     };
   }
 

apps/server/src/core/telemetry/client-metrics.constants.ts

@@ -24,6 +24,54 @@ export const ALLOWED_RATINGS = new Set<string>([
   'poor',
 ]);
 
+// The ONLY route labels accepted. The endpoint is anonymous, so an un-checked
+// `route` is a free-text write surface (arbitrary high-cardinality strings /
+// injected text into the metrics table). The client only ever sends a label from
+// a finite template dictionary (`templateRoute`), so we drop anything not in it.
+//
+// PARITY: this MUST mirror `KNOWN_ROUTE_TEMPLATES` in the client's
+// `apps/client/src/lib/telemetry/route-template.ts` (the canonical source). A
+// drift means legit client routes get dropped — keep the two in lockstep; the
+// client self-consistency test asserts `templateRoute` only emits these values.
+export const ALLOWED_ROUTE_TEMPLATES = new Set<string>([
+  '/',
+  'other',
+  // Static routes.
+  '/home',
+  '/spaces',
+  '/favorites',
+  '/login',
+  '/forgot-password',
+  '/password-reset',
+  '/setup/register',
+  '/settings/account/profile',
+  '/settings/account/preferences',
+  '/settings/workspace',
+  '/settings/ai',
+  '/settings/members',
+  '/settings/groups',
+  '/settings/spaces',
+  '/settings/sharing',
+  // Dynamic templates (slugs/ids are already collapsed to `:param`).
+  '/share/:shareId/p/:slug',
+  '/share/p/:slug',
+  '/share/:shareId',
+  '/p/:slug',
+  '/s/:space/p/:slug',
+  '/s/:space/trash',
+  '/s/:space',
+  '/labels/:label',
+  '/invites/:invitationId',
+  '/settings/groups/:groupId',
+]);
+
+// `attr` is a web-vitals attribution TARGET: a CSS-selector-ish string (an
+// element path like `html>body>div#app>button.cta`), never free prose. Constrain
+// it to a conservative CSS-selector charset so the anonymous endpoint cannot be
+// used to write arbitrary text / PII / markup into the metrics table. A value
+// containing anything outside this set is DROPPED (-> null); the event is kept.
+export const ATTR_ALLOWED_CHARSET = /^[A-Za-z0-9#.\-_> :()[\]="'*+~,]+$/;
+
 // Max events accepted per batch; the rest are ignored.
 export const MAX_EVENTS_PER_BATCH = 50;
 
@@ -77,14 +125,20 @@ export function sanitizeVitalEvent(
       ? e.rating
       : null;
 
+  // route: accept ONLY a known template label (dictionary check), else drop to
+  // null. The length cap stays as a cheap pre-guard before the Set lookup.
   let route: string | null = null;
   if (typeof e.route === 'string' && e.route.length > 0) {
-    route = e.route.slice(0, MAX_ROUTE_LENGTH);
+    const candidate = e.route.slice(0, MAX_ROUTE_LENGTH);
+    route = ALLOWED_ROUTE_TEMPLATES.has(candidate) ? candidate : null;
   }
 
+  // attr: truncate, then accept ONLY if it is a CSS-selector-shaped string
+  // (charset whitelist); anything with characters outside the set is dropped.
   let attr: string | null = null;
   if (typeof e.attr === 'string' && e.attr.length > 0) {
-    attr = e.attr.slice(0, MAX_ATTR_LENGTH);
+    const candidate = e.attr.slice(0, MAX_ATTR_LENGTH);
+    attr = ATTR_ALLOWED_CHARSET.test(candidate) ? candidate : null;
   }
 
   let docSize: number | null = null;

apps/server/src/core/telemetry/vitals.service.spec.ts

@@ -90,6 +90,44 @@ describe('VitalsService.buildRows', () => {
     expect(rows[0].attr).toHaveLength(MAX_ATTR_LENGTH);
   });
 
+  it('keeps a known route template but DROPS an unknown/free-text route (#495)', () => {
+    const rows = svc.buildRows(
+      {
+        events: [
+          { name: 'INP', value: 1, route: '/s/:space/p/:slug' }, // known
+          { name: 'INP', value: 2, route: '/s/acme-corp/p/secret-slug' }, // raw path (slugs) — not a template
+          { name: 'INP', value: 3, route: 'DROP TABLE client_metrics;--' }, // injected free text
+          { name: 'INP', value: 4, route: '/home' }, // known static
+        ],
+      },
+      WS,
+    );
+    expect(rows.map((r) => r.route)).toEqual([
+      '/s/:space/p/:slug',
+      null, // raw path dropped
+      null, // free text dropped
+      '/home',
+    ]);
+  });
+
+  it('DROPS an attr that is not a CSS-selector-shaped string (#495)', () => {
+    const rows = svc.buildRows(
+      {
+        events: [
+          { name: 'INP', value: 1, attr: 'div#app>button.cta' }, // valid selector
+          { name: 'INP', value: 2, attr: 'user@example.com wrote a note' }, // free text / PII
+          { name: 'INP', value: 3, attr: '<script>alert(1)</script>' }, // markup
+        ],
+      },
+      WS,
+    );
+    expect(rows.map((r) => r.attr)).toEqual([
+      'div#app>button.cta',
+      null,
+      null,
+    ]);
+  });
+
   it('caps the batch at 50 events', () => {
     const events = Array.from({ length: 200 }, () => ({ name: 'CLS', value: 1 }));
     const rows = svc.buildRows({ events }, WS);

apps/server/src/database/concurrent-indexes.spec.ts

@@ -0,0 +1,114 @@
+import * as path from 'path';
+import { readFileSync } from 'fs';
+
+// Mock ONLY kysely's `sql.raw(...).execute()` so we can observe what
+// ensureConcurrentIndexes runs and how it handles failures, without a DB.
+const execMock = jest.fn((_db: unknown) => Promise.resolve(undefined));
+const rawMock = jest.fn((_stmt: string) => ({ execute: execMock }));
+jest.mock('kysely', () => {
+  const actual = jest.requireActual('kysely');
+  return { ...actual, sql: { ...actual.sql, raw: rawMock } };
+});
+
+import { CONCURRENT_INDEXES, ensureConcurrentIndexes } from './concurrent-indexes';
+
+describe('ensureConcurrentIndexes', () => {
+  const fakeDb = { __topLevelKysely: true } as never;
+
+  beforeEach(() => {
+    execMock.mockReset().mockResolvedValue(undefined);
+    rawMock.mockClear();
+  });
+
+  it('redefines the inlinable f_unaccent BEFORE building any index, then builds each CONCURRENTLY outside a transaction', async () => {
+    const onLog = jest.fn();
+    await ensureConcurrentIndexes(fakeDb, onLog);
+
+    // One f_unaccent redefine + one statement per index.
+    expect(rawMock).toHaveBeenCalledTimes(CONCURRENT_INDEXES.length + 1);
+    const statements = rawMock.mock.calls.map((c) => c[0] as string);
+    // ORDER: the f_unaccent redefine MUST be first — otherwise an existing
+    // tenant's old 2-arg f_unaccent makes every CONCURRENTLY build fail.
+    expect(statements[0]).toContain('CREATE OR REPLACE FUNCTION f_unaccent');
+    expect(statements[0]).toContain('SELECT public.unaccent($1)');
+    expect(statements[0]).not.toContain('CREATE INDEX');
+    // The rest are the CONCURRENTLY index builds.
+    for (const stmt of statements.slice(1)) {
+      expect(stmt).toContain('CREATE INDEX CONCURRENTLY');
+      expect(stmt).toContain('IF NOT EXISTS');
+    }
+    // Executed against the top-level db (a transaction would forbid CONCURRENTLY).
+    for (const call of execMock.mock.calls) {
+      expect(call[0]).toBe(fakeDb);
+    }
+    expect(onLog).toHaveBeenCalledTimes(CONCURRENT_INDEXES.length + 1);
+  });
+
+  it('still builds the indexes when the f_unaccent redefine fails (fresh DB, best-effort)', async () => {
+    // Redefine (first execute) throws; the index loop must still run.
+    execMock
+      .mockRejectedValueOnce(new Error('extension "unaccent" does not exist'))
+      .mockResolvedValue(undefined);
+    const onLog = jest.fn();
+
+    await expect(
+      ensureConcurrentIndexes(fakeDb, onLog),
+    ).resolves.toBeUndefined();
+
+    // 1 redefine attempt + one per index.
+    expect(execMock).toHaveBeenCalledTimes(CONCURRENT_INDEXES.length + 1);
+    const errored = onLog.mock.calls.filter((c) => c[1] !== undefined);
+    expect(errored).toHaveLength(1);
+    expect(String(errored[0][1])).toContain('unaccent');
+  });
+
+  it('is best-effort: a failing index does not abort the rest and is reported', async () => {
+    // Redefine ok; fail the FIRST index; the remaining ones must still be tried.
+    execMock
+      .mockResolvedValueOnce(undefined) // f_unaccent redefine
+      .mockRejectedValueOnce(new Error('relation "pages" does not exist'))
+      .mockResolvedValue(undefined);
+    const onLog = jest.fn();
+
+    await expect(
+      ensureConcurrentIndexes(fakeDb, onLog),
+    ).resolves.toBeUndefined();
+
+    expect(execMock).toHaveBeenCalledTimes(CONCURRENT_INDEXES.length + 1);
+    const errored = onLog.mock.calls.filter((c) => c[1] !== undefined);
+    expect(errored).toHaveLength(1);
+    expect(String(errored[0][1])).toContain('does not exist');
+  });
+});
+
+// DRIFT GUARD: each CONCURRENT_INDEXES entry pre-builds an index that a plain
+// migration ALSO creates with `IF NOT EXISTS`. If the two expressions diverge,
+// Postgres would treat them as different indexes and the pre-build would NOT
+// make the migration a no-op. Assert the migration files still contain each
+// index's functional expression.
+describe('CONCURRENT_INDEXES parity with the migrations', () => {
+  const migrationsDir = path.join(__dirname, 'migrations');
+  const files = [
+    '20260705T120000-perf-indexes.ts',
+    '20260706T120000-search-lookup-trgm.ts',
+  ].map((f) => readFileSync(path.join(migrationsDir, f), 'utf8'));
+  const allMigrationSrc = files.join('\n');
+
+  it.each(CONCURRENT_INDEXES.map((i) => [i.name, i]))(
+    'migration source still creates %s with the same expression',
+    (_name, idx) => {
+      // Extract the `USING gin ((...expr...) gin_trgm_ops)` tail from the
+      // canonical create and assert the migration source contains it verbatim.
+      const m = (idx as { create: string }).create.match(
+        /ON \w+ (USING gin .+)$/,
+      );
+      expect(m).not.toBeNull();
+      const expr = (m as RegExpMatchArray)[1];
+      expect(allMigrationSrc).toContain(expr);
+      // And the migration must build it by the SAME index name.
+      expect(allMigrationSrc).toContain(
+        `CREATE INDEX IF NOT EXISTS ${(idx as { name: string }).name}`,
+      );
+    },
+  );
+});

apps/server/src/database/concurrent-indexes.ts

@@ -0,0 +1,142 @@
+import { Kysely, sql } from 'kysely';
+
+/**
+ * Indexes that MUST be built with `CREATE INDEX CONCURRENTLY` so an auto-deploy
+ * migration never takes a `SHARE` lock that blocks writes on a hot table
+ * (`pages`) for the — potentially minutes-long — GIN trigram build (#495 item 12).
+ *
+ * Kysely runs each migration INSIDE a transaction (Postgres has transactional
+ * DDL), and `CREATE INDEX CONCURRENTLY` cannot run inside a transaction block, so
+ * these cannot live in an ordinary migration. Instead {@link ensureConcurrentIndexes}
+ * builds them out-of-band (no transaction) BEFORE the migrator runs; the matching
+ * migrations keep a plain `CREATE INDEX IF NOT EXISTS` as a backstop, which then
+ * no-ops because the index already exists. So:
+ *   - existing prod DB, incremental deploy: the pre-build FIRST redefines
+ *     `f_unaccent` to its index-inlinable 1-arg form (see below), THEN builds each
+ *     index CONCURRENTLY (no write lock); the migration's IF NOT EXISTS no-ops →
+ *     the write-blocking build is gone;
+ *   - fresh DB (or a DB whose `pages` / `unaccent` extension does not exist yet):
+ *     the pre-build fails and is swallowed (best-effort), and the migration builds
+ *     the index normally on an empty/small table where the lock is irrelevant.
+ *
+ * NOT a strict "worst case = previous behaviour":
+ *   - The f_unaccent form matters. The trigram expressions use `LOWER(f_unaccent(col))`.
+ *     The INDEX-INLINABLE 1-arg `f_unaccent(text)` (`SELECT public.unaccent($1)`)
+ *     is created INSIDE migration 20260705, which runs AFTER this pre-build. On an
+ *     existing tenant the live `f_unaccent` is still the OLD 2-arg form from
+ *     20250729, which Postgres CANNOT inline into a CONCURRENTLY index expression
+ *     (`function unaccent(unknown, text) does not exist ... during inlining`) — the
+ *     build fails outright. So this pre-build redefines `f_unaccent` to the 1-arg
+ *     form FIRST (idempotent, output-identical, in lockstep with 20260705). Without
+ *     that redefine the whole feature is dead-on-arrival for the very case it
+ *     targets.
+ *   - An INTERRUPTED `CREATE INDEX CONCURRENTLY` (killed pod, cancelled query) with
+ *     a working `f_unaccent` leaves an INVALID index behind. A subsequent name-based
+ *     `IF NOT EXISTS` — in BOTH this pre-build and the migration backstop — sees the
+ *     name and skips, so the invalid index is NEVER repaired automatically and the
+ *     query keeps seq-scanning until an operator `DROP INDEX`es it. The old
+ *     in-transaction build could not leave an invalid index (a failed tx rolled the
+ *     whole index back), so this is a genuinely new failure mode, not "= previous".
+ *     (A future hardening could `DROP` an `indisvalid = false` index before
+ *     rebuilding; not done here.)
+ *
+ * The `create` text is the CANONICAL definition — it MUST match the migration's
+ * `IF NOT EXISTS` create expression exactly (same functional expression + opclass)
+ * or Postgres would treat them as two different indexes.
+ */
+export const CONCURRENT_INDEXES: ReadonlyArray<{
+  name: string;
+  create: string;
+}> = [
+  {
+    // #348 perf-indexes — pages.title trigram (coalesce-free functional expr).
+    name: 'idx_pages_title_trgm',
+    create:
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_pages_title_trgm ' +
+      'ON pages USING gin ((LOWER(f_unaccent(title))) gin_trgm_ops)',
+  },
+  {
+    // #348 perf-indexes — users.name trigram (member search-suggest).
+    name: 'idx_users_name_trgm',
+    create:
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_name_trgm ' +
+      'ON users USING gin ((LOWER(f_unaccent(name))) gin_trgm_ops)',
+  },
+  {
+    // #443 search-lookup-trgm — pages.text_content trigram (the slow, large one).
+    name: 'idx_pages_text_content_trgm',
+    create:
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_pages_text_content_trgm ' +
+      'ON pages USING gin ((LOWER(f_unaccent(text_content))) gin_trgm_ops)',
+  },
+];
+
+/**
+ * Idempotent, output-identical redefinition of `f_unaccent` to the INDEX-INLINABLE
+ * 1-arg form. MUST stay byte-for-byte in lockstep with migration
+ * `20260705T120000-perf-indexes.ts` (same signature + body): the trigram indexes
+ * above only build CONCURRENTLY once `f_unaccent(text)` inlines, and on an existing
+ * tenant it is still the old 2-arg form until that migration runs — which is AFTER
+ * this pre-build.
+ */
+const F_UNACCENT_REDEF = `
+    CREATE OR REPLACE FUNCTION f_unaccent(text)
+      RETURNS text
+      LANGUAGE sql
+      IMMUTABLE PARALLEL SAFE STRICT
+    AS $func$
+      SELECT public.unaccent($1);
+    $func$
+`;
+
+/**
+ * Best-effort, non-transactional pre-build of {@link CONCURRENT_INDEXES}. Run
+ * BEFORE the migrator so the blocking `CREATE INDEX` in the corresponding
+ * migration becomes an `IF NOT EXISTS` no-op.
+ *
+ * `db` MUST be the top-level Kysely instance (NOT a transaction): each statement
+ * then executes on its own connection with no surrounding `BEGIN`, which is
+ * required for `CONCURRENTLY`. Every statement is independent and swallowed on
+ * error: the migration backstop still builds the index, so a failure here is
+ * never fatal. `onLog` reports progress/failures for the caller to route to its
+ * logger.
+ *
+ * ORDER MATTERS: redefine `f_unaccent` to the inlinable form BEFORE the index
+ * loop — otherwise an existing tenant's old 2-arg `f_unaccent` makes every
+ * CONCURRENTLY build fail and the feature is a no-op (see the module docstring).
+ */
+export async function ensureConcurrentIndexes(
+  db: Kysely<any>,
+  onLog?: (message: string, error?: unknown) => void,
+): Promise<void> {
+  // Make f_unaccent inlinable FIRST. On a fresh DB (no `unaccent` extension yet)
+  // this throws harmlessly and is swallowed — the migration builds everything.
+  try {
+    await sql.raw(F_UNACCENT_REDEF).execute(db);
+    onLog?.('f_unaccent redefined to the index-inlinable 1-arg form');
+  } catch (error) {
+    onLog?.(
+      'f_unaccent redefine skipped (fresh DB / no unaccent extension) — ' +
+        'the migration will define it and build the indexes',
+      error,
+    );
+  }
+
+  for (const idx of CONCURRENT_INDEXES) {
+    try {
+      await sql.raw(idx.create).execute(db);
+      onLog?.(`Concurrent index ensured: ${idx.name}`);
+    } catch (error) {
+      // Non-fatal by design — the migration's IF NOT EXISTS create is the
+      // backstop. Benign on a fresh DB (the table/extension does not exist yet).
+      // NOT benign, but still swallowed, on an existing tenant whose f_unaccent
+      // could not be redefined above (then the migration builds the index NON-
+      // concurrently under the SHARE lock this feature meant to avoid).
+      onLog?.(
+        `Concurrent index pre-build skipped for ${idx.name} ` +
+          `(will fall back to the in-migration build)`,
+        error,
+      );
+    }
+  }
+}

apps/server/src/database/execute-tx-after-commit.spec.ts

@@ -0,0 +1,113 @@
+import { executeTx, registerAfterCommit } from './utils';
+import { KyselyDB, KyselyTransaction } from './types/kysely.types';
+
+// Post-commit hook contract (#495 item 13): a side effect registered via
+// registerAfterCommit must run ONLY AFTER the owning transaction commits, and a
+// hook registered against a passed-through existingTrx must fire at the OUTER
+// commit boundary — never inside the inner call. We fake the Kysely transaction
+// runner so the ordering is observable without a real DB.
+
+/**
+ * A minimal db whose `.transaction().execute(cb)` records the commit ORDER: it
+ * runs `cb(trx)`, pushes 'commit' onto `log` (simulating the real commit that
+ * happens after the callback resolves), then returns the callback's result.
+ */
+function fakeDb(log: string[]): { db: KyselyDB; trx: KyselyTransaction } {
+  const trx = { __fakeTrx: true } as unknown as KyselyTransaction;
+  const db = {
+    transaction: () => ({
+      execute: async (cb: (t: KyselyTransaction) => Promise<unknown>) => {
+        const result = await cb(trx);
+        log.push('commit');
+        return result;
+      },
+    }),
+  } as unknown as KyselyDB;
+  return { db, trx };
+}
+
+describe('executeTx post-commit hooks', () => {
+  it('runs an afterCommit hook only AFTER the transaction commits', async () => {
+    const log: string[] = [];
+    const { db } = fakeDb(log);
+
+    await executeTx(db, async (trx) => {
+      log.push('body');
+      registerAfterCommit(trx, () => {
+        log.push('hook');
+      });
+      // The hook must NOT have run yet — the tx is still open.
+      expect(log).toEqual(['body']);
+    });
+
+    // Order proves post-commit: body → commit → hook (never body → hook → commit).
+    expect(log).toEqual(['body', 'commit', 'hook']);
+  });
+
+  it('drains hooks registered against a passed-through existingTrx at the OUTER commit', async () => {
+    const log: string[] = [];
+    const { db, trx: outerTrx } = fakeDb(log);
+
+    await executeTx(db, async (outer) => {
+      // Nested executeTx reuses the outer trx: it must NOT commit or drain now.
+      await executeTx(
+        db,
+        async (inner) => {
+          registerAfterCommit(inner, () => {
+            log.push('inner-hook');
+          });
+        },
+        outer,
+      );
+      // Still inside the outer tx — the inner hook has not fired.
+      expect(log).toEqual([]);
+    });
+
+    // The single (outer) commit drains the hook registered on the shared trx.
+    expect(log).toEqual(['commit', 'inner-hook']);
+    // Sanity: the trx the hooks were registered against is the outer one.
+    expect(outerTrx).toBeDefined();
+  });
+
+  it('a hook failure does not reject the already-committed executeTx', async () => {
+    const log: string[] = [];
+    const { db } = fakeDb(log);
+
+    await expect(
+      executeTx(db, async (trx) => {
+        registerAfterCommit(trx, () => {
+          throw new Error('cache del blew up');
+        });
+        registerAfterCommit(trx, () => {
+          log.push('second-hook-still-runs');
+        });
+        return 'ok';
+      }),
+    ).resolves.toBe('ok');
+
+    // The throwing hook is swallowed; a later hook still runs.
+    expect(log).toEqual(['commit', 'second-hook-still-runs']);
+  });
+
+  it('does NOT run afterCommit hooks when the transaction body throws (rollback)', async () => {
+    // The body rejects -> the fake transaction never pushes 'commit' and
+    // db.transaction().execute() rejects, mirroring a real rolled-back tx. The
+    // drain runs only AFTER the awaited (committed) transaction, so a rollback
+    // must leave every registered hook UN-run — otherwise a cache-bust / event
+    // would fire for a write that never landed.
+    const log: string[] = [];
+    const { db } = fakeDb(log);
+    const hook = jest.fn();
+
+    await expect(
+      executeTx(db, async (trx) => {
+        registerAfterCommit(trx, hook);
+        throw new Error('write failed -> rollback');
+      }),
+    ).rejects.toThrow('write failed -> rollback');
+
+    // No commit happened, and the post-commit hook never ran.
+    expect(log).toEqual([]); // no 'commit'
+    expect(hook).not.toHaveBeenCalled();
+  });
+});

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

@@ -35,4 +35,25 @@ describe('jsonbBind', () => {
     expect(out).not.toBeNull();
     expect(out).toBeDefined();
   });
+
+  // preserveEmpty (#476): opts a column OUT of the empty-to-null collapse so an
+  // empty container is persisted verbatim (e.g. `[]` = deny-all for
+  // tool_allowlist). null stays null regardless of the flag.
+  describe('preserveEmpty', () => {
+    it('returns a (non-null) bind for an empty array', () => {
+      const out = jsonbBind([], { preserveEmpty: true });
+      expect(out).not.toBeNull();
+      expect(out).toBeDefined();
+    });
+
+    it('returns a (non-null) bind for an empty object', () => {
+      const out = jsonbBind({}, { preserveEmpty: true });
+      expect(out).not.toBeNull();
+      expect(out).toBeDefined();
+    });
+
+    it('still returns null for null (null means null, flag or not)', () => {
+      expect(jsonbBind(null, { preserveEmpty: true })).toBeNull();
+    });
+  });
 });

apps/server/src/database/migrations/20260705T120000-perf-indexes.ts

@@ -33,16 +33,18 @@ import { type Kysely, sql } from 'kysely';
  *    - comments: `findPageComments` does WHERE page_id ORDER BY id ASC, but only
  *      `(page_id)` exists → extra sort.
  *
- * DEPLOY-TIME LOCK WARNING: these are plain (non-CONCURRENT) CREATE INDEX
- * statements — CONCURRENTLY is impossible because Kysely runs each migration in a
- * transaction. They take a SHARE lock that BLOCKS writes (INSERT/UPDATE/DELETE) on
- * pages/users/groups/comments/page_history for the duration of the build. The two
- * GIN trigram builds on pages.title / users.name are the slow ones and can take
- * minutes on a large tenant → a write-outage window during the deploy migration.
- * For large installations, run this migration in a maintenance window, or build
- * the trigram indexes out-of-band with CREATE INDEX CONCURRENTLY before deploying
- * (then this migration's `IF NOT EXISTS` is a no-op). Small/typical tenants are
- * unaffected.
+ * DEPLOY-TIME LOCK: these are plain (non-CONCURRENT) CREATE INDEX statements —
+ * CONCURRENTLY is impossible HERE because Kysely runs each migration in a
+ * transaction. The two GIN trigram builds on pages.title / users.name are the
+ * slow ones and would take a SHARE lock that BLOCKS writes on pages/users for
+ * minutes on a large tenant. To avoid that, `ensureConcurrentIndexes`
+ * (database/concurrent-indexes.ts) now pre-builds BOTH trigram indexes with
+ * CREATE INDEX CONCURRENTLY (no transaction) BEFORE the migrator runs, so on an
+ * existing DB the two `IF NOT EXISTS` trigram creates below no-op and no write
+ * lock is taken. On a fresh DB the pre-build is skipped and they build on an
+ * empty table. Keep the two trigram creates in lockstep with their CANONICAL
+ * definitions in CONCURRENT_INDEXES. (The plain b-tree indexes further down are
+ * fast metadata-only builds; they are not pre-built.)
  */
 export async function up(db: Kysely<any>): Promise<void> {
   // Index-compatible, output-identical redefinition of f_unaccent (see header).

apps/server/src/database/migrations/20260706T120000-search-lookup-trgm.ts

@@ -26,13 +26,16 @@ import { type Kysely, sql } from 'kysely';
  *    to update than b-trees); on the small instances this fork targets that cost
  *    is acceptable and the read win on agent lookups is the priority.
  *
- * DEPLOY-TIME LOCK WARNING: plain (non-CONCURRENT) CREATE INDEX — Kysely runs
- * each migration in a transaction, so CONCURRENTLY is impossible. The build takes
- * a SHARE lock that BLOCKS writes on `pages` for its duration. The text_content
- * GIN build is the slow one and can take minutes on a large tenant. For large
- * installations, run this in a maintenance window or build the index out-of-band
- * with CREATE INDEX CONCURRENTLY before deploying (then `IF NOT EXISTS` no-ops
- * here). Small/typical tenants are unaffected.
+ * DEPLOY-TIME LOCK: this is a plain (non-CONCURRENT) CREATE INDEX — Kysely runs
+ * each migration in a transaction, so CONCURRENTLY is impossible HERE, and the
+ * build would take a SHARE lock that BLOCKS writes on `pages` for its duration
+ * (the text_content GIN build can take minutes on a large tenant). To avoid that,
+ * `ensureConcurrentIndexes` (database/concurrent-indexes.ts) now pre-builds this
+ * index with CREATE INDEX CONCURRENTLY (no transaction) BEFORE the migrator runs,
+ * so on an existing DB the `IF NOT EXISTS` below no-ops and no write lock is taken.
+ * On a fresh DB the pre-build is skipped and this builds it on an empty table
+ * where the lock is irrelevant. Keep this create in lockstep with the CANONICAL
+ * definition in CONCURRENT_INDEXES (same expression + opclass).
  */
 export async function up(db: Kysely<any>): Promise<void> {
   // The title predicate is served by #348's idx_pages_title_trgm — see header.

apps/server/src/database/migrations/20260707T120000-ai-chat-metadata.ts

@@ -0,0 +1,24 @@
+import { type Kysely, sql } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  // Chat-level metadata bag (#490). First use: the deferred-tool ACTIVATION set
+  // (`activatedTools`) is persisted here so it survives across turns — previously
+  // the set was reset every turn, forcing the model to re-run loadTools and pay a
+  // fresh round-trip to re-activate the same tools each turn. On load the stored
+  // set is intersected with the current valid deferred names, so an allowlist /
+  // role change can never inject a now-nonexistent tool.
+  //
+  // jsonb, defaulted to '{}' so every row (incl. pre-migration ones, backfilled
+  // by the default) is a readable object — the app never has to null-guard the
+  // bag itself, only individual keys.
+  await db.schema
+    .alterTable('ai_chats')
+    .addColumn('metadata', 'jsonb', (col) =>
+      col.notNull().defaultTo(sql`'{}'::jsonb`),
+    )
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.alterTable('ai_chats').dropColumn('metadata').execute();
+}

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

@@ -78,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: jsonbBind(values.toolAllowlist),
+        // preserveEmpty (#476): `[]` is a real value here (deny-all), distinct
+        // from null ("no restriction") — it must round-trip as `[]`, not null.
+        toolAllowlist: jsonbBind(values.toolAllowlist, { preserveEmpty: true }),
         // Plain text column: blank/whitespace-only guidance is stored as null.
         instructions: blankToNull(values.instructions),
         enabled: values.enabled ?? true,
@@ -111,7 +113,10 @@ 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 = jsonbBind(patch.toolAllowlist);
+      // preserveEmpty (#476): see insert — `[]` (deny-all) must not become null.
+      set.toolAllowlist = jsonbBind(patch.toolAllowlist, {
+        preserveEmpty: true,
+      });
     }
     if (patch.instructions !== undefined) {
       // Blank/whitespace-only guidance clears the column (stored as null).
@@ -158,7 +163,9 @@ export function blankToNull(value: string | null | undefined): string | null {
  * 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).
+ * array with a non-string element all become null. NOTE: null here only means
+ * "could not parse" — the null-vs-deny-all policy decision lives in
+ * normalizeRow (#476: present-but-corrupt fails CLOSED to `[]`).
  */
 export function parseToolAllowlist(value: unknown): string[] | null {
   // Shape guard only; the legacy double-encoding self-heal lives in
@@ -173,17 +180,20 @@ export function parseToolAllowlist(value: unknown): 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.
+ * FAIL-CLOSED (#476): a stored value that is PRESENT but cannot be parsed into
+ * a string[] (corrupt JSON, a non-array, non-string elements) degrades to `[]`
+ * = deny-all, so a corrupted allowlist can never silently widen to "the agent
+ * gets ALL of the server's tools" (the old fail-open null). An error line is
+ * logged (server id only, never the contents) so the admin can repair the row.
+ * A column that is truly NULL/absent stays `null` = "no restriction".
  */
 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)`,
+    logger.error(
+      `Corrupt tool_allowlist for MCP server ${row.id}; failing closed (NO tools allowed) — re-save the server's allowlist to repair it`,
     );
+    return { ...row, toolAllowlist: [] };
   }
   return { ...row, toolAllowlist: parsed };
 }

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

@@ -1,7 +1,7 @@
 import { Injectable } from '@nestjs/common';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
-import { dbOrTx, executeTx } from '../../utils';
+import { dbOrTx, executeTx, registerAfterCommit } from '../../utils';
 import {
   InsertablePage,
   Page,
@@ -349,14 +349,23 @@ export class PageRepo {
     pageId: string,
     deletedById: string,
     workspaceId: string,
+    // Optional caller transaction. When passed, the reads + soft-delete run in
+    // THAT transaction (so a caller holding a `FOR UPDATE` lock on the row — e.g.
+    // the temporary-note sweeper — can delete under the lock without deadlocking
+    // on a nested independent transaction) and the PAGE_SOFT_DELETED broadcast is
+    // deferred to the caller's COMMIT via registerAfterCommit (so a rolled-back
+    // delete never broadcasts). With no trx the behaviour is unchanged: own
+    // transaction, broadcast right after it commits.
+    existingTrx?: KyselyTransaction,
   ): Promise<void> {
     const currentDate = new Date();
+    const readDb = dbOrTx(this.db, existingTrx);
 
     // Read the root snapshot up front so PAGE_SOFT_DELETED can carry it without
     // a post-commit DB read (variant A). Only the root of the deleted subtree is
     // needed for the tree broadcast — the client `treeModel.remove` drops all
     // descendants, so we don't snapshot/broadcast every descendant.
-    const rootSnapshot = await this.db
+    const rootSnapshot = await readDb
       .selectFrom('pages')
       .select([
         'id',
@@ -371,7 +380,7 @@ export class PageRepo {
       .where('deletedAt', 'is', null)
       .executeTakeFirst();
 
-    const descendants = await this.db
+    const descendants = await readDb
       .withRecursive('page_descendants', (db) =>
         db
           .selectFrom('pages')
@@ -393,39 +402,60 @@ export class PageRepo {
     const pageIds = descendants.map((d) => d.id);
 
     if (pageIds.length > 0) {
-      await executeTx(this.db, async (trx) => {
-        await trx
-          .updateTable('pages')
-          .set({
-            deletedById: deletedById,
-            deletedAt: currentDate,
-          })
-          .where('id', 'in', pageIds)
-          .where('deletedAt', 'is', null)
-          .execute();
+      // Reuse the caller's transaction when given (executeTx passes it straight
+      // through), else own a fresh one.
+      await executeTx(
+        this.db,
+        async (trx) => {
+          await trx
+            .updateTable('pages')
+            .set({
+              deletedById: deletedById,
+              deletedAt: currentDate,
+            })
+            .where('id', 'in', pageIds)
+            .where('deletedAt', 'is', null)
+            .execute();
 
-        await trx.deleteFrom('shares').where('pageId', 'in', pageIds).execute();
-      });
+          await trx
+            .deleteFrom('shares')
+            .where('pageId', 'in', pageIds)
+            .execute();
+        },
+        existingTrx,
+      );
 
-      this.eventEmitter.emit(EventName.PAGE_SOFT_DELETED, {
-        pageIds: pageIds,
-        workspaceId,
-        // Root-only snapshot: one `deleteTreeNode` is enough, the client removes
-        // the whole subtree. Skip if the root vanished between the two reads.
-        pages: rootSnapshot
-          ? [
-              {
-                id: rootSnapshot.id,
-                slugId: rootSnapshot.slugId,
-                title: rootSnapshot.title,
-                icon: rootSnapshot.icon,
-                position: rootSnapshot.position,
-                spaceId: rootSnapshot.spaceId,
-                parentPageId: rootSnapshot.parentPageId,
-              },
-            ]
-          : [],
-      });
+      const emitSoftDeleted = () => {
+        this.eventEmitter.emit(EventName.PAGE_SOFT_DELETED, {
+          pageIds: pageIds,
+          workspaceId,
+          // Root-only snapshot: one `deleteTreeNode` is enough, the client
+          // removes the whole subtree. Skip if the root vanished between reads.
+          pages: rootSnapshot
+            ? [
+                {
+                  id: rootSnapshot.id,
+                  slugId: rootSnapshot.slugId,
+                  title: rootSnapshot.title,
+                  icon: rootSnapshot.icon,
+                  position: rootSnapshot.position,
+                  spaceId: rootSnapshot.spaceId,
+                  parentPageId: rootSnapshot.parentPageId,
+                },
+              ]
+            : [],
+        });
+      };
+
+      if (existingTrx) {
+        // Inside a caller transaction: the delete above is NOT committed yet.
+        // Defer the tree broadcast to the caller's commit so a rolled-back delete
+        // never broadcasts a phantom removal.
+        registerAfterCommit(existingTrx, emitSoftDeleted);
+      } else {
+        // Own transaction already committed above — broadcast now.
+        emitSoftDeleted();
+      }
     }
   }
 

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

@@ -3,7 +3,7 @@ import { CACHE_MANAGER } from '@nestjs/cache-manager';
 import { Cache } from 'cache-manager';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
-import { dbOrTx } from '../../utils';
+import { dbOrTx, registerAfterCommit } from '../../utils';
 import {
   InsertableWorkspace,
   UpdatableWorkspace,
@@ -80,16 +80,30 @@ export class WorkspaceRepo {
    */
   private async bustWorkspaceCache(
     workspace?: Pick<Workspace, 'hostname'> | undefined,
+    trx?: KyselyTransaction,
   ): Promise<void> {
-    try {
-      await this.cacheManager.del(CacheKey.WORKSPACE_SELF_HOSTED);
-      if (workspace?.hostname) {
-        await this.cacheManager.del(
-          CacheKey.WORKSPACE_BY_HOST(workspace.hostname),
-        );
+    const del = async () => {
+      try {
+        await this.cacheManager.del(CacheKey.WORKSPACE_SELF_HOSTED);
+        if (workspace?.hostname) {
+          await this.cacheManager.del(
+            CacheKey.WORKSPACE_BY_HOST(workspace.hostname),
+          );
+        }
+      } catch {
+        // cache is best-effort; TTL is the backstop
       }
-    } catch {
-      // cache is best-effort; TTL is the backstop
+    };
+    if (trx) {
+      // Inside a caller transaction the write is NOT yet committed: busting now
+      // opens a repopulation window (a concurrent reader reloads the cache with
+      // the pre-commit / stale row, which then survives until TTL). Defer the del
+      // to the transaction's commit (drained by the owning executeTx) (#495).
+      registerAfterCommit(trx, del);
+    } else {
+      // No transaction: the mutation above already auto-committed, so this del is
+      // already post-commit.
+      await del();
     }
   }
 
@@ -180,7 +194,7 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
-    await this.bustWorkspaceCache(workspace);
+    await this.bustWorkspaceCache(workspace, trx);
     return workspace;
   }
 
@@ -195,7 +209,7 @@ export class WorkspaceRepo {
       .returning(this.baseFields)
       .executeTakeFirst();
     // Bust the cached "not found" so a fresh install / new tenant is seen at once.
-    await this.bustWorkspaceCache(workspace);
+    await this.bustWorkspaceCache(workspace, trx);
     return workspace;
   }
 
@@ -249,7 +263,7 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
-    await this.bustWorkspaceCache(workspace);
+    await this.bustWorkspaceCache(workspace, trx);
     return workspace;
   }
 
@@ -271,7 +285,7 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
-    await this.bustWorkspaceCache(workspace);
+    await this.bustWorkspaceCache(workspace, trx);
     return workspace;
   }
 
@@ -326,7 +340,7 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
-    await this.bustWorkspaceCache(workspace);
+    await this.bustWorkspaceCache(workspace, trx);
     return workspace;
   }
 
@@ -354,7 +368,7 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
-    await this.bustWorkspaceCache(workspace);
+    await this.bustWorkspaceCache(workspace, trx);
     return workspace;
   }
 
@@ -376,7 +390,7 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
-    await this.bustWorkspaceCache(workspace);
+    await this.bustWorkspaceCache(workspace, trx);
     return workspace;
   }
 
@@ -398,7 +412,7 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
-    await this.bustWorkspaceCache(workspace);
+    await this.bustWorkspaceCache(workspace, trx);
     return workspace;
   }
 

apps/server/src/database/services/migration.service.ts

@@ -4,6 +4,7 @@ import { promises as fs } from 'fs';
 import { Migrator, FileMigrationProvider } from 'kysely';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB } from '@docmost/db/types/kysely.types';
+import { ensureConcurrentIndexes } from '@docmost/db/concurrent-indexes';
 
 @Injectable()
 export class MigrationService {
@@ -12,6 +13,16 @@ export class MigrationService {
   constructor(@InjectKysely() private readonly db: KyselyDB) {}
 
   async migrateToLatest(): Promise<void> {
+    // Build write-blocking trigram indexes CONCURRENTLY (no transaction) BEFORE
+    // the migrator runs, so the corresponding in-migration `CREATE INDEX IF NOT
+    // EXISTS` no-ops instead of taking a SHARE lock on `pages` during deploy
+    // (#495). Best-effort: on a fresh DB (no `pages`/`f_unaccent` yet) this is a
+    // no-op and the migrations build the index normally.
+    await ensureConcurrentIndexes(this.db, (message, error) => {
+      if (error) this.logger.warn(`${message}: ${String(error)}`);
+      else this.logger.log(message);
+    });
+
     const migrator = new Migrator({
       db: this.db,
       provider: new FileMigrationProvider({

apps/server/src/database/types/db.d.ts

@@ -606,6 +606,9 @@ export interface AiChats {
   // The document the chat was created in (open page at first message). NULL =>
   // started outside any document. ON DELETE SET NULL on the page FK.
   pageId: string | null;
+  // Chat-level metadata bag (#490). jsonb, defaulted to '{}'. First key:
+  // `activatedTools` — the deferred-tool activation set persisted across turns.
+  metadata: Generated<Json>;
   createdAt: Generated<Timestamp>;
   updatedAt: Generated<Timestamp>;
   deletedAt: Timestamp | null;

apps/server/src/database/utils.ts

@@ -6,16 +6,76 @@ import { KyselyDB, KyselyTransaction } from './types/kysely.types';
  * If an existing transaction is provided, it directly executes the callback with it.
  * Otherwise, it starts a new transaction using the provided database instance and executes the callback within that transaction.
  */
+/**
+ * Post-commit side-effect hooks, keyed by the transaction they were registered
+ * against. A WeakMap so an abandoned/never-drained transaction's entry is GC'd
+ * with the trx object (no leak). Used by {@link registerAfterCommit} /
+ * {@link executeTx}.
+ */
+const afterCommitHooks = new WeakMap<
+  KyselyTransaction,
+  Array<() => Promise<void> | void>
+>();
+
+/**
+ * Register a side effect to run ONLY AFTER the transaction that owns `trx`
+ * commits. THE fix for "bust the cache inside the open transaction" bugs: a
+ * cache-invalidation (or any read-your-write-visible side effect) done while the
+ * writing transaction is still open opens a window where a concurrent reader
+ * repopulates the cache with the PRE-COMMIT (stale) row, so after commit the
+ * cache holds the old value until its TTL. Deferring the effect to post-commit
+ * closes that window.
+ *
+ * The hook is drained by the OUTERMOST {@link executeTx} that actually owns
+ * (created) this transaction — so registering against a passed-through
+ * `existingTrx` still fires at the real commit boundary, not at the inner call.
+ * NOTE: a hook registered against a transaction that was NOT created via
+ * `executeTx` (untracked) will never be drained — always create transactions
+ * through `executeTx` when you rely on post-commit hooks.
+ */
+export function registerAfterCommit(
+  trx: KyselyTransaction,
+  hook: () => Promise<void> | void,
+): void {
+  const existing = afterCommitHooks.get(trx);
+  if (existing) existing.push(hook);
+  else afterCommitHooks.set(trx, [hook]);
+}
+
 export async function executeTx<T>(
   db: KyselyDB,
   callback: (trx: KyselyTransaction) => Promise<T>,
   existingTrx?: KyselyTransaction,
 ): Promise<T> {
   if (existingTrx) {
-    return await callback(existingTrx); // Execute callback with existing transaction
-  } else {
-    return await db.transaction().execute((trx) => callback(trx)); // Start new transaction and execute callback
+    // Reuse the caller's transaction. Any post-commit hooks registered here are
+    // drained by the OUTER executeTx that created `existingTrx`, at the true
+    // commit boundary — so we must NOT drain them now.
+    return await callback(existingTrx);
   }
+  // We OWN this transaction: run the body, then (only once it has COMMITTED)
+  // drain the post-commit hooks registered against it during the body.
+  let ownTrx: KyselyTransaction | undefined;
+  const result = await db.transaction().execute((trx) => {
+    ownTrx = trx;
+    return callback(trx);
+  });
+  if (ownTrx) {
+    const hooks = afterCommitHooks.get(ownTrx);
+    if (hooks) {
+      afterCommitHooks.delete(ownTrx);
+      for (const hook of hooks) {
+        // Best-effort: a failed side effect (e.g. a cache del) must not fail the
+        // already-committed transaction.
+        try {
+          await hook();
+        } catch {
+          // swallow — the durable write already committed
+        }
+      }
+    }
+  }
+  return result;
 }
 
 /*
@@ -78,18 +138,30 @@ export function violatedConstraint(err: unknown): string | undefined {
  * 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 `[]`/`{}`.
+ * Returns `null` for null/undefined. By default it ALSO returns `null` for
+ * "empty" values (an empty array, or an object with no own enumerable keys) —
+ * most callers treat empty as "clear/unset", so an empty config never
+ * round-trips as `[]`/`{}`.
+ *
+ * `preserveEmpty` (issue #476) opts a column OUT of that empty-to-null
+ * normalization so `[]`/`{}` are persisted as real jsonb values. Needed where
+ * empty and null mean DIFFERENT things: an empty `tool_allowlist` is
+ * deny-all ("zero tools allowed"), while null is "no restriction" — collapsing
+ * `[]` to null silently widened deny-all to allow-all. Deliberately an opt-in
+ * flag, NOT a global change: the other jsonb callers (model_config, source)
+ * keep the empty-means-unset contract.
  */
 export function jsonbBind<T>(
   value: T | null | undefined,
+  opts?: { preserveEmpty?: boolean },
 ): 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;
+  if (!opts?.preserveEmpty) {
+    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-settings.service.spec.ts

@@ -99,10 +99,12 @@ describe('AiSettingsService.getMasked reindex progress', () => {
     // actually pins the progress.total branch rather than coincidentally
     // matching the DB fallback. With fix #1 the two sources agree in practice,
     // but getMasked must still return progress.total when a record is active.
+    const startedAt = Date.now();
     reindexProgress.get.mockResolvedValue({
       total: 500,
       done: 120,
-      startedAt: Date.now(),
+      startedAt,
+      runId: 'run-abc',
     });
 
     const masked = await service.getMasked(WORKSPACE_ID);
@@ -110,6 +112,10 @@ describe('AiSettingsService.getMasked reindex progress', () => {
     expect(masked.indexedPages).toBe(120); // progress.done, not DB 478
     expect(masked.totalPages).toBe(500); // progress.total, not DB 478
     expect(masked.reindexing).toBe(true);
+    // The status payload must carry the run identity so the client can key its
+    // poll on it (a changed runId => a NEW run).
+    expect(masked.runId).toBe('run-abc');
+    expect(masked.reindexStartedAt).toBe(startedAt);
   });
 
   it('falls back to countIndexedPages when no reindex is active', async () => {
@@ -121,6 +127,10 @@ describe('AiSettingsService.getMasked reindex progress', () => {
     expect(masked.indexedPages).toBe(478);
     expect(masked.totalPages).toBe(478);
     expect(masked.reindexing).toBe(false);
+    // No active run -> no run identity surfaced (the client keeps its prior
+    // steady-state behaviour).
+    expect(masked.runId).toBeUndefined();
+    expect(masked.reindexStartedAt).toBeUndefined();
   });
 });
 

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

@@ -245,6 +245,9 @@ export class AiSettingsService {
       // Max context window for the chat header badge denominator. Stored as
       // ::text; 0/unset/invalid = no limit (undefined).
       chatContextWindow: parsePositiveInt(provider.chatContextWindow),
+      // RAW stored value (#490): the replay budgeter reads this to distinguish an
+      // explicit `0` (off-switch) from unset, which parsePositiveInt cannot.
+      chatContextWindowRaw: provider.chatContextWindow,
       // Plain passthrough; getChatModel defaults unset to 'openai-compatible'.
       chatApiStyle: provider.chatApiStyle,
       // Cheap model id for the anonymous public-share assistant; reuses the chat
@@ -371,6 +374,12 @@ export class AiSettingsService {
       totalPages,
       // Optional hint for the client: a reindex run is currently in progress.
       reindexing: progress != null,
+      // Per-run identity so the client can key its poll on a stable run id and
+      // reset its per-run state when a NEW run starts. Present only while a run
+      // is active; `runId` may be '' for a legacy/degraded record (the client
+      // treats that as "no identity").
+      runId: progress?.runId,
+      reindexStartedAt: progress?.startedAt,
     };
   }
 

apps/server/src/integrations/ai/ai.service.provider-fetch.spec.ts

@@ -0,0 +1,86 @@
+// `.provider` alone cannot prove the gemini/ollama chat factories were built
+// with the instrumented streaming fetch — a regression dropping it (which drops
+// them back to the global undici fetch: no keep-alive recycle, no reset retries,
+// unbounded silence timeout; incident classes #140/#175/#310) would still pass.
+// So mock the factories and assert the exact fetch argument. jest.mock is
+// module-scoped, hence a dedicated file.
+
+const mockGeminiModel = { provider: 'google.generative-ai', modelId: 'm' };
+const mockOllamaModel = { provider: 'ollama.chat', modelId: 'm' };
+
+// jest allows `mock`-prefixed vars inside a jest.mock factory.
+const mockCreateGoogle = jest.fn((_settings: unknown) => () => mockGeminiModel);
+const mockCreateOllama = jest.fn((_settings: unknown) => () => mockOllamaModel);
+
+jest.mock('@ai-sdk/google', () => ({
+  createGoogleGenerativeAI: (settings: unknown) => mockCreateGoogle(settings),
+}));
+jest.mock('ai-sdk-ollama', () => ({
+  createOllama: (settings: unknown) => mockCreateOllama(settings),
+}));
+
+import { AiService } from './ai.service';
+
+describe('AiService.getChatModel provider transport fetch (gemini/ollama)', () => {
+  function serviceWith(cfg: Record<string, unknown>) {
+    const aiSettings = {
+      resolve: jest.fn().mockResolvedValue(cfg),
+    };
+    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(() => {
+    mockCreateGoogle.mockClear();
+    mockCreateOllama.mockClear();
+  });
+
+  it('builds the gemini chat model with the instrumented streaming fetch', async () => {
+    await serviceWith({
+      driver: 'gemini',
+      chatModel: 'gemini-2.5-pro',
+      apiKey: 'the-key',
+    }).getChatModel('ws-1');
+    expect(mockCreateGoogle).toHaveBeenCalledTimes(1);
+    expect(mockCreateGoogle).toHaveBeenCalledWith(
+      expect.objectContaining({
+        apiKey: 'the-key',
+        fetch: expect.any(Function),
+      }),
+    );
+  });
+
+  it('builds the ollama chat model with the instrumented streaming fetch', async () => {
+    await serviceWith({
+      driver: 'ollama',
+      chatModel: 'llama3',
+      baseUrl: 'http://localhost:11434/api',
+    }).getChatModel('ws-1');
+    expect(mockCreateOllama).toHaveBeenCalledTimes(1);
+    expect(mockCreateOllama).toHaveBeenCalledWith(
+      expect.objectContaining({
+        baseURL: 'http://localhost:11434/api',
+        fetch: expect.any(Function),
+      }),
+    );
+  });
+
+  it('reuses ONE service-lifetime fetch instance across both providers', async () => {
+    const svc = serviceWith({
+      driver: 'gemini',
+      chatModel: 'gemini-2.5-pro',
+      apiKey: 'k',
+    });
+    await svc.getChatModel('ws-1');
+    const geminiFetch = mockCreateGoogle.mock.calls[0][0] as { fetch: unknown };
+    // Same instance on a second call — the fetch is held for the service
+    // lifetime to reuse the streaming dispatcher's connection pool.
+    await svc.getChatModel('ws-1');
+    const geminiFetch2 = mockCreateGoogle.mock.calls[1][0] as { fetch: unknown };
+    expect(geminiFetch.fetch).toBe(geminiFetch2.fetch);
+  });
+});

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

@@ -190,10 +190,22 @@ export class AiService {
         }).chat(chatModel);
       }
       case 'gemini':
-        return createGoogleGenerativeAI({ apiKey })(chatModel);
+        // Route gemini through the same instrumented streaming fetch as openai
+        // (finite silence timeouts + keep-alive recycling + pre-response
+        // connection-reset retry). Without it the provider ran on the global
+        // undici fetch — no keep-alive recycle, no reset retries, default
+        // (unbounded silence) timeout — so incident classes #140/#175/#310 were
+        // reproducible for gemini too.
+        return createGoogleGenerativeAI({
+          apiKey,
+          fetch: this.aiProviderFetch,
+        })(chatModel);
       case 'ollama':
-        // Ollama needs no API key.
-        return createOllama({ baseURL: baseUrl })(chatModel);
+        // Ollama needs no API key. Same transport hardening as above (#140/#175/#310).
+        return createOllama({
+          baseURL: baseUrl,
+          fetch: this.aiProviderFetch,
+        })(chatModel);
       default:
         throw new AiNotConfiguredException();
     }

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

@@ -105,6 +105,10 @@ export interface ResolvedAiConfig extends Partial<AiProviderSettings> {
   // Max context window in tokens; surfaced to the chat header badge as the
   // "current / max" denominator. 0/unset = no limit.
   chatContextWindow?: number;
+  // RAW stored context window (::text), BEFORE parsePositiveInt collapses `0` and
+  // unset to `undefined`. The #490 replay budgeter needs the raw value to honor an
+  // explicit `0` off-switch distinctly from "unset -> flat default".
+  chatContextWindowRaw?: string | number;
   // Cheap model id for the public-share assistant; reuses the chat creds.
   publicShareChatModel?: string;
   // Agent-role id whose persona the public-share assistant adopts (empty/unset
@@ -149,4 +153,14 @@ export interface MaskedAiSettings {
   // True while a full workspace reindex is actively running (the counts above
   // then reflect the live run progress rather than the steady-state DB count).
   reindexing?: boolean;
+  // Identity of the ACTIVE reindex run (present only while `reindexing`). The
+  // client keys its poll on `runId`: a changed value means a NEW run (reset the
+  // per-run poll state it latched), the same value means the run it is already
+  // watching — removing the "same run or a fresh one?" ambiguity a stale
+  // pre-reindex snapshot otherwise causes. Absent/empty degrades gracefully.
+  runId?: string;
+  // Epoch-ms the active run started (present only while `reindexing`). Paired
+  // with `runId` so a run that restarts with the same (recycled) id is still
+  // seen as new.
+  reindexStartedAt?: number;
 }

apps/server/src/integrations/ai/embedding-reindex-progress.service.spec.ts

@@ -48,19 +48,38 @@ describe('EmbeddingReindexProgressService', () => {
   }
 
   describe('get', () => {
-    it('maps a valid hash to a ReindexProgress object', async () => {
+    it('maps a valid hash to a ReindexProgress object (incl. the run identity)', async () => {
       const { redis, hgetall } = makeRedis();
-      hgetall.mockResolvedValue({ total: '478', done: '120', startedAt: '1000' });
+      hgetall.mockResolvedValue({
+        total: '478',
+        done: '120',
+        startedAt: '1000',
+        runId: 'run-xyz',
+      });
       const service = makeService(redis);
 
       await expect(service.get(WORKSPACE_ID)).resolves.toEqual({
         total: 478,
         done: 120,
         startedAt: 1000,
+        runId: 'run-xyz',
       });
       expect(hgetall).toHaveBeenCalledWith(KEY);
     });
 
+    it('degrades a missing runId to an empty string (legacy/partial record)', async () => {
+      const { redis, hgetall } = makeRedis();
+      // A record written before runId existed: get() must still succeed and
+      // report runId='' so the client treats it as "no identity", never breaks.
+      hgetall.mockResolvedValue({ total: '10', done: '3', startedAt: '5' });
+      await expect(makeService(redis).get(WORKSPACE_ID)).resolves.toEqual({
+        total: 10,
+        done: 3,
+        startedAt: 5,
+        runId: '',
+      });
+    });
+
     it('returns null for an empty hash (no record)', async () => {
       const { redis, hgetall } = makeRedis();
       hgetall.mockResolvedValue({});
@@ -87,11 +106,17 @@ describe('EmbeddingReindexProgressService', () => {
 
     it('coerces a non-finite startedAt to 0', async () => {
       const { redis, hgetall } = makeRedis();
-      hgetall.mockResolvedValue({ total: '10', done: '2', startedAt: 'nope' });
+      hgetall.mockResolvedValue({
+        total: '10',
+        done: '2',
+        startedAt: 'nope',
+        runId: 'run-1',
+      });
       await expect(makeService(redis).get(WORKSPACE_ID)).resolves.toEqual({
         total: 10,
         done: 2,
         startedAt: 0,
+        runId: 'run-1',
       });
     });
 
@@ -115,6 +140,21 @@ describe('EmbeddingReindexProgressService', () => {
       expect(multiObj.exec).toHaveBeenCalledTimes(1);
     });
 
+    it('mints a fresh non-empty runId into the record on each start', async () => {
+      const { redis, multiObj } = makeRedis();
+      const service = makeService(redis);
+      await service.start(WORKSPACE_ID, 1);
+      await service.start(WORKSPACE_ID, 1);
+
+      const firstRunId = multiObj.hset.mock.calls[0][1].runId;
+      const secondRunId = multiObj.hset.mock.calls[1][1].runId;
+      expect(typeof firstRunId).toBe('string');
+      expect(firstRunId).not.toBe('');
+      // Each run gets its OWN identity so the client can tell a re-trigger apart
+      // from the run it is already watching.
+      expect(secondRunId).not.toBe(firstRunId);
+    });
+
     it('defaults the expire TTL to the full 1h record TTL', async () => {
       const { redis, multiObj } = makeRedis();
       await makeService(redis).start(WORKSPACE_ID, 478);

apps/server/src/integrations/ai/embedding-reindex-progress.service.ts

@@ -1,17 +1,28 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { RedisService } from '@nestjs-labs/nestjs-ioredis';
+import { randomUUID } from 'node:crypto';
 import type { Redis } from 'ioredis';
 
 /**
  * Live progress of an in-flight workspace embeddings reindex run.
  * `total` is the number of pages the run will process, `done` how many it has
  * already processed (success OR handled failure), `startedAt` the epoch-ms the
- * record was created.
+ * record was created, and `runId` a per-run identity minted at `start()`.
+ *
+ * `runId` gives each reindex run a stable identity so a poller can tell "same
+ * run I've been watching" from "a NEW run started" WITHOUT guessing from the
+ * progress counters (the ambiguity that a stale pre-reindex snapshot vs a fresh
+ * run otherwise causes — the bug class fixed twice under #262). It is best-
+ * effort like the rest of this record: a record written before this field
+ * existed (or a Redis hiccup) yields an empty `runId`, which the client must
+ * treat as "no identity available" and degrade to its prior behaviour, never
+ * break.
  */
 export interface ReindexProgress {
   total: number;
   done: number;
   startedAt: number;
+  runId: string;
 }
 
 /** Redis key namespace for the per-workspace reindex-progress record. */
@@ -86,12 +97,18 @@ export class EmbeddingReindexProgressService {
   ): Promise<void> {
     const key = this.key(workspaceId);
     try {
+      // A fresh identity per run so the client poll can key on it: a changed
+      // runId means a genuinely NEW run (reset any latched per-run poll state),
+      // the same runId means the run the client is already watching. Best-effort
+      // like the counters — never surfaced to the user, only used to disambiguate.
+      const runId = randomUUID();
       await this.redis
         .multi()
         .hset(key, {
           total: String(total),
           done: '0',
           startedAt: String(Date.now()),
+          runId,
         })
         .expire(key, ttlSeconds)
         .exec();
@@ -150,7 +167,15 @@ export class EmbeddingReindexProgressService {
       const done = Number(data.done);
       const startedAt = Number(data.startedAt);
       if (!Number.isFinite(total) || !Number.isFinite(done)) return null;
-      return { total, done, startedAt: Number.isFinite(startedAt) ? startedAt : 0 };
+      // `runId` degrades gracefully: a pre-existing record (written before this
+      // field) or a stripped value reads as '' — the client treats that as "no
+      // identity" and keeps its prior behaviour rather than breaking the poll.
+      return {
+        total,
+        done,
+        startedAt: Number.isFinite(startedAt) ? startedAt : 0,
+        runId: typeof data.runId === 'string' ? data.runId : '',
+      };
     } catch (err) {
       this.logger.warn(
         `reindex-progress read failed for workspace ${workspaceId}; ` +

apps/server/src/integrations/audit/audit.module.ts

@@ -1,14 +1,19 @@
 import { Global, Module } from '@nestjs/common';
-import { AUDIT_SERVICE, NoopAuditService } from './audit.service';
+import { AUDIT_SERVICE } from './audit.service';
+import { DatabaseAuditService } from './database-audit.service';
 
+// #496: bind the audit token to a real DB-backed trail (was NoopAuditService,
+// which silently dropped every event). Kysely (@Global DatabaseModule) and
+// ClsService (@Global ClsModule) are both globally available, so this module
+// needs no extra imports.
 @Global()
 @Module({
   providers: [
     {
       provide: AUDIT_SERVICE,
-      useClass: NoopAuditService,
+      useClass: DatabaseAuditService,
     },
   ],
   exports: [AUDIT_SERVICE],
 })
-export class NoopAuditModule {}
+export class AuditModule {}

apps/server/src/integrations/audit/database-audit.service.spec.ts

@@ -0,0 +1,198 @@
+import { Logger } from '@nestjs/common';
+import { DatabaseAuditService } from './database-audit.service';
+import { AUDIT_CONTEXT_KEY } from '../../common/middlewares/audit-context.middleware';
+import { AuditEvent, AuditResource } from '../../common/events/audit-events';
+
+/**
+ * Observable-property coverage for the DB-backed audit trail (#496): every
+ * assertion pins what actually reaches the `audit` table (or that nothing does),
+ * driven through a chainable Kysely mock that captures the inserted rows.
+ */
+describe('DatabaseAuditService', () => {
+  function makeService(clsContext: any) {
+    const inserted: any[] = [];
+    const updated: any[] = [];
+    let failNextInsert = false;
+
+    const db: any = {
+      insertInto: jest.fn(() => ({
+        values: jest.fn((rows: any) => ({
+          execute: jest.fn(async () => {
+            if (failNextInsert) {
+              failNextInsert = false;
+              throw new Error('boom');
+            }
+            inserted.push(rows);
+          }),
+        })),
+      })),
+      updateTable: jest.fn(() => ({
+        set: jest.fn((patch: any) => ({
+          where: jest.fn(() => ({
+            execute: jest.fn(async () => {
+              updated.push(patch);
+            }),
+          })),
+        })),
+      })),
+    };
+
+    const store: Record<string, any> = { [AUDIT_CONTEXT_KEY]: clsContext };
+    const cls: any = {
+      get: jest.fn((key: string) => store[key]),
+      set: jest.fn((key: string, val: any) => {
+        store[key] = val;
+      }),
+    };
+
+    const service = new DatabaseAuditService(db, cls);
+    return {
+      service,
+      inserted,
+      updated,
+      cls,
+      store,
+      failInsert: () => {
+        failNextInsert = true;
+      },
+    };
+  }
+
+  const applyPayload = () => ({
+    event: AuditEvent.COMMENT_SUGGESTION_APPLIED,
+    resourceType: AuditResource.COMMENT,
+    resourceId: 'c-1',
+    spaceId: 'space-1',
+    metadata: { pageId: 'p-1', suggestedText: 'new', decidedBy: 'u-2' },
+  });
+
+  const ctx = (over?: any) => ({
+    workspaceId: 'ws-1',
+    actorId: 'u-2',
+    actorType: 'user',
+    ipAddress: '10.0.0.1',
+    userAgent: 'jest',
+    ...over,
+  });
+
+  it('log() persists a row with the CLS context merged onto the payload', async () => {
+    const { service, inserted } = makeService(ctx());
+    service.log(applyPayload());
+    // log() is fire-and-forget; flush the microtask queue.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(inserted).toHaveLength(1);
+    expect(inserted[0]).toMatchObject({
+      workspaceId: 'ws-1',
+      actorId: 'u-2',
+      actorType: 'user',
+      event: AuditEvent.COMMENT_SUGGESTION_APPLIED,
+      resourceType: AuditResource.COMMENT,
+      resourceId: 'c-1',
+      spaceId: 'space-1',
+      ipAddress: '10.0.0.1',
+      metadata: { pageId: 'p-1', suggestedText: 'new', decidedBy: 'u-2' },
+    });
+  });
+
+  it('log() is a no-op when there is no workspace in scope', async () => {
+    const { service, inserted } = makeService(ctx({ workspaceId: null }));
+    service.log(applyPayload());
+    await Promise.resolve();
+    expect(inserted).toHaveLength(0);
+  });
+
+  it('log() drops EXCLUDED_AUDIT_EVENTS (e.g. comment.created)', async () => {
+    const { service, inserted } = makeService(ctx());
+    service.log({
+      event: AuditEvent.COMMENT_CREATED,
+      resourceType: AuditResource.COMMENT,
+      resourceId: 'c-1',
+      spaceId: 'space-1',
+    });
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(inserted).toHaveLength(0);
+  });
+
+  it('a failed insert is swallowed with a warn and floats no rejection (audit is a side-record)', async () => {
+    // This pins the load-bearing swallow inside persist(). Because log() is
+    // fire-and-forget (`void this.persist(...)`), it always returns synchronously
+    // without throwing — so `not.toThrow()` alone would stay green even if the
+    // try/catch were removed. We instead observe the two effects the catch is
+    // responsible for: a warn IS emitted, and NO unhandled rejection floats.
+    // Removing persist()'s try/catch reddens both assertions (warn count 0 + a
+    // captured rejection).
+    const warnSpy = jest
+      .spyOn(Logger.prototype, 'warn')
+      .mockImplementation(() => undefined as any);
+    const rejections: unknown[] = [];
+    const onRejection = (err: unknown) => rejections.push(err);
+    process.on('unhandledRejection', onRejection);
+    try {
+      const { service, failInsert } = makeService(ctx());
+      failInsert();
+      expect(() => service.log(applyPayload())).not.toThrow();
+      // Flush microtasks so the rejected insert settles, then give any floated
+      // rejection a macrotask tick to be reported by the runtime.
+      await Promise.resolve();
+      await Promise.resolve();
+      await new Promise((r) => setImmediate(r));
+
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(String(warnSpy.mock.calls[0][0])).toContain(
+        'Failed to persist audit event',
+      );
+      expect(rejections).toHaveLength(0);
+    } finally {
+      process.off('unhandledRejection', onRejection);
+      warnSpy.mockRestore();
+    }
+  });
+
+  it('logWithContext() persists with an explicit (non-request) context', async () => {
+    const { service, inserted } = makeService(undefined);
+    service.logWithContext(applyPayload(), ctx({ actorType: 'system' }) as any);
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(inserted).toHaveLength(1);
+    expect(inserted[0].actorType).toBe('system');
+    expect(inserted[0].workspaceId).toBe('ws-1');
+  });
+
+  it('logBatchWithContext() inserts only non-excluded events', async () => {
+    const { service, inserted } = makeService(undefined);
+    service.logBatchWithContext(
+      [
+        applyPayload(),
+        {
+          event: AuditEvent.COMMENT_CREATED,
+          resourceType: AuditResource.COMMENT,
+          resourceId: 'c-2',
+        },
+      ],
+      ctx() as any,
+    );
+    await Promise.resolve();
+    await Promise.resolve();
+    // Batch is a single insert call carrying only the applied event.
+    expect(inserted).toHaveLength(1);
+    expect(inserted[0]).toHaveLength(1);
+    expect(inserted[0][0].event).toBe(AuditEvent.COMMENT_SUGGESTION_APPLIED);
+  });
+
+  it('setActorId / setActorType mutate the ambient CLS context', () => {
+    const { service, store } = makeService(ctx({ actorId: null }));
+    service.setActorId('u-9');
+    service.setActorType('api_key');
+    expect(store[AUDIT_CONTEXT_KEY].actorId).toBe('u-9');
+    expect(store[AUDIT_CONTEXT_KEY].actorType).toBe('api_key');
+  });
+
+  it('updateRetention() writes the workspace retention window', async () => {
+    const { service, updated } = makeService(ctx());
+    await service.updateRetention('ws-1', 30);
+    expect(updated).toEqual([{ auditRetentionDays: 30 }]);
+  });
+});

apps/server/src/integrations/audit/database-audit.service.ts

@@ -0,0 +1,160 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { InjectKysely } from 'nestjs-kysely';
+import { ClsService } from 'nestjs-cls';
+import { KyselyDB } from '@docmost/db/types/kysely.types';
+import {
+  AuditContext,
+  AUDIT_CONTEXT_KEY,
+} from '../../common/middlewares/audit-context.middleware';
+import {
+  AuditLogPayload,
+  ActorType,
+  EXCLUDED_AUDIT_EVENTS,
+} from '../../common/events/audit-events';
+import { AuditLogContext, IAuditService } from './audit.service';
+
+/**
+ * Minimal DB-backed audit trail (#496). Replaces NoopAuditService so that
+ * decision-bearing events — notably comment.suggestion_applied /
+ * comment.suggestion_dismissed, whose subject comment is HARD-DELETED on the
+ * childless path — leave a durable record of who decided what. Without this the
+ * events were emitted (comment.service / *.controller) but swallowed, so an
+ * applied/dismissed suggestion was unrecoverable once the row was gone.
+ *
+ * Rows land in the pre-existing `audit` table (migration 20260228T223532). The
+ * per-request actor/workspace/ip come from the CLS AuditContext populated by
+ * AuditContextMiddleware + AuditActorInterceptor; callers that run OUTSIDE a
+ * request (queue workers, imports) pass an explicit context via
+ * logWithContext / logBatchWithContext.
+ *
+ * Audit is a side-record: a write failure MUST NOT break the originating
+ * request, so every persistence path swallows its error with a warn. Events in
+ * EXCLUDED_AUDIT_EVENTS (high-volume/low-signal) are dropped.
+ */
+@Injectable()
+export class DatabaseAuditService implements IAuditService {
+  private readonly logger = new Logger(DatabaseAuditService.name);
+
+  constructor(
+    @InjectKysely() private readonly db: KyselyDB,
+    private readonly cls: ClsService,
+  ) {}
+
+  /**
+   * Persist a single event using the ambient request-scoped AuditContext. A
+   * no-op when there is no workspace in scope (the table's workspace_id is NOT
+   * NULL) or the event is excluded. Fire-and-forget: the returned promise is not
+   * awaited by hot callers, and its rejection is swallowed here.
+   */
+  log(payload: AuditLogPayload): void {
+    const context = this.cls?.get<AuditContext>(AUDIT_CONTEXT_KEY);
+    if (!context?.workspaceId) {
+      // No workspace in scope — nothing we can attribute the row to. This is
+      // expected for events emitted outside an HTTP request; those callers must
+      // use logWithContext instead.
+      return;
+    }
+    void this.persist(payload, {
+      workspaceId: context.workspaceId,
+      actorId: context.actorId ?? undefined,
+      actorType: context.actorType,
+      ipAddress: context.ipAddress ?? undefined,
+      userAgent: context.userAgent ?? undefined,
+    });
+  }
+
+  /** Persist a single event with an explicit (non-request) context. */
+  logWithContext(payload: AuditLogPayload, context: AuditLogContext): void {
+    if (!context?.workspaceId) return;
+    void this.persist(payload, context);
+  }
+
+  /** Persist a batch of events sharing one explicit context (imports). */
+  logBatchWithContext(
+    payloads: AuditLogPayload[],
+    context: AuditLogContext,
+  ): void {
+    if (!context?.workspaceId || payloads.length === 0) return;
+    const rows = payloads
+      .filter((p) => !EXCLUDED_AUDIT_EVENTS.has(p.event))
+      .map((p) => this.toRow(p, context));
+    if (rows.length === 0) return;
+    this.db
+      .insertInto('audit')
+      .values(rows)
+      .execute()
+      .catch((err: any) =>
+        this.logger.warn(`Failed to persist ${rows.length} audit events: ${err?.message}`),
+      );
+  }
+
+  /** Update the ambient request actor (e.g. after login resolves the user). */
+  setActorId(actorId: string): void {
+    const context = this.cls?.get<AuditContext>(AUDIT_CONTEXT_KEY);
+    if (context) {
+      context.actorId = actorId;
+      this.cls.set(AUDIT_CONTEXT_KEY, context);
+    }
+  }
+
+  /** Update the ambient request actor type (user | system | api_key). */
+  setActorType(actorType: ActorType): void {
+    const context = this.cls?.get<AuditContext>(AUDIT_CONTEXT_KEY);
+    if (context) {
+      context.actorType = actorType;
+      this.cls.set(AUDIT_CONTEXT_KEY, context);
+    }
+  }
+
+  /** Persist a workspace's audit-log retention window (days). */
+  async updateRetention(
+    workspaceId: string,
+    retentionDays: number,
+  ): Promise<void> {
+    try {
+      await this.db
+        .updateTable('workspaces')
+        .set({ auditRetentionDays: retentionDays })
+        .where('id', '=', workspaceId)
+        .execute();
+    } catch (err: any) {
+      this.logger.warn(
+        `Failed to update audit retention for workspace ${workspaceId}: ${err?.message}`,
+      );
+    }
+  }
+
+  private async persist(
+    payload: AuditLogPayload,
+    context: AuditLogContext,
+  ): Promise<void> {
+    if (EXCLUDED_AUDIT_EVENTS.has(payload.event)) return;
+    try {
+      await this.db
+        .insertInto('audit')
+        .values(this.toRow(payload, context))
+        .execute();
+    } catch (err: any) {
+      // Audit is a side-record; never let a failed write surface to the caller.
+      this.logger.warn(
+        `Failed to persist audit event ${payload.event}: ${err?.message}`,
+      );
+    }
+  }
+
+  private toRow(payload: AuditLogPayload, context: AuditLogContext) {
+    return {
+      workspaceId: context.workspaceId,
+      actorId: context.actorId ?? null,
+      actorType: context.actorType ?? 'user',
+      event: payload.event,
+      resourceType: payload.resourceType,
+      resourceId: payload.resourceId ?? null,
+      spaceId: payload.spaceId ?? null,
+      // jsonb columns: node-postgres serializes plain objects to JSON.
+      changes: payload.changes ? (payload.changes as any) : null,
+      metadata: payload.metadata ? (payload.metadata as any) : null,
+      ipAddress: context.ipAddress ?? null,
+    };
+  }
+}

apps/server/src/integrations/import/services/file-import-task.service.ts

@@ -22,10 +22,12 @@ import { v7 } from 'uuid';
 import { generateJitteredKeyBetween } from 'fractional-indexing-jittered';
 import { FileTask, InsertablePage } from '@docmost/db/types/entity.types';
 import { canonicalizeFootnotes } from '@docmost/editor-ext';
-import { markdownToProseMirror } from '@docmost/prosemirror-markdown';
+import {
+  markdownToProseMirror,
+  normalizeForeignMarkdown,
+} from '@docmost/prosemirror-markdown';
 import { getProsemirrorContent } from '../../../common/helpers/prosemirror/utils';
 import { formatImportHtml } from '../utils/import-formatter';
-import { normalizeForeignMarkdown } from '../utils/foreign-markdown';
 import {
   buildAttachmentCandidates,
   collectMarkdownAndHtmlFiles,

apps/server/src/integrations/import/services/import.service.ts

@@ -18,8 +18,10 @@ import { generateJitteredKeyBetween } from 'fractional-indexing-jittered';
 import { TiptapTransformer } from '@hocuspocus/transformer';
 import * as Y from 'yjs';
 import { canonicalizeFootnotes } from '@docmost/editor-ext';
-import { markdownToProseMirror } from '@docmost/prosemirror-markdown';
-import { normalizeForeignMarkdown } from '../utils/foreign-markdown';
+import {
+  markdownToProseMirror,
+  normalizeForeignMarkdown,
+} from '@docmost/prosemirror-markdown';
 import {
   FileTaskStatus,
   FileTaskType,

apps/server/src/integrations/import/utils/foreign-markdown.spec.ts

@@ -1,218 +0,0 @@
-import {
-  convertProseMirrorToMarkdown,
-  markdownToProseMirror,
-} from '@docmost/prosemirror-markdown';
-import { normalizeForeignMarkdown } from './foreign-markdown';
-
-/**
- * STEP 2 goldens for issue #345: the foreign-markdown normalizer that runs at the
- * import boundary BEFORE the strict canonical parser (`markdownToProseMirror`).
- *
- * Two layers:
- *  1. PURE string→string cases pinning the normalizer's own behavior (GFM
- *     reference footnotes → inline `^[…]`).
- *  2. END-TO-END acceptance: for a foreign corpus, `normalizeForeignMarkdown`
- *     then `markdownToProseMirror` then `convertProseMirrorToMarkdown` must leave
- *     NO literal `[^id]` / `:::` garbage in the document and must re-export in the
- *     canonical forms.
- */
-
-describe('normalizeForeignMarkdown — GFM reference footnotes', () => {
-  it('inlines a single-line reference footnote and drops its definition', () => {
-    const out = normalizeForeignMarkdown(
-      'A note[^1] here.\n\n[^1]: The definition.',
-    );
-    expect(out).toBe('A note^[The definition.] here.\n');
-  });
-
-  it('inlines every reference to a reused id (downstream dedups)', () => {
-    const out = normalizeForeignMarkdown(
-      'X[^a] and Y[^a].\n\n[^a]: shared.',
-    );
-    expect(out).toBe('X^[shared.] and Y^[shared.].\n');
-  });
-
-  it('joins indented continuation lines of a definition with a space', () => {
-    const out = normalizeForeignMarkdown(
-      'See[^n].\n\n[^n]: line one\n    line two',
-    );
-    expect(out).toBe('See^[line one line two].\n');
-  });
-
-  it('never rewrites a reference inside a fenced code block', () => {
-    const out = normalizeForeignMarkdown(
-      '```\ncode[^1] here\n```\n\n[^1]: def.',
-    );
-    expect(out).toContain('code[^1] here');
-    // The (now orphaned) definition line is still removed.
-    expect(out).not.toContain('[^1]: def.');
-  });
-
-  it('never rewrites a reference inside an INLINE-code span (backticks)', () => {
-    // The `[^1]` inside backticks is literal code and must survive verbatim;
-    // the one outside is rewritten. (Bug #1: only fenced blocks were protected.)
-    const out = normalizeForeignMarkdown(
-      'Use `arr[^1]` in code but note[^1] in prose.\n\n[^1]: def.',
-    );
-    expect(out).toBe('Use `arr[^1]` in code but note^[def.] in prose.\n');
-  });
-
-  it('escapes brackets in a body so an unbalanced ] cannot truncate the footnote', () => {
-    // A foreign definition body with a stray `]` would, unescaped, close the
-    // canonical `^[...]` early and leak the tail as text (bug #2). The body's
-    // brackets are backslash-escaped so the footnote stays whole.
-    const out = normalizeForeignMarkdown(
-      'Ref[^1] here.\n\n[^1]: see item ] and [more] later',
-    );
-    expect(out).toBe('Ref^[see item \\] and \\[more\\] later] here.\n');
-    // The tokenizer must see exactly one unescaped closing bracket (our own).
-    expect(out.match(/(?<!\\)\]/g)).toHaveLength(1);
-  });
-
-  it('leaves a reference with no matching definition literal (no body to inline)', () => {
-    const out = normalizeForeignMarkdown('Dangling[^x] ref.');
-    expect(out).toBe('Dangling[^x] ref.');
-  });
-
-  it('returns the input unchanged when there are no reference footnotes', () => {
-    const md = '# Title\n\nJust text with `inline code` and a [link](/x).';
-    expect(normalizeForeignMarkdown(md)).toBe(md);
-  });
-
-  it('does NOT touch callout surfaces — the canonical parser handles them', () => {
-    const callouts = ':::info\nHi\n:::\n\n> [!warning]\n> Careful';
-    expect(normalizeForeignMarkdown(callouts)).toBe(callouts);
-  });
-
-  it('strips a leading YAML front-matter block (Obsidian/Hugo/git-sync files)', () => {
-    const out = normalizeForeignMarkdown(
-      '---\ntitle: My Page\ntags: [a, b]\n---\n\n# Heading\n\nBody.',
-    );
-    expect(out).toBe('# Heading\n\nBody.');
-    // The front-matter must not leak into the body as a setext heading.
-    expect(out).not.toContain('title: My Page');
-    expect(out).not.toContain('---');
-  });
-
-  it('does not strip a horizontal rule that is not leading front-matter', () => {
-    const md = 'Intro paragraph.\n\n---\n\nAfter the rule.';
-    expect(normalizeForeignMarkdown(md)).toBe(md);
-  });
-
-  it('is linear on a document with thousands of definitions (no quadratic blowup)', () => {
-    // F2(a): the pass-2 rewrite must be O(text), not O(text × defs). Build a
-    // pathological doc (many defs + many plain text lines) and assert it
-    // completes well under a second — a quadratic implementation took ~14s.
-    const N = 4000;
-    const refs = Array.from({ length: N }, (_, i) => `line ${i} plain text`).join('\n');
-    const defs = Array.from({ length: N }, (_, i) => `[^n${i}]: def ${i}`).join('\n');
-    const doc = `start[^n0] and[^n${N - 1}] end\n\n${refs}\n\n${defs}`;
-    const t0 = Date.now();
-    const out = normalizeForeignMarkdown(doc);
-    const elapsed = Date.now() - t0;
-    expect(elapsed).toBeLessThan(2000);
-    // Sanity: the two real references were still inlined.
-    expect(out).toContain('^[def 0]');
-    expect(out).toContain(`^[def ${N - 1}]`);
-  });
-
-  it('is bounded on a long unclosed backtick run (no inline-split ReDoS)', () => {
-    // F2(b): a huge unterminated backtick run must not cause quadratic
-    // backtracking in the inline-code split. Oversized lines skip the split
-    // entirely (left untouched), so this returns promptly.
-    const line = 'x' + '`'.repeat(200000);
-    const doc = `${line}\n\n[^1]: def`;
-    const t0 = Date.now();
-    normalizeForeignMarkdown(doc);
-    expect(Date.now() - t0).toBeLessThan(2000);
-  });
-
-  it('does not crash or slow down on thousands of prefix-chain definition ids', () => {
-    // F7: the rewrite must use a FIXED generic scanner, not an alternation built
-    // from the ids. A `(a|aa|aaa|…)` alternation over prefix-chain ids blows the
-    // V8 regex compiler (FATAL RegExpCompiler Allocation failed — uncatchable,
-    // kills the process). A fixed scanner has no id-dependent compilation cost.
-    const N = 4000;
-    const ids = Array.from({ length: N }, (_, i) => 'a'.repeat(i + 1));
-    const defs = ids.map((id) => `[^${id}]: body ${id.length}`).join('\n');
-    const doc = `ref[^${ids[0]}] and[^${ids[N - 1]}] end\n\n${defs}`;
-    const t0 = Date.now();
-    const out = normalizeForeignMarkdown(doc);
-    expect(Date.now() - t0).toBeLessThan(2000);
-    // Prefix disambiguation is correct: [^a] and [^aaaa...] inline their OWN body.
-    expect(out).toContain('^[body 1]');
-    expect(out).toContain(`^[body ${N}]`);
-  });
-
-  it('strips a CRLF (Windows) front-matter block, not just LF', () => {
-    // F9: the line-anchored regex needs LF after the opening `---`, so a Windows
-    // file (`---\r\n…`) would slip past the strip and leak the front-matter into
-    // the body. normalizeForeignMarkdown normalizes CRLF -> LF first.
-    const out = normalizeForeignMarkdown(
-      '---\r\ntitle: Foo\r\ntags: [a]\r\n---\r\n\r\n# Heading\r\n\r\nBody.',
-    );
-    expect(out).toBe('# Heading\n\nBody.');
-    expect(out).not.toContain('title: Foo');
-    expect(out).not.toContain('---');
-  });
-
-  it('strips front-matter whose value contains a triple-dash (line-anchored)', () => {
-    // F8: the block must close only on a `\n---` LINE, not the first inline
-    // `---`. A value like `title: Q1 --- Q2` must not truncate the front-matter
-    // and leak the rest (author/closing ---) into the body.
-    const out = normalizeForeignMarkdown(
-      '---\ntitle: Q1 --- Q2 results\nauthor: bob\n---\n\nReal body.',
-    );
-    expect(out).toBe('Real body.');
-    expect(out).not.toContain('author: bob');
-    expect(out).not.toContain('Q2 results');
-  });
-});
-
-describe('foreign markdown import acceptance (normalizer + canonical parser)', () => {
-  const FOREIGN = [
-    '# Doc',
-    '',
-    'Body refs [^c] and [^a] and [^b] and again [^a].',
-    '',
-    ':::info',
-    'A legacy callout.',
-    ':::',
-    '',
-    '| h1 | h2 |',
-    '| --- | --- |',
-    '| 1 | 2 |',
-    '',
-    '[^a]: note A',
-    '[^b]: note B',
-    '[^c]: note C',
-    '[^z]: orphan note',
-  ].join('\n');
-
-  it('leaves no literal [^id] or ::: in the imported doc and re-exports canonically', async () => {
-    const normalized = normalizeForeignMarkdown(FOREIGN);
-    const doc = await markdownToProseMirror(normalized);
-    const reexport = convertProseMirrorToMarkdown(doc);
-
-    // No foreign garbage leaks into the document.
-    expect(reexport).not.toMatch(/\[\^/); // no reference footnote refs/defs
-    expect(reexport).not.toContain(':::'); // no legacy callout fences
-
-    // Canonical forms are present.
-    expect(reexport).toContain('^[note C]');
-    expect(reexport).toContain('> [!info]');
-    expect(reexport).toContain('| h1 | h2 |');
-
-    // Footnotes: ordered by first reference (C, A, B), reused [^a] deduped to one,
-    // orphan [^z] dropped (it had no reference after normalization).
-    const list = doc.content.find((n: any) => n.type === 'footnotesList');
-    const bodies = list.content.map(
-      (d: any) => d.content[0].content[0].text,
-    );
-    expect(bodies).toEqual(['note C', 'note A', 'note B']);
-    expect(bodies).not.toContain('orphan note');
-    expect(
-      doc.content.filter((n: any) => n.type === 'footnotesList'),
-    ).toHaveLength(1);
-  });
-});

apps/server/src/integrations/import/utils/foreign-markdown.ts

@@ -1,266 +0,0 @@
-/**
- * Foreign-markdown normalizer — an input-liberal / output-canonical adapter that
- * runs at the IMPORT boundary, BEFORE the canonical parser
- * (`markdownToProseMirror` from `@docmost/prosemirror-markdown`).
- *
- * The canonical parser is deliberately STRICT: it only understands Docmost's
- * canonical markdown surface (Obsidian-style `> [!type]` callouts, Pandoc/Obsidian
- * inline footnotes `^[body]`, lossless `![alt](src) <!--img {...}-->` images, …).
- * Import, however, ingests FOREIGN files (GitHub/GFM, Notion, old Docmost
- * exports). Those use surfaces the canonical parser does not accept, most notably
- * GitHub-flavoured *reference* footnotes:
- *
- *     Text with a note[^1] and another[^long].
- *
- *     [^1]: The first definition.
- *     [^long]: A second one.
- *
- * Left untouched, the parser does NOT recognise `[^id]` (it only parses `^[body]`),
- * so the reference leaks as literal text — and worse, the trailing `[^id]: def`
- * line is a valid CommonMark *link-reference definition*, so `[^id]` is silently
- * rendered as a bogus link. This normalizer rewrites reference footnotes into the
- * canonical inline form so the parser materialises real footnote nodes.
- *
- * This is a TEXT pre-pass, NOT a second parser fork: it does not re-implement any
- * converter logic. Callout surfaces (`:::type` and `> [!type]`) are intentionally
- * NOT touched here — the canonical parser already accepts BOTH natively (its
- * `preprocessCallouts` pass), so normalizing them would be redundant and would
- * only risk degrading the parser's nesting/code-fence-aware handling.
- */
-
-/** Matches a fenced code block delimiter (``` or ~~~), capturing the marker run. */
-const CODE_FENCE_RE = /^(\s*)(`{3,}|~{3,})/;
-
-/**
- * Matches a GFM footnote DEFINITION line: `[^id]: body`. The id is any run of
- * non-`]` characters; the body is the remainder of the line (possibly empty).
- */
-const FOOTNOTE_DEF_RE = /^\[\^([^\]]+)\]:[ \t]?(.*)$/;
-
-/** True when a line is a code-fence delimiter that toggles fenced-code state. */
-function fenceMarker(line: string): string | null {
-  const m = line.match(CODE_FENCE_RE);
-  return m ? m[2] : null;
-}
-
-/** True when a line is indented (leading space/tab) and not blank — a continuation. */
-function isIndentedContinuation(line: string): boolean {
-  return /^[ \t]+\S/.test(line);
-}
-
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-/**
- * Backslash-escape any square bracket in a footnote body before it is wrapped in
- * `^[...]`. The canonical inline-footnote tokenizer scans the body with bracket
- * balancing and closes on the first UNMATCHED `]`, so an unbalanced bracket in a
- * foreign definition (e.g. `[^1]: see item ] later`) would otherwise truncate the
- * footnote and leak the tail as literal text. Escaping every `[`/`]` makes the
- * body an inert run of characters — the tokenizer then closes only on our own
- * closing `]`. (A balanced `[link](url)` inside a body still round-trips because
- * the escaped form renders the literal brackets, which is the safe reading for a
- * footnote body; the alternative — brittle balance tracking — risks worse.)
- */
-function escapeFootnoteBody(body: string): string {
-  return body.replace(/[[\]]/g, '\\$&');
-}
-
-/**
- * Rewrite every `[^id]` reference on a line to its `^[body]` form, but ONLY in the
- * text OUTSIDE inline-code spans. A `[^id]` inside backticks is literal code
- * content and must be preserved verbatim (a footnote ref never lives inside code).
- * We split the line on inline-code spans (paired backtick runs) and rewrite only
- * the non-code segments.
- */
-// Above this length a single line is not split into inline-code spans (see
-// below). A genuine markdown line carrying a footnote reference is never tens of
-// KB; the cap only bypasses the inline-code protection for pathological lines.
-const INLINE_SPLIT_MAX_LINE = 8192;
-
-function rewriteRefsOutsideInlineCode(
-  line: string,
-  replace: (text: string) => string,
-): string {
-  // The inline-code split alternation `(`+)(?:(?!\1)[\s\S])*\1` backtracks
-  // quadratically on a long UNCLOSED backtick run (its middle can consume the
-  // rest of the line, then fail to find a closing run and retry from each
-  // position). On an untrusted import this is a request-thread ReDoS. A real
-  // footnote line is short, so for an oversized line we skip the inline-code
-  // protection entirely and leave the line UNTOUCHED (rewriting it wholesale
-  // could corrupt a `[^id]` that legitimately lives inside inline code). This is
-  // a conservative bypass: an over-8KB line simply does not get its reference
-  // footnotes inlined — acceptable for a pathological input.
-  if (line.length > INLINE_SPLIT_MAX_LINE) return line;
-
-  // Alternation: an inline-code span (one or more backticks, then anything up to
-  // the SAME run of backticks) OR a run of non-backtick text. Unterminated
-  // backticks fall through as ordinary text (matched by the second branch on the
-  // leftover), so a stray backtick never swallows the rest of the line.
-  const parts = line.match(/(`+)(?:(?!\1)[\s\S])*\1|[^`]+|`+/g);
-  if (!parts) return line;
-  return parts
-    .map((seg) => (seg.startsWith('`') ? seg : replace(seg)))
-    .join('');
-}
-
-/**
- * Convert GFM reference footnotes (`[^id]` + `[^id]: def`) into canonical inline
- * footnotes (`^[def]`).
- *
- * - Definitions are collected first (a leading `[^id]: text` line plus any
- *   immediately-following indented continuation lines, joined with a space) and
- *   removed from the output.
- * - Each in-text reference `[^id]` for which a definition was found is replaced by
- *   `^[def]`. References with no matching definition are left literal (there is no
- *   body to inline; the parser fails them open the same way).
- * - Code is respected on both passes: `[^id]` inside a fenced ``` / ~~~ block is
- *   never rewritten and a `[^id]:` line inside a fence is never a definition; and
- *   on the rewrite pass a `[^id]` inside an INLINE-code span (backticks) is left
- *   literal too.
- * - The inlined body is bracket-escaped so an unbalanced `[`/`]` in a foreign
- *   definition cannot truncate the resulting `^[...]` footnote.
- *
- * Deduplication / reference-ordering / orphan-dropping of the resulting footnotes
- * is handled downstream by the canonical parser (`assembleFootnotes`); this pass
- * only changes the surface syntax.
- */
-function convertReferenceFootnotes(markdown: string): string {
-  const lines = markdown.split('\n');
-
-  // Pass 1: collect definitions and mark their lines for removal.
-  const defs = new Map<string, string>();
-  const dropped = new Array<boolean>(lines.length).fill(false);
-  let inFence = false;
-  let fence = '';
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const marker = fenceMarker(line);
-    if (inFence) {
-      if (marker && marker[0] === fence[0] && marker.length >= fence.length) {
-        inFence = false;
-        fence = '';
-      }
-      continue;
-    }
-    if (marker) {
-      inFence = true;
-      fence = marker;
-      continue;
-    }
-
-    const def = line.match(FOOTNOTE_DEF_RE);
-    if (!def) continue;
-
-    const id = def[1];
-    const body: string[] = [def[2].trim()];
-    dropped[i] = true;
-
-    // Consume immediately-following indented continuation lines (GFM lazy
-    // continuation is not supported by design — keep it simple and predictable).
-    let j = i + 1;
-    while (j < lines.length && isIndentedContinuation(lines[j])) {
-      body.push(lines[j].trim());
-      dropped[j] = true;
-      j++;
-    }
-    i = j - 1;
-
-    // Last definition wins for a duplicated id (matches CommonMark link-ref
-    // semantics closely enough for a foreign-input adapter).
-    defs.set(id, body.filter((s) => s.length > 0).join(' '));
-  }
-
-  if (defs.size === 0) {
-    return markdown;
-  }
-
-  // ONE fixed, generic scanner regex — NOT one built from the definition ids.
-  // It matches ANY `[^id]` shape, and the replacer decides per match via a map
-  // lookup whether that id is a real definition (replace) or not (leave as-is).
-  // This is genuinely O(total text) with no per-document regex compilation.
-  //
-  // Do NOT rebuild this as an alternation over `[...defs.keys()]`: a giant
-  // `(id1|id2|...)` alternation over thousands of ids can blow the V8 regex
-  // compiler's stack — a fatal, UNCATCHABLE "RegExpCompiler Allocation failed"
-  // on prefix-chain ids (`a`, `aa`, `aaa`, ...) that kills the whole process
-  // (worse than the earlier per-def thread-hang). A fixed scanner has no
-  // id-dependent compilation cost and cannot blow up.
-  const refRe = /\[\^([^\]]+)\]/g;
-  const rewriteSegment = (segment: string): string =>
-    segment.replace(refRe, (whole, id: string) => {
-      const body = defs.get(id);
-      // Only real definitions are inlined; an unknown id is left literal (same as
-      // the old per-def loop, which simply never matched it).
-      return body === undefined ? whole : `^[${escapeFootnoteBody(body)}]`;
-    });
-
-  // Pass 2: rewrite in-text references, skipping fenced code and dropped lines.
-  const out: string[] = [];
-  inFence = false;
-  fence = '';
-  for (let i = 0; i < lines.length; i++) {
-    if (dropped[i]) continue;
-    let line = lines[i];
-
-    const marker = fenceMarker(line);
-    if (inFence) {
-      out.push(line);
-      if (marker && marker[0] === fence[0] && marker.length >= fence.length) {
-        inFence = false;
-        fence = '';
-      }
-      continue;
-    }
-    if (marker) {
-      inFence = true;
-      fence = marker;
-      out.push(line);
-      continue;
-    }
-
-    line = rewriteRefsOutsideInlineCode(line, rewriteSegment);
-    out.push(line);
-  }
-
-  return out.join('\n');
-}
-
-/**
- * Strip a single leading YAML front-matter block (`---\n…\n---`). Foreign files
- * from Obsidian / Hugo / Jekyll / Notion — and Docmost's OWN git-sync page files
- * — open with front-matter that the canonical parser does not consume, so
- * without this it leaks into the body (and `title: Foo` above the closing `---`
- * renders as a setext `<h2>` that `extractTitleAndRemoveHeading` can hijack as
- * the page title). It is a no-op for front-matter-free input.
- *
- * LINE-ANCHORED (the same shape the canonical parser uses in
- * prosemirror-markdown/page-file.ts): the block opens only on `---\n` at the
- * very start and closes only on a `\n---` line. The retired editor-ext
- * `markdownToHtml` front-matter strip (removed in #347) closed on the FIRST
- * `---` ANYWHERE (an unanchored close), so a value
- * containing a triple-dash (e.g. `title: Q1 --- Q2`) truncated the front-matter
- * and leaked the rest into the body. An optional leading BOM is tolerated.
- */
-const YAML_FRONT_MATTER_RE = /^\uFEFF?---\n[\s\S]*?\n---\n?/;
-
-/**
- * Normalize a foreign markdown string into Docmost's canonical markdown surface
- * so the strict canonical parser accepts it losslessly: normalize line endings,
- * strip a leading YAML front-matter block, then rewrite GFM reference footnotes
- * into inline footnotes. Add further fixture-driven foreign-surface cases here as
- * they are found.
- */
-export function normalizeForeignMarkdown(markdown: string): string {
-  if (!markdown) return markdown;
-  // Normalize CRLF -> LF FIRST. The line-anchored front-matter regex requires a
-  // bare `\n` after the opening `---`, and convertReferenceFootnotes splits on
-  // `\n`; a Windows/CRLF foreign file (`---\r\n…`) would otherwise slip past the
-  // front-matter strip and leak into the body. The canonical parser
-  // (page-file.ts parsePageFile) normalizes the same way before its FRONTMATTER_RE.
-  const src = markdown.replace(/\r\n/g, '\n');
-  const withoutFrontMatter = src.replace(YAML_FRONT_MATTER_RE, '').trimStart();
-  return convertReferenceFootnotes(withoutFrontMatter);
-}

apps/server/src/integrations/queue/processors/general-queue.processor.comment-mark.spec.ts

@@ -139,13 +139,19 @@ describe('GeneralQueueProcessor — COMMENT_MARK_UPDATE (#399)', () => {
     );
   });
 
-  it('skips (no throw) when the comment row has vanished', async () => {
+  it('reconcile (#496): comment row vanished → strips the orphan anchor mark', async () => {
     const { proc, collaborationGateway, commentRepo } = makeProc();
     commentRepo.findById.mockResolvedValue(undefined);
 
     await expect(
       proc.process(job({ ...base, action: 'resolve', ts: 1000 })),
     ).resolves.toBeUndefined();
-    expect(collaborationGateway.handleYjsEvent).not.toHaveBeenCalled();
+    // A resolve/unresolve mark job whose comment row is gone leaves a silent
+    // orphan; the worker self-heals by stripping the anchor instead of returning.
+    expect(collaborationGateway.handleYjsEvent).toHaveBeenCalledWith(
+      'deleteCommentMark',
+      'page.page-1',
+      { commentId: 'c-1', user: { id: 'user-1' } },
+    );
   });
 });

apps/server/src/integrations/queue/processors/general-queue.processor.ts

@@ -95,7 +95,8 @@ export class GeneralQueueProcessor
    * #399: apply a comment's inline-mark mirror in the collab Y.Doc, off the HTTP
    * critical path. Runs the SAME gateway path the synchronous comment.service
    * code used (byte-identical mark op):
-   *   - resolve / unresolve → resolveCommentMark (flip the `resolved` attribute);
+   *   - resolve / unresolve → resolveCommentMark (flip the `resolved` attribute),
+   *     OR strip an orphan anchor when the comment row has vanished (#496);
    *   - delete → deleteCommentMark (strip the ephemeral-suggestion anchor #329).
    * The op is idempotent, so a BullMQ retry is safe. Throwing propagates to
    * WorkerHost → the job is retried and, on exhaustion, surfaces in failed-job
@@ -133,7 +134,18 @@ export class GeneralQueueProcessor
     // of this resolve), skip it rather than flip the mark to a stale state.
     const comment = await this.commentRepo.findById(commentId);
     if (!comment) {
-      // The comment vanished (e.g. hard-deleted) → nothing left to mirror.
+      // #496 reconcile: the comment row is GONE (e.g. an ephemeral apply/dismiss
+      // hard-deleted it while this resolve/unresolve mark job sat in the queue),
+      // but its inline anchor may still live in the doc — a silent orphan mark
+      // pointing at a comment that no longer exists. Self-heal by stripping it
+      // instead of just returning: this closes the divergence the fire-and-forget
+      // resolve/unresolve enqueue (comment.service resolveComment) could leave.
+      // Idempotent — deleteCommentMark on an already-absent mark is a no-op.
+      await this.getCollaborationGateway().handleYjsEvent(
+        'deleteCommentMark',
+        documentName,
+        { commentId, user },
+      );
       return;
     }
     const wantResolved = action === 'resolve';