fix(client): close mobile sidebar drawer after creating a page (#325)

On mobile the "create page" action is triggered from inside the off-canvas
sidebar drawer (the space sidebar "+" and temporary-note buttons, and the
tree-row "add subpage"). handleCreate navigated to the new page's editor route
but never closed that drawer, so it stayed open on top of the freshly created
page — the editor was hidden behind the page tree ("as if the page didn't
open", #325 item 5).

Close the mobile sidebar (`setMobileSidebar(false)`) right after navigating,
mirroring the existing drawer-close on a tree-row tap (space-tree-row). Placing
it in handleCreate covers all three create entry points in one spot. It is a
no-op on desktop, where the mobile-sidebar atom is already false and only
governs the sub-992px collapsed state — desktop behavior is unchanged.

Verified: `tsc --noEmit` clean; client vitest 887 passed | 1 expected-fail.

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

.env.example

@@ -173,9 +173,21 @@ MCP_DOCMOST_PASSWORD=
 # Keep-alive recycle window (ms) for streaming chat/agent AI + external-MCP calls.
 # A pooled connection idle longer than this is closed instead of reused, so a
 # NAT / egress firewall / reverse proxy that silently drops idle connections
-# cannot poison a reused socket into a PRE-RESPONSE `read ECONNRESET`. Lower it if
-# your egress drops idle connections faster than ~10s. Default 10000 (10 s).
-# AI_STREAM_KEEPALIVE_MS=10000
+# cannot poison a reused socket into a PRE-RESPONSE `read ECONNRESET`. Kept under
+# common ~5s upstream/middlebox idle cutoffs so undici recycles the socket before
+# the network kills it (fewer resets), while still reusing within a burst of
+# back-to-back calls. Lower it further if your egress drops idle connections even
+# faster. Default 4000 (4 s).
+# AI_STREAM_KEEPALIVE_MS=4000
+
+# Number of PRE-RESPONSE connection retries for streaming chat/agent AI calls: a
+# reset/timeout BEFORE any response byte (e.g. `read ECONNRESET` on a stale pooled
+# socket) is retried on a fresh connection with jittered exponential backoff.
+# Total attempts = value + 1, so the default 4 gives 5 attempts — headroom to
+# absorb a short BURST of upstream resets without exhausting the budget. Safe to
+# retry: a started stream is never replayed, only a connect that never responded.
+# 0 disables the retry. Default 4.
+# AI_STREAM_PRE_RESPONSE_RETRIES=4
 
 # Silence timeout (ms) for EXTERNAL-MCP transport ONLY (not the chat provider).
 # Tighter than AI_STREAM_TIMEOUT_MS so a byte-silent/hung MCP server is broken in

.gitignore

@@ -4,7 +4,11 @@
 data
 # compiled output
 /dist
-/node_modules
+node_modules/
+
+# git-sync compiled output (built in CI/Docker via `pnpm build`, never committed,
+# so src/ and prod can never silently diverge).
+packages/git-sync/build/
 
 # Logs
 logs
@@ -43,6 +47,8 @@ lerna-debug.log*
 .nx/cache
 .claude/worktrees/
 .claude/tmp/
+# Local Chrome performance traces recorded by the AI-chat perf harness
+.claude/perf-traces/
 
 # TypeScript incremental build artifacts
 *.tsbuildinfo

AGENTS.md

@@ -293,6 +293,7 @@ Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirro
 - The version string shown in the UI comes from `APP_VERSION` (CI/Docker) or `git describe --tags --always` (local), resolved in `vite.config.ts` — not from `package.json`.
 - Server TS config is permissive (`noImplicitAny: false`, `strictNullChecks: false`, `no-explicit-any` lint disabled). Follow the existing relaxed style rather than tightening types broadly.
 - Dependency versions are heavily pinned via `pnpm.overrides` and `pnpm.patchedDependencies` (`scimmy`, `yjs`) in the root `package.json`. Don't bump pinned/patched deps casually; the patches and overrides exist for compatibility/security reasons.
+- **Adding/renaming/removing an MCP tool requires updating `SERVER_INSTRUCTIONS`** in `packages/mcp/src/index.ts` — the intent-routing guide MCP clients receive on initialize. This applies both to inline `server.registerTool(...)` calls in `index.ts` and to specs in `packages/mcp/src/tool-specs.ts`. Enforced by `packages/mcp/test/unit/server-instructions.test.mjs`, which fails when a registered tool is not mentioned in the guide (deliberate opt-outs go into its `EXCEPTIONS` list). Remember `packages/mcp/build/` is committed — rebuild after editing.
 
 ## CI / release
 

agent-roles-catalog/bundles/editorial/en.yaml

@@ -34,11 +34,13 @@ roles:
       Read the whole text first. Think at the level of sections and paragraphs, not sentences.
 
       HOW TO LEAVE COMMENTS
-      You don't edit the text yourself. For each note, select the relevant span via the MCP tool and leave a comment. Open the comment with the label `[Structure]`. Then: state the problem briefly, propose a concrete fix (move, merge, cut, add, reorder, strengthen the lead/headline), and explain why if it isn't obvious. Tag severity:
+      You don't edit the text yourself. For each note, select the relevant span via the MCP tool and leave a comment. State the problem briefly, propose a concrete fix (move, merge, cut, add, reorder, strengthen the lead/headline), and explain why if it isn't obvious. Tag severity:
       - [Critical] — broken logic, the text doesn't deliver what the headline promises, a key link in the argument is missing.
       - [Major] — weak structure, a noticeable gap or redundancy, a sagging lead/headline.
       - [Minor] — an optional improvement to framing or flow.
 
+      Structural fixes (move, merge, cut) can't be expressed as a fragment replacement — a comment is enough for those. But when your proposal boils down to replacing a specific wording in place (a headline, a lead phrase), attach a suggested replacement to the comment (the `suggestedText` parameter): the exact new text for the selected fragment, plain text with no markup — the author applies it with one click. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context.
+
       TONE
       Respectful and to the point. The author may know the subject better than you. Flag only what matters structurally. When unsure, phrase it as a question.
 
@@ -85,7 +87,7 @@ roles:
       - Don't rewrite the text yourself or impose your own voice. Your job is to make the author's voice livelier, not to replace it.
 
       HOW TO LEAVE COMMENTS
-      You don't edit the text directly. For each note, select the span via the MCP tool and leave a comment. Open the comment with the label `[Style]`. Give a concrete rephrasing, not "revise". Tag severity:
+      You don't edit the text directly. For each note, select the span via the MCP tool and leave a comment. Give a concrete rephrasing, not "revise", and attach it to the comment as a suggested replacement (the `suggestedText` parameter): the exact new text for the selected fragment, plain text with no markup — the author applies it with one click. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context. Tag severity:
       - [Critical] — the sentence is unclear or distorts the meaning.
       - [Major] — an obvious LLM cliché, heavy bureaucratese, filler that breaks the reading.
       - [Minor] — a stylistic improvement to taste.
@@ -126,7 +128,7 @@ roles:
       - Don't fabricate confirmations. If you can't verify, honestly mark [Unverified] or [Unverifiable].
 
       HOW TO LEAVE COMMENTS
-      You don't edit the text directly. For each problem claim (an error, a doubt, an unverifiable statement), select the span via the MCP tool and leave a comment; leave no comment on correct facts. Open the comment with the label `[Facts]`, then the verdict, the correction (if any), and the source. Tag severity:
+      You don't edit the text directly. For each problem claim (an error, a doubt, an unverifiable statement), select the span via the MCP tool and leave a comment; leave no comment on correct facts. Give the verdict, the correction (if any), and the source. For an [Incorrect] verdict, ALWAYS attach the ready correction as a suggested replacement (the `suggestedText` parameter): since you found the correct value in the sources, propose the ready fix right away instead of merely describing the error. The replacement is the exact new text for the selected fragment, plain text with no markup; the author applies it with one click instead of retyping the fragment. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context. Do not attach a replacement to [Unverified], [Unverifiable], or [Opinion] verdicts. Tag severity:
       - [Critical] — a factual error, especially in numbers, names, or quotes, or a claim that risks misinformation.
       - [Major] — a doubtful or unconfirmed claim that needs a source.
       - [Minor] — a small correction, or false precision worth rounding or confirming.
@@ -166,14 +168,17 @@ roles:
       - Don't verify facts — that's the Fact-checker.
       - Don't make substantive changes. Edits are minimal and mechanical.
 
+      HOW TO WORK
+      Go through the whole text from start to finish in a single pass. Flag EVERY violation, including all repeat occurrences of the same error and minor items tagged [Minor] — don't stop at the first few or the most conspicuous. Don't summarize instead of marking up: until you've reached the end of the document, the job isn't done. One run covers the whole text, not just "the most important".
+
       HOW TO LEAVE COMMENTS
-      You don't edit the text directly. For each fix, select the span via the MCP tool and leave a comment with the concrete correction. Open the comment with the label `[Copyedit]`. Tag severity:
+      You don't edit the text directly. For each fix, select the span via the MCP tool and leave a comment with the concrete correction. Attach a suggested replacement to every fix (the `suggestedText` parameter): the exact corrected text for the selected fragment, plain text with no markup — the author applies it with one click. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context. Do NOT leave summary notes like "throughout, replace X with Y" or "make the units/quotes/spelling consistent": such a comment can't be applied with a button. If the same error occurs in several places, walk EVERY occurrence and leave a separate targeted comment with its own replacement on each — ten targeted fixes instead of one blanket note. The only exception is a note that genuinely cannot be expressed as a replacement of a concrete fragment; leave those rare cases as an ordinary comment without a replacement. Tag severity:
       - [Critical] — a grammar/spelling error or typo visible to the reader.
       - [Major] — a consistency or typography break (wrong quotes, hyphen for a dash, missing serial comma where the rest of the text has it).
       - [Minor] — optional polish.
 
       TONE
-      To the point, no explaining the obvious. Group repeated fixes (e.g. "throughout: straight quotes → curly") so you don't spawn dozens of identical comments.
+      To the point, no explaining the obvious. Don't fold repeated fixes into a single "change it everywhere" note — spread them across the specific spots: ten targeted comments each carrying a ready replacement beat one blanket comment that can't be applied with a button. Don't worry about "spawning" comments — for a copyeditor that's normal.
 
       WHEN UNSURE
       If a fix touches meaning, don't make it — that's out of scope. If correctness depends on an author decision (a choice between two acceptable spellings), propose a variant.
@@ -272,7 +277,7 @@ roles:
       First read the whole text and assess it as a story as a whole. Then go in order: (1) the framework and the template; (2) the lede; (3) the hooks and loops; (4) Chekhov's guns; (5) illustrations; (6) liveliness of tone. If at any step liveliness threatens technical accuracy — the priority is accuracy.
 
       ═══ HOW TO LEAVE NOTES ═══
-      You do not edit the text directly and do not rewrite it for the author. Using the MCP tool, select the relevant fragment and leave a free-form comment on it. Explain not only “what” but also “why” — what effect it will have on the reader. Propose concrete moves and options, but leave the choice to the author: it is their experience and their voice. Comment on what will strengthen the story, not on every little thing.
+      You do not edit the text directly and do not rewrite it for the author. Using the MCP tool, select the relevant fragment and leave a free-form comment on it. Explain not only “what” but also “why” — what effect it will have on the reader. Propose concrete moves and options, but leave the choice to the author: it is their experience and their voice. When one of your options is a single ready-made text (e.g. a new lead phrase), you may attach it as a suggested replacement (the `suggestedText` parameter: the exact new text for the selected fragment, no markup; the fragment must occur exactly once in the text, otherwise extend the selection) — the button imposes nothing, the author is free not to apply it. Comment on what will strengthen the story, not on every little thing.
 
       ═══ TONE ═══
       Respectfully, with enthusiasm, in a human way. You are not a censor but a co-author and guide who helps the author tell their story better. The author knows the subject better than you — your task is to help them reveal it.

agent-roles-catalog/bundles/editorial/ru.yaml

@@ -34,11 +34,13 @@ roles:
       Сначала прочитай весь текст целиком. Думай на уровне разделов и абзацев, а не предложений.
 
       КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст сам. Для каждого замечания через MCP-инструмент выдели соответствующий фрагмент и оставь к нему комментарий. Начинай комментарий с метки `[Структура]`. Дальше: коротко назови проблему, предложи конкретное решение (перенести, объединить, вырезать, добавить, переставить, усилить лид/заголовок) и при необходимости поясни, почему. Помечай важность:
+      Ты не редактируешь текст сам. Для каждого замечания через MCP-инструмент выдели соответствующий фрагмент и оставь к нему комментарий. Коротко назови проблему, предложи конкретное решение (перенести, объединить, вырезать, добавить, переставить, усилить лид/заголовок) и при необходимости поясни, почему. Помечай важность:
       - [Критично] — сломана логика, текст не отвечает на заявленное в заголовке, отсутствует ключевое звено аргумента.
       - [Существенно] — слабая структура, заметный пробел или избыточность, провисающий лид/заголовок.
       - [Незначительно] — улучшение подачи или стройности, не обязательное.
 
+      Структурные правки (перенести, объединить, вырезать) через замену фрагмента не выражаются — для них достаточно комментария. Но если предложение сводится к замене конкретной формулировки на месте (заголовок, лид-фраза), приложи к комментарию предложение-замену (параметр `suggestedText`): точный новый текст взамен выделенного фрагмента, обычным текстом без разметки — автор применит его одной кнопкой. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом.
+
       ТОН
       Уважительно и по делу. Автор может разбираться в теме лучше тебя. Помечай только то, что важно для структуры. Если сомневаешься, формулируй вопросом.
 
@@ -85,7 +87,7 @@ roles:
       - Не переписываешь текст сам и не навязываешь свой голос. Твоя задача — сделать авторскую интонацию живее, а не заменить собой.
 
       КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст напрямую. Для каждого замечания через MCP-инструмент выдели фрагмент и оставь к нему комментарий. Начинай комментарий с метки `[Стиль]`. Давай конкретный вариант переформулировки, а не «переделать». Помечай важность:
+      Ты не редактируешь текст напрямую. Для каждого замечания через MCP-инструмент выдели фрагмент и оставь к нему комментарий. Давай конкретный вариант переформулировки, а не «переделать», и прикладывай его к комментарию как предложение-замену (параметр `suggestedText`): точный новый текст взамен выделенного фрагмента, обычным текстом без разметки — автор применит его одной кнопкой. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом. Помечай важность:
       - [Критично] — предложение непонятно или искажает смысл.
       - [Существенно] — явный штамп LLM, заметный канцелярит, вода, ломающая чтение.
       - [Незначительно] — стилистическое улучшение на вкус.
@@ -126,7 +128,7 @@ roles:
       - Не выдумываешь подтверждения. Если не можешь проверить — честно ставь [Не проверено] или [Непроверяемо].
 
       КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст напрямую. Для каждого проблемного утверждения (ошибка, сомнение, непроверяемость) через MCP-инструмент выдели фрагмент и оставь комментарий; на верные факты комментарии не оставляй. Начинай комментарий с метки `[Факты]`, затем вердикт, исправление (если нужно) и источник. Помечай важность:
+      Ты не редактируешь текст напрямую. Для каждого проблемного утверждения (ошибка, сомнение, непроверяемость) через MCP-инструмент выдели фрагмент и оставь комментарий; на верные факты комментарии не оставляй. В комментарии дай вердикт, исправление (если нужно) и источник. К вердикту [Неверно] всегда прикладывай готовое исправление как предложение-замену (параметр `suggestedText`): раз ты нашёл по источникам верное значение — сразу предлагай готовую правку, а не только описывай ошибку. Замена — это точный новый текст взамен выделенного фрагмента, обычным текстом без разметки; автор применит её одной кнопкой, не переписывая фрагмент вручную. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом. К вердиктам [Не проверено], [Непроверяемо] и [Это мнение] замену не прикладывай. Помечай важность:
       - [Критично] — фактическая ошибка, особенно в числах, именах, цитатах, или утверждение с риском дезинформации.
       - [Существенно] — сомнительное или непроверенное утверждение, требующее источника.
       - [Незначительно] — мелкое уточнение, псевдоточность, которую стоит округлить или подтвердить.
@@ -167,14 +169,17 @@ roles:
       - Не проверяешь достоверность фактов — это фактчекер.
       - Не вносишь содержательных изменений. Правки — минимальные и механические.
 
+      КАК РАБОТАТЬ
+      Пройди весь текст от начала до конца за один проход. Помечай КАЖДОЕ нарушение, включая все повторные вхождения одной и той же ошибки и мелочи с меткой [Незначительно], — не ограничивайся первыми несколькими или самыми заметными. Не подводи итог вместо разбора: пока не дошёл до конца документа, работа не закончена. Один прогон покрывает весь текст, а не «самое важное».
+
       КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст напрямую. Для каждой правки через MCP-инструмент выдели фрагмент и оставь комментарий с конкретным исправлением. Начинай комментарий с метки `[Корректура]`. Помечай важность:
+      Ты не редактируешь текст напрямую. Для каждой правки через MCP-инструмент выдели фрагмент и оставь комментарий с конкретным исправлением. К каждой правке прикладывай предложение-замену (параметр `suggestedText`): точный исправленный текст взамен выделенного фрагмента, обычным текстом без разметки — автор применит его одной кнопкой. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом. НЕ оставляй сводных замечаний вида «во всём тексте заменить X на Y» или «привести единицы/кавычки/написание к единообразию»: такой комментарий нельзя применить кнопкой. Если одна и та же ошибка встречается в нескольких местах, обойди КАЖДОЕ вхождение и оставь на нём отдельный целевой комментарий со своей заменой — десять точечных правок вместо одной общей. Единственное исключение — замечание, которое в принципе невозможно выразить заменой конкретного фрагмента; такие редкие случаи оставляй обычным комментарием без замены. Помечай важность:
       - [Критично] — грамматическая/орфографическая ошибка или опечатка, видимая читателю.
       - [Существенно] — нарушение единообразия или типографики (неверные кавычки, дефис вместо тире, отсутствие неразрывного пробела в критичном месте).
       - [Незначительно] — необязательная шлифовка.
 
       ТОН
-      По делу, без объяснений очевидного. Группируй однотипные правки (например, «во всём тексте: прямые кавычки → ёлочки»), чтобы не плодить десятки одинаковых комментариев.
+      По делу, без объяснений очевидного. Не сворачивай однотипные правки в одно сводное замечание «поменять везде» — разнеси их по конкретным местам: десять целевых комментариев с готовой заменой в каждом лучше одного общего, который нельзя применить кнопкой. Не бойся «плодить» комментарии: для корректора это норма.
 
       ПРИ НЕУВЕРЕННОСТИ
       Если правка затрагивает смысл — не трогай, это не твоя зона. Если правильность зависит от решения автора (выбор между двумя допустимыми написаниями), предложи вариант.
@@ -273,7 +278,7 @@ roles:
       Сначала прочитай весь текст и оцени его как историю целиком. Затем иди по порядку: (1) каркас и шаблон; (2) лид; (3) крючки и петли; (4) висящие ружья; (5) иллюстрации; (6) живость тона. Если на каком-то шаге живость угрожает технической точности — приоритет за точностью.
 
       ═══ КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ ═══
-      Ты не редактируешь текст напрямую и не переписываешь его за автора. Через MCP-инструмент выделяй нужный фрагмент и оставляй к нему комментарий в свободной форме. Объясняй не только «что», но и «зачем» — какой эффект на читателя это даст. Предлагай конкретные ходы и варианты, но оставляй выбор автору: это его опыт и его голос. Комментируй то, что усилит историю, а не каждую мелочь.
+      Ты не редактируешь текст напрямую и не переписываешь его за автора. Через MCP-инструмент выделяй нужный фрагмент и оставляй к нему комментарий в свободной форме. Объясняй не только «что», но и «зачем» — какой эффект на читателя это даст. Предлагай конкретные ходы и варианты, но оставляй выбор автору: это его опыт и его голос. Если среди вариантов есть один готовый текст (например, новая формулировка лида), можешь приложить его к комментарию как предложение-замену (параметр `suggestedText`: точный новый текст взамен выделенного фрагмента, без разметки; фрагмент должен встречаться в тексте ровно один раз, иначе расширь выделение) — кнопка ничего не навязывает, автор волен не применять. Комментируй то, что усилит историю, а не каждую мелочь.
 
       ═══ ТОН ═══
       Уважительно, увлечённо, по-человечески. Ты не цензор, а соавтор-проводник, который помогает автору рассказать его историю лучше. Автор знает тему лучше тебя — твоя задача помочь ему её раскрыть.

agent-roles-catalog/index.yaml

@@ -12,15 +12,15 @@ bundles:
       - en
     roles:
       - slug: structural-editor
-        version: 2
+        version: 4
       - slug: line-editor
-        version: 2
+        version: 4
       - slug: fact-checker
-        version: 3
+        version: 5
       - slug: proofreader
-        version: 3
+        version: 7
       - slug: narrator
-        version: 1
+        version: 2
   - id: research
     name:
       ru: Исследование

agent-roles-catalog/scripts/content-hashes.json

@@ -1,26 +1,26 @@
 {
   "fact-checker": {
-    "version": 3,
-    "hash": "a94931fbd20272570a588c72159ac9e48a89c99bd8f718449cda5e7ca4280fdf"
+    "version": 5,
+    "hash": "d7769872968109a1ccfb58d71bc3f3564a750b91766156f59031762848de4f24"
   },
   "line-editor": {
-    "version": 2,
-    "hash": "cca324110dc6f96d2a8a239a2fb95b0ba09fad5806c9b6090a3c210ea7883ceb"
+    "version": 4,
+    "hash": "890d10f3f0bd7f2b2cfcc94463634221c557a3140e3794721748dc8d99979780"
   },
   "narrator": {
-    "version": 1,
-    "hash": "36b38785fea6ae1c70bf6fb6b29ae5278bb86e389e61f7b9736675a589fa434c"
+    "version": 2,
+    "hash": "66fe653003b4f63ef3c3a5c5c48552fe47daeefffc16907c37c35f0e8da98851"
   },
   "proofreader": {
-    "version": 3,
-    "hash": "a36047c5cab837b2a727f63d4ddafc269b1fc44b90b365e770ecdb8f77e13952"
+    "version": 7,
+    "hash": "fdf8e0a443fa3c4102095e024146401363629a3f9015fb938c7bac2642825e56"
   },
   "researcher": {
     "version": 1,
     "hash": "853658fda43ddbe0a4d08f2c6e50b5116d29a2e9ccd7f46e173e65920d8f6ace"
   },
   "structural-editor": {
-    "version": 2,
-    "hash": "83093baa7262aef8193871a1afcf2b43b11a56fe2d00cade41355cf66d972b74"
+    "version": 4,
+    "hash": "89100e0a00b88daa0d2118fd98ec1c27d06b972bfc6ec58b705553a4daed85df"
   }
 }

apps/client/perf/ai-chat-perf-main.tsx

@@ -0,0 +1,50 @@
+/**
+ * DEV-ONLY entry for the AI chat perf harness (served by the vite dev server at
+ * /perf/ai-chat-perf.html; never part of the production build, which uses the
+ * single default index.html entry).
+ *
+ * Mounts the minimal provider stack the real ChatThread needs (Mantine, router
+ * for tool-card Links, react-query, i18n) and patches `window.fetch` BEFORE
+ * React mounts so ChatThread's DefaultChatTransport requests to
+ * /api/ai-chat/stream are answered by the synthetic SSE generator.
+ */
+
+import "@mantine/core/styles.css";
+
+import ReactDOM from "react-dom/client";
+import { MantineProvider } from "@mantine/core";
+import { MemoryRouter } from "react-router-dom";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { mantineCssResolver, theme } from "../src/theme.ts";
+// i18n side-effect init (http-backend). Translations load from /locales in dev;
+// missing keys fall back to the key text, which is fine for the harness.
+import "../src/i18n.ts";
+import { installAiChatStreamFetchPatch } from "./synthetic-turn.ts";
+import PerfHarness from "./harness.tsx";
+
+// MUST run before React mounts: ChatThread creates its transport with the
+// global fetch, so the patch has to be in place before the first send.
+installAiChatStreamFetchPatch();
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      refetchOnMount: false,
+      refetchOnWindowFocus: false,
+      retry: false,
+      staleTime: 5 * 60 * 1000,
+    },
+  },
+});
+
+const container = document.getElementById("root") as HTMLElement;
+
+ReactDOM.createRoot(container).render(
+  <MemoryRouter>
+    <MantineProvider theme={theme} cssVariablesResolver={mantineCssResolver}>
+      <QueryClientProvider client={queryClient}>
+        <PerfHarness />
+      </QueryClientProvider>
+    </MantineProvider>
+  </MemoryRouter>,
+);

apps/client/perf/ai-chat-perf.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AI chat perf harness</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./ai-chat-perf-main.tsx"></script>
+  </body>
+</html>

apps/client/perf/harness.tsx

@@ -0,0 +1,390 @@
+/**
+ * DEV-ONLY perf harness UI for the AI chat feature.
+ *
+ * Left panel: controls + live stats. Right side: a bordered box (~real chat
+ * window size) hosting the REAL ChatThread component.
+ *
+ * Scenario A "Open existing chat": mount ChatThread seeded with a large
+ * persisted transcript and measure click -> post-mount-paint time.
+ * Scenario B "Live agent stream": mount an empty chat and auto-send a message;
+ * the fetch patch (see synthetic-turn.ts) answers with a synthetic SSE stream
+ * through the real useChat pipeline.
+ */
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { CSSProperties, MutableRefObject } from "react";
+import ChatThread from "../src/features/ai-chat/components/chat-thread.tsx";
+import type { IAiChatMessageRow } from "../src/features/ai-chat/types/ai-chat.types.ts";
+import {
+  PRESETS,
+  buildPersistedRows,
+  buildTurnScript,
+  setLiveStreamSettings,
+  type PresetKey,
+} from "./synthetic-turn.ts";
+
+const AUTO_SEND_TEXT = "Run the synthetic perf turn";
+const AUTO_SEND_TIMEOUT_MS = 1000;
+/** Stats display refresh period — 2x/s so the display itself stays cheap. */
+const STATS_FLUSH_MS = 500;
+
+// ---------------------------------------------------------------------------
+// Shared mutable stats (written from callbacks, flushed to state at 2 Hz)
+// ---------------------------------------------------------------------------
+
+interface PerfStats {
+  longtaskCount: number;
+  longtaskTotalMs: number;
+  longtaskMaxMs: number;
+  fps: number;
+  sseChunks: number;
+  sseChars: number;
+  mountAMs: number | null;
+  streamState: "idle" | "streaming" | "done" | "aborted";
+}
+
+function emptyStats(): PerfStats {
+  return {
+    longtaskCount: 0,
+    longtaskTotalMs: 0,
+    longtaskMaxMs: 0,
+    fps: 0,
+    sseChunks: 0,
+    sseChars: 0,
+    mountAMs: null,
+    streamState: "idle",
+  };
+}
+
+/**
+ * Self-contained stats panel: owns the longtask observer, the FPS meter and the
+ * 2 Hz flush interval. Isolated in its OWN component so its periodic setState
+ * re-renders only this panel — NOT the ChatThread under measurement.
+ */
+function StatsPanel({ stats }: { stats: MutableRefObject<PerfStats> }) {
+  const [snapshot, setSnapshot] = useState<PerfStats>(() => ({ ...stats.current }));
+
+  // Long tasks (main-thread blocks > 50ms).
+  useEffect(() => {
+    let observer: PerformanceObserver | null = null;
+    try {
+      observer = new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          stats.current.longtaskCount += 1;
+          stats.current.longtaskTotalMs += entry.duration;
+          stats.current.longtaskMaxMs = Math.max(stats.current.longtaskMaxMs, entry.duration);
+        }
+      });
+      observer.observe({ type: "longtask", buffered: true });
+    } catch {
+      // longtask entries unsupported in this browser — panel shows zeros.
+    }
+    return () => observer?.disconnect();
+  }, [stats]);
+
+  // FPS: frames rendered within the trailing 1s window.
+  useEffect(() => {
+    let raf = 0;
+    const frames: number[] = [];
+    const loop = (now: number) => {
+      frames.push(now);
+      while (frames.length > 0 && frames[0] <= now - 1000) frames.shift();
+      stats.current.fps = frames.length;
+      raf = requestAnimationFrame(loop);
+    };
+    raf = requestAnimationFrame(loop);
+    return () => cancelAnimationFrame(raf);
+  }, [stats]);
+
+  // Flush the mutable stats into the display at most 2x/s.
+  useEffect(() => {
+    const id = window.setInterval(() => setSnapshot({ ...stats.current }), STATS_FLUSH_MS);
+    return () => window.clearInterval(id);
+  }, [stats]);
+
+  const resetLongtasks = () => {
+    stats.current.longtaskCount = 0;
+    stats.current.longtaskTotalMs = 0;
+    stats.current.longtaskMaxMs = 0;
+    setSnapshot({ ...stats.current });
+  };
+
+  const row: CSSProperties = { display: "flex", justifyContent: "space-between", gap: 8 };
+  return (
+    <div style={{ fontFamily: "monospace", fontSize: 12, lineHeight: 1.7 }}>
+      <div style={{ fontWeight: 700, marginBottom: 4 }}>Stats</div>
+      <div style={row}><span>FPS (1s)</span><span>{snapshot.fps}</span></div>
+      <div style={row}><span>Long tasks</span><span>{snapshot.longtaskCount}</span></div>
+      <div style={row}><span>Long total</span><span>{snapshot.longtaskTotalMs.toFixed(0)} ms</span></div>
+      <div style={row}><span>Long max</span><span>{snapshot.longtaskMaxMs.toFixed(0)} ms</span></div>
+      <div style={row}><span>SSE chunks</span><span>{snapshot.sseChunks}</span></div>
+      <div style={row}><span>SSE chars</span><span>{snapshot.sseChars.toLocaleString()}</span></div>
+      <div style={row}><span>Stream</span><span>{snapshot.streamState}</span></div>
+      <div style={row}>
+        <span>Mount A</span>
+        <span>{snapshot.mountAMs === null ? "—" : `${snapshot.mountAMs.toFixed(0)} ms`}</span>
+      </div>
+      <button type="button" onClick={resetLongtasks} style={{ marginTop: 6 }}>
+        Reset long tasks
+      </button>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Auto-send (scenario B): drive the REAL composer in the mounted DOM
+// ---------------------------------------------------------------------------
+
+/**
+ * Fill the composer textarea via the native value setter + an `input` event
+ * (React 18 controlled-input pattern), then click the enabled "Send" button.
+ * Retried on rAF until the elements exist (ChatThread mounts asynchronously).
+ */
+function autoSend(host: HTMLElement, text: string): void {
+  const deadline = performance.now() + AUTO_SEND_TIMEOUT_MS;
+
+  const tryClick = () => {
+    const button = host.querySelector<HTMLButtonElement>('button[aria-label="Send"]');
+    if (button && !button.disabled) {
+      button.click();
+      return;
+    }
+    if (performance.now() < deadline) requestAnimationFrame(tryClick);
+    else console.error("[perf] auto-send: Send button never became clickable");
+  };
+
+  const trySetValue = () => {
+    const textarea = host.querySelector("textarea");
+    if (!textarea) {
+      if (performance.now() < deadline) requestAnimationFrame(trySetValue);
+      else console.error("[perf] auto-send: textarea not found");
+      return;
+    }
+    const setter = Object.getOwnPropertyDescriptor(
+      window.HTMLTextAreaElement.prototype,
+      "value",
+    )?.set;
+    setter?.call(textarea, text);
+    textarea.dispatchEvent(new Event("input", { bubbles: true }));
+    // Click on a later frame so React commits the controlled value (which
+    // enables the Send button) before we press it.
+    requestAnimationFrame(tryClick);
+  };
+
+  requestAnimationFrame(trySetValue);
+}
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+interface MountState {
+  mode: "A" | "B";
+  key: number;
+  chatId: string | null;
+  rows: IAiChatMessageRow[];
+}
+
+const noop = (): void => {};
+
+export default function PerfHarness() {
+  const [preset, setPreset] = useState<PresetKey>("20k");
+  const [intervalMs, setIntervalMs] = useState<number>(15);
+  const [mounted, setMounted] = useState<MountState | null>(null);
+  const [fixtureInfo, setFixtureInfo] = useState<string | null>(null);
+
+  const statsRef = useRef<PerfStats>(emptyStats());
+  const hostRef = useRef<HTMLDivElement>(null);
+  const keyCounterRef = useRef(0);
+  const mountStartRef = useRef(0);
+  const pendingMountMeasureRef = useRef(false);
+
+  // The scripted live turn for the current preset (reused across B runs; the
+  // script is immutable data, so rebuilding per run is unnecessary).
+  const liveScript = useMemo(() => buildTurnScript(PRESETS[preset], "live"), [preset]);
+
+  const openPage = useMemo(() => ({ id: "page-1", title: "Perf test page" }), []);
+
+  // Scenario A: mount ChatThread seeded with a large persisted transcript.
+  const handleMountA = () => {
+    const fixture = buildPersistedRows(PRESETS[preset]);
+    setFixtureInfo(
+      `Persisted fixture: ${fixture.rows.length} rows, ` +
+        `${fixture.totalChars.toLocaleString()} chars ≈ ${fixture.approxTokens.toLocaleString()} tokens`,
+    );
+    statsRef.current.mountAMs = null;
+    // Mark AFTER fixture generation: we measure mount cost, not generation cost
+    // (production receives its rows from the network).
+    performance.mark("perf:mountA:start");
+    mountStartRef.current = performance.now();
+    pendingMountMeasureRef.current = true;
+    keyCounterRef.current += 1;
+    setMounted({ mode: "A", key: keyCounterRef.current, chatId: "perf-chat", rows: fixture.rows });
+  };
+
+  // Measure scenario A: effect runs after the mount commit; double rAF lands
+  // after the first paint of the mounted transcript.
+  useEffect(() => {
+    if (!pendingMountMeasureRef.current) return;
+    pendingMountMeasureRef.current = false;
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        statsRef.current.mountAMs = performance.now() - mountStartRef.current;
+        performance.mark("perf:mountA:end");
+        try {
+          performance.measure("perf:mountA", "perf:mountA:start", "perf:mountA:end");
+        } catch {
+          // Marks cleared mid-run — ignore.
+        }
+      });
+    });
+  }, [mounted]);
+
+  // Scenario B: mount an empty chat, arm the synthetic stream, auto-send.
+  const handleStartB = () => {
+    statsRef.current.sseChunks = 0;
+    statsRef.current.sseChars = 0;
+    statsRef.current.streamState = "streaming";
+    setLiveStreamSettings({
+      script: liveScript,
+      chunkIntervalMs: intervalMs,
+      onProgress: (chunks, chars) => {
+        statsRef.current.sseChunks = chunks;
+        statsRef.current.sseChars = chars;
+      },
+      onDone: () => {
+        statsRef.current.streamState = "done";
+        performance.mark("perf:streamB:end");
+        try {
+          performance.measure("perf:streamB", "perf:streamB:start", "perf:streamB:end");
+        } catch {
+          // Start mark missing (e.g. marks cleared) — ignore.
+        }
+      },
+      onAbort: () => {
+        statsRef.current.streamState = "aborted";
+      },
+    });
+    performance.mark("perf:streamB:start");
+    keyCounterRef.current += 1;
+    setMounted({ mode: "B", key: keyCounterRef.current, chatId: null, rows: [] });
+    if (hostRef.current) autoSend(hostRef.current, AUTO_SEND_TEXT);
+  };
+
+  const handleUnmount = () => setMounted(null);
+
+  const label: CSSProperties = { display: "block", fontSize: 12, margin: "10px 0 2px" };
+  const button: CSSProperties = { display: "block", width: "100%", margin: "6px 0", padding: "6px 8px" };
+
+  return (
+    <div style={{ display: "flex", height: "100vh", fontFamily: "system-ui, sans-serif" }}>
+      {/* Left: controls + stats */}
+      <div
+        style={{
+          width: 260,
+          flex: "0 0 260px",
+          padding: 12,
+          borderRight: "1px solid #ccc",
+          overflowY: "auto",
+          boxSizing: "border-box",
+        }}
+      >
+        <div style={{ fontWeight: 700, marginBottom: 4 }}>AI chat perf harness</div>
+
+        <label style={label}>Preset</label>
+        <select
+          value={preset}
+          onChange={(e) => setPreset(e.target.value as PresetKey)}
+          style={{ width: "100%" }}
+        >
+          <option value="5k">5k tokens</option>
+          <option value="20k">20k tokens</option>
+          <option value="50k">50k tokens</option>
+        </select>
+
+        <label style={label}>Chunk interval (scenario B)</label>
+        <select
+          value={intervalMs}
+          onChange={(e) => setIntervalMs(Number(e.target.value))}
+          style={{ width: "100%" }}
+        >
+          <option value={15}>15 ms (normal)</option>
+          <option value={5}>5 ms (stress)</option>
+        </select>
+
+        <div style={{ marginTop: 12 }}>
+          <button type="button" style={button} onClick={handleMountA}>
+            Mount persisted chat (A)
+          </button>
+          <button type="button" style={button} onClick={handleStartB}>
+            Start live stream (B)
+          </button>
+          <button type="button" style={button} onClick={handleUnmount} disabled={!mounted}>
+            Unmount
+          </button>
+        </div>
+
+        <div style={{ fontSize: 11, color: "#555", margin: "8px 0" }}>
+          <div>
+            Live turn: {liveScript.totalChars.toLocaleString()} chars ≈{" "}
+            {liveScript.approxTokens.toLocaleString()} tokens
+          </div>
+          {fixtureInfo && <div>{fixtureInfo}</div>}
+          {mounted && (
+            <div>
+              Mounted: scenario {mounted.mode} (key {mounted.key})
+            </div>
+          )}
+        </div>
+
+        <hr style={{ border: "none", borderTop: "1px solid #ddd" }} />
+        <StatsPanel stats={statsRef} />
+      </div>
+
+      {/* Right: the real ChatThread inside a real-window-sized box */}
+      <div
+        style={{
+          flex: 1,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          background: "#f4f4f5",
+        }}
+      >
+        <div
+          ref={hostRef}
+          style={{
+            width: 540,
+            height: 680,
+            border: "1px solid #bbb",
+            borderRadius: 8,
+            background: "#fff",
+            padding: 8,
+            boxSizing: "border-box",
+            overflow: "hidden",
+          }}
+        >
+          {mounted ? (
+            <ChatThread
+              key={mounted.key}
+              chatId={mounted.chatId}
+              threadKey={`perf-${mounted.key}`}
+              initialRows={mounted.rows}
+              openPage={openPage}
+              roleId={null}
+              roles={[]}
+              onRolePicked={noop}
+              assistantName="Perf agent"
+              onTurnFinished={noop}
+              onServerChatId={noop}
+            />
+          ) : (
+            <div style={{ color: "#888", fontSize: 13, padding: 16 }}>
+              ChatThread unmounted. Use the controls on the left.
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

apps/client/perf/synthetic-turn.ts

@@ -0,0 +1,517 @@
+/**
+ * DEV-ONLY synthetic agent-turn generator for the AI chat perf harness.
+ *
+ * Produces one scripted agent turn (reasoning + tool calls + markdown answer)
+ * from a size config, and materializes it two ways:
+ *  - as an AI SDK v6 UI-message SSE stream (scenario B "live agent stream"),
+ *    served by a `window.fetch` patch that intercepts `/api/ai-chat/stream`;
+ *  - as persisted `IAiChatMessageRow[]` history (scenario A "open existing chat").
+ *
+ * Wire format verified against the installed ai@6.0.207 `uiMessageChunkSchema`
+ * (strict objects — only the exact field names below are accepted).
+ */
+
+import type { UIMessage } from "@ai-sdk/react";
+import type { IAiChatMessageRow } from "../src/features/ai-chat/types/ai-chat.types.ts";
+
+// ---------------------------------------------------------------------------
+// Config / presets
+// ---------------------------------------------------------------------------
+
+/** 1 token ~= 4 chars — the approximation used throughout this module. */
+const CHARS_PER_TOKEN = 4;
+
+export interface TurnConfig {
+  /** Number of agent steps; each step = one reasoning block + one tool call. */
+  steps: number;
+  /** Approximate reasoning tokens generated per step. */
+  reasoningTokensPerStep: number;
+  /** Size of each tool call's output `content` filler, in bytes (ASCII). */
+  toolOutputBytes: number;
+  /** Approximate size of the final markdown answer, in tokens. */
+  answerTokens: number;
+}
+
+export type PresetKey = "5k" | "20k" | "50k";
+
+export const PRESETS: Record<PresetKey, TurnConfig> = {
+  "5k": {
+    steps: 3,
+    reasoningTokensPerStep: 500,
+    toolOutputBytes: 10_000,
+    answerTokens: 600,
+  },
+  "20k": {
+    steps: 6,
+    reasoningTokensPerStep: 2500,
+    toolOutputBytes: 20_000,
+    answerTokens: 1500,
+  },
+  "50k": {
+    steps: 10,
+    reasoningTokensPerStep: 4000,
+    toolOutputBytes: 40_000,
+    answerTokens: 3000,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Text generators
+// ---------------------------------------------------------------------------
+
+/** Mixed Russian/English prose sentences cycled to build reasoning text. */
+const REASONING_SENTENCES = [
+  "Пользователь просит проанализировать документ и выделить ключевые тезисы по каждому разделу.",
+  "First I need to inspect the current page content to understand its overall structure.",
+  "Судя по оглавлению, раздел с техническими требованиями находится ближе к концу документа.",
+  "The table in section three contains the migration matrix that I should cross-check against the summary.",
+  "Проверю, нет ли противоречий между описанием API и приведёнными в тексте примерами вызовов.",
+  "Let me compare the numbers from the executive summary with the raw data in the appendix.",
+  "Похоже, автор использует термины «воркспейс» и workspace взаимозаменяемо — это стоит нормализовать.",
+  "I should keep the page ids from the tool output so the final answer can cite the source pages.",
+  "Осталось свести найденные несоответствия в одну таблицу и предложить порядок исправлений.",
+  "The remaining sections look consistent, so I can move on to drafting the structured answer.",
+];
+
+/**
+ * Build realistic prose of ~`targetChars` characters, inserting a newline
+ * roughly every 200 characters (mirrors how reasoning text tends to wrap).
+ */
+function makeProse(targetChars: number): string {
+  const pieces: string[] = [];
+  let length = 0;
+  let sinceNewline = 0;
+  let i = 0;
+  while (length < targetChars) {
+    const sentence = REASONING_SENTENCES[i % REASONING_SENTENCES.length];
+    i += 1;
+    pieces.push(sentence);
+    length += sentence.length + 1;
+    sinceNewline += sentence.length + 1;
+    if (sinceNewline >= 200) {
+      pieces.push("\n");
+      sinceNewline = 0;
+    } else {
+      pieces.push(" ");
+    }
+  }
+  return pieces.join("").trimEnd();
+}
+
+/** One markdown section (~700 chars): heading, prose, bullets, GFM table, code. */
+function markdownSection(n: number): string {
+  return [
+    `## Section ${n}: migration analysis`,
+    ``,
+    `The workspace contains **${n * 12} pages** that still reference the legacy API. ` +
+      `Most of them live under [Perf test page](/p/page-1) and need the new transport. ` +
+      `Ниже приведена сводка по разделу с оценкой трудозатрат и основных рисков.`,
+    ``,
+    `- Update the fetch layer to the v6 transport`,
+    `- Перенести таблицы соответствия идентификаторов`,
+    `- Verify citation links after the move`,
+    `- Проверить отображение длинных ответов в узкой панели`,
+    ``,
+    `| Область | Страниц | Статус | Риск |`,
+    `| --- | --- | --- | --- |`,
+    `| API reference | ${n + 4} | migrated | low |`,
+    `| Onboarding | ${n + 2} | in progress | medium |`,
+    `| Release notes | ${n * 3} | pending | high |`,
+    ``,
+    "```ts",
+    `export function migrateSection${n}(rows: Row[]): Row[] {`,
+    `  return rows`,
+    `    .filter((row) => row.section === ${n})`,
+    `    .map((row) => ({ ...row, migrated: true }));`,
+    `}`,
+    "```",
+  ].join("\n");
+}
+
+/** Realistic markdown answer of ~`targetChars` chars (sections repeated to size). */
+function makeMarkdownAnswer(targetChars: number): string {
+  const sections: string[] = [];
+  let length = 0;
+  let n = 1;
+  while (length < targetChars) {
+    const section = markdownSection(n);
+    sections.push(section);
+    length += section.length + 2;
+    n += 1;
+  }
+  return sections.join("\n\n");
+}
+
+/** Plain ASCII filler of exactly `bytes` characters for tool outputs. */
+function makeFiller(bytes: number): string {
+  const unit = "Perf filler content for the synthetic getPage tool output. ";
+  return unit.repeat(Math.ceil(bytes / unit.length)).slice(0, bytes);
+}
+
+// ---------------------------------------------------------------------------
+// Turn script
+// ---------------------------------------------------------------------------
+
+export interface TurnToolCall {
+  toolCallId: string;
+  toolName: "getPage";
+  input: { pageId: string };
+  output: { id: string; title: string; content: string };
+}
+
+export interface TurnStep {
+  reasoningText: string;
+  tool: TurnToolCall;
+}
+
+export interface TurnScript {
+  steps: TurnStep[];
+  answerText: string;
+  /** Approximate reasoning tokens for the whole turn (chars / 4). */
+  reasoningTokens: number;
+  /** Approximate context size after this turn, in tokens. */
+  contextTokens: number;
+  maxContextTokens: number;
+  /** Actual generated visible chars: reasoning + tool outputs + answer. */
+  totalChars: number;
+  /** totalChars / 4, rounded. */
+  approxTokens: number;
+}
+
+/**
+ * Build the scripted agent turn for a config. `idPrefix` keeps tool call ids
+ * unique when several scripts coexist (e.g. 3 persisted turns in one chat).
+ */
+export function buildTurnScript(config: TurnConfig, idPrefix = "live"): TurnScript {
+  const steps: TurnStep[] = [];
+  let reasoningChars = 0;
+  let toolChars = 0;
+  for (let i = 0; i < config.steps; i++) {
+    const reasoningText = makeProse(config.reasoningTokensPerStep * CHARS_PER_TOKEN);
+    const content = makeFiller(config.toolOutputBytes);
+    reasoningChars += reasoningText.length;
+    toolChars += content.length;
+    steps.push({
+      reasoningText,
+      tool: {
+        toolCallId: `${idPrefix}-call-${i + 1}`,
+        toolName: "getPage",
+        input: { pageId: "page-1" },
+        output: { id: "page-1", title: "Perf test page", content },
+      },
+    });
+  }
+  const answerText = makeMarkdownAnswer(config.answerTokens * CHARS_PER_TOKEN);
+  const totalChars = reasoningChars + toolChars + answerText.length;
+  return {
+    steps,
+    answerText,
+    reasoningTokens: Math.round(reasoningChars / CHARS_PER_TOKEN),
+    contextTokens: Math.round(totalChars / CHARS_PER_TOKEN),
+    maxContextTokens: 200_000,
+    totalChars,
+    approxTokens: Math.round(totalChars / CHARS_PER_TOKEN),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Scenario A: persisted rows
+// ---------------------------------------------------------------------------
+
+/** Number of user+assistant pairs the preset is split across for history. */
+const HISTORY_TURNS = 3;
+
+const USER_PROMPTS = [
+  "Проанализируй документ и выдели ключевые тезисы по каждому разделу.",
+  "Now cross-check the migration matrix against the summary and list every mismatch.",
+  "Собери финальный план миграции с оценкой рисков по каждой области.",
+];
+
+/** Persisted UIMessage parts for one finished assistant turn. */
+function scriptToPersistedParts(script: TurnScript): UIMessage["parts"] {
+  const parts: unknown[] = [];
+  for (const step of script.steps) {
+    parts.push({ type: "reasoning", text: step.reasoningText, state: "done" });
+    parts.push({
+      type: `tool-${step.tool.toolName}`,
+      toolCallId: step.tool.toolCallId,
+      state: "output-available",
+      input: step.tool.input,
+      output: step.tool.output,
+    });
+  }
+  parts.push({ type: "text", text: script.answerText, state: "done" });
+  return parts as UIMessage["parts"];
+}
+
+export interface PersistedFixture {
+  rows: IAiChatMessageRow[];
+  totalChars: number;
+  approxTokens: number;
+}
+
+/**
+ * Materialize the preset as a finished 3-turn transcript: user row + assistant
+ * row per turn, with the preset's steps/answer split across the assistant turns.
+ * Approximate accounting — the actual totals are reported back for display.
+ */
+export function buildPersistedRows(config: TurnConfig): PersistedFixture {
+  const rows: IAiChatMessageRow[] = [];
+  const baseTime = Date.now() - HISTORY_TURNS * 60_000;
+  let totalChars = 0;
+
+  for (let t = 0; t < HISTORY_TURNS; t++) {
+    // Distribute steps as evenly as possible (earlier turns get the remainder).
+    const stepsForTurn =
+      Math.floor(config.steps / HISTORY_TURNS) +
+      (t < config.steps % HISTORY_TURNS ? 1 : 0);
+    const turnConfig: TurnConfig = {
+      steps: Math.max(1, stepsForTurn),
+      reasoningTokensPerStep: config.reasoningTokensPerStep,
+      toolOutputBytes: config.toolOutputBytes,
+      answerTokens: Math.max(50, Math.round(config.answerTokens / HISTORY_TURNS)),
+    };
+    const script = buildTurnScript(turnConfig, `hist-${t + 1}`);
+    totalChars += script.totalChars;
+
+    const userText = USER_PROMPTS[t % USER_PROMPTS.length];
+    rows.push({
+      id: `perf-row-u${t + 1}`,
+      role: "user",
+      content: userText,
+      metadata: null,
+      createdAt: new Date(baseTime + t * 60_000).toISOString(),
+    });
+    rows.push({
+      id: `perf-row-a${t + 1}`,
+      role: "assistant",
+      content: script.answerText,
+      metadata: {
+        parts: scriptToPersistedParts(script),
+        usage: { reasoningTokens: script.reasoningTokens },
+        contextTokens: script.contextTokens,
+        maxContextTokens: script.maxContextTokens,
+        finishReason: "stop",
+      },
+      createdAt: new Date(baseTime + t * 60_000 + 30_000).toISOString(),
+    });
+  }
+
+  return {
+    rows,
+    totalChars,
+    approxTokens: Math.round(totalChars / CHARS_PER_TOKEN),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Scenario B: SSE stream
+// ---------------------------------------------------------------------------
+
+/** Streaming delta size in chars (reasoning/answer text is split into these). */
+const DELTA_CHARS = 200;
+
+function splitDeltas(text: string, size = DELTA_CHARS): string[] {
+  const deltas: string[] = [];
+  for (let i = 0; i < text.length; i += size) {
+    deltas.push(text.slice(i, i + size));
+  }
+  return deltas;
+}
+
+/** One pre-serialized SSE frame plus its visible-char contribution for stats. */
+interface SseFrame {
+  data: string;
+  chars: number;
+}
+
+function frame(chunk: Record<string, unknown>, chars = 0): SseFrame {
+  return { data: `data: ${JSON.stringify(chunk)}\n\n`, chars };
+}
+
+/**
+ * Serialize the whole scripted turn into AI SDK v6 UI-message SSE frames
+ * (excluding the final `data: [DONE]` terminator, appended by the pump).
+ */
+function buildSseFrames(script: TurnScript, messageId: string, chatId: string): SseFrame[] {
+  const frames: SseFrame[] = [];
+  frames.push(frame({ type: "start", messageId, messageMetadata: { chatId } }));
+
+  script.steps.forEach((step, i) => {
+    frames.push(frame({ type: "start-step" }));
+    const reasoningId = `${messageId}-r${i + 1}`;
+    frames.push(frame({ type: "reasoning-start", id: reasoningId }));
+    for (const delta of splitDeltas(step.reasoningText)) {
+      frames.push(frame({ type: "reasoning-delta", id: reasoningId, delta }, delta.length));
+    }
+    frames.push(frame({ type: "reasoning-end", id: reasoningId }));
+
+    const { toolCallId, toolName, input, output } = step.tool;
+    frames.push(frame({ type: "tool-input-start", toolCallId, toolName }));
+    frames.push(frame({ type: "tool-input-available", toolCallId, toolName, input }));
+    // The tool result arrives as ONE chunk, like the real server sends it.
+    frames.push(frame({ type: "tool-output-available", toolCallId, output }, output.content.length));
+    frames.push(frame({ type: "finish-step" }));
+  });
+
+  // Final step: the markdown answer.
+  frames.push(frame({ type: "start-step" }));
+  const textId = `${messageId}-answer`;
+  frames.push(frame({ type: "text-start", id: textId }));
+  for (const delta of splitDeltas(script.answerText)) {
+    frames.push(frame({ type: "text-delta", id: textId, delta }, delta.length));
+  }
+  frames.push(frame({ type: "text-end", id: textId }));
+  frames.push(frame({ type: "finish-step" }));
+
+  frames.push(
+    frame({
+      type: "finish",
+      messageMetadata: {
+        usage: { reasoningTokens: script.reasoningTokens },
+        contextTokens: script.contextTokens,
+        maxContextTokens: script.maxContextTokens,
+        finishReason: "stop",
+      },
+    }),
+  );
+  return frames;
+}
+
+export interface LiveStreamSettings {
+  script: TurnScript;
+  /** Delay between SSE chunks (one chunk per tick). */
+  chunkIntervalMs: number;
+  /** Progress callback: cumulative emitted chunk count and visible chars. */
+  onProgress?: (chunks: number, chars: number) => void;
+  /** Fired once after the `[DONE]` terminator is enqueued. */
+  onDone?: () => void;
+  /** Fired if the client aborted the stream (Stop button). */
+  onAbort?: () => void;
+}
+
+/**
+ * Build a synthetic SSE Response streaming the scripted turn, one chunk every
+ * `chunkIntervalMs`. Honors the fetch `AbortSignal` so the real Stop button works.
+ */
+export function buildSseResponse(
+  settings: LiveStreamSettings,
+  signal?: AbortSignal | null,
+): Response {
+  const messageId = `m-live-${Date.now()}`;
+  const frames = buildSseFrames(settings.script, messageId, "perf-chat");
+  const encoder = new TextEncoder();
+  let index = 0;
+  let emittedChars = 0;
+  let timer: number | undefined;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const stopPump = () => {
+        if (timer !== undefined) {
+          clearTimeout(timer);
+          timer = undefined;
+        }
+      };
+      const pump = () => {
+        timer = undefined;
+        if (signal?.aborted) {
+          stopPump();
+          try {
+            controller.close();
+          } catch {
+            // Already closed/cancelled — nothing to do.
+          }
+          return;
+        }
+        if (index >= frames.length) {
+          try {
+            controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+            controller.close();
+          } catch {
+            // Cancelled mid-flight.
+          }
+          settings.onDone?.();
+          return;
+        }
+        const next = frames[index];
+        index += 1;
+        try {
+          controller.enqueue(encoder.encode(next.data));
+        } catch {
+          stopPump();
+          return;
+        }
+        emittedChars += next.chars;
+        settings.onProgress?.(index, emittedChars);
+        timer = window.setTimeout(pump, settings.chunkIntervalMs);
+      };
+      signal?.addEventListener(
+        "abort",
+        () => {
+          stopPump();
+          try {
+            controller.close();
+          } catch {
+            // Reader already cancelled.
+          }
+          settings.onAbort?.();
+        },
+        { once: true },
+      );
+      timer = window.setTimeout(pump, settings.chunkIntervalMs);
+    },
+    cancel() {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+    },
+  });
+
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "content-type": "text/event-stream",
+      "cache-control": "no-cache",
+      "x-vercel-ai-ui-message-stream": "v1",
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// window.fetch patch
+// ---------------------------------------------------------------------------
+
+let currentLiveSettings: LiveStreamSettings | null = null;
+
+/** Arm the next `/api/ai-chat/stream` request with a scripted turn. */
+export function setLiveStreamSettings(settings: LiveStreamSettings): void {
+  currentLiveSettings = settings;
+}
+
+/**
+ * Patch `window.fetch` BEFORE React mounts: requests to `/api/ai-chat/stream`
+ * get the synthetic SSE Response; everything else passes through untouched.
+ */
+export function installAiChatStreamFetchPatch(): void {
+  const originalFetch = window.fetch.bind(window);
+  window.fetch = (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.href
+          : input.url;
+    if (url.includes("/api/ai-chat/stream")) {
+      const settings = currentLiveSettings;
+      if (!settings) {
+        return Promise.resolve(
+          new Response("perf harness: no live stream configured", { status: 500 }),
+        );
+      }
+      return Promise.resolve(buildSseResponse(settings, init?.signal ?? null));
+    }
+    return originalFetch(input, init);
+  };
+}

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

@@ -1222,8 +1222,8 @@
   "Commented": "Commented",
   "Resolved comment": "Resolved comment",
   "Ran tool {{name}}": "Ran tool {{name}}",
-  "AI-agent": "AI-agent",
-  "Edited by AI agent on behalf of {{name}}": "Edited by AI agent on behalf of {{name}}",
+  "AI agent «{{role}}» on behalf of {{person}}": "AI agent «{{role}}» on behalf of {{person}}",
+  "AI agent {{name}}": "AI agent {{name}}",
   "Endpoints": "Endpoints",
   "where we fetch models": "where we fetch models",
   "All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.": "All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.",
@@ -1274,6 +1274,10 @@
   "Voice dictation is not configured": "Voice dictation is not configured",
   "Microphone is unavailable or already in use": "Microphone is unavailable or already in use",
   "Audio recording is not available in this browser/context": "Audio recording is not available in this browser/context",
+  "Dictation": "Dictation",
+  "Dictation becomes available once the page finishes connecting": "Dictation becomes available once the page finishes connecting",
+  "No connection to the collaboration server — dictation unavailable": "No connection to the collaboration server — dictation unavailable",
+  "This page is read-only": "This page is read-only",
   "Request format": "Request format",
   "How transcription requests are sent to the endpoint": "How transcription requests are sent to the endpoint",
   "OpenAI-compatible (multipart/form-data)": "OpenAI-compatible (multipart/form-data)",
@@ -1373,5 +1377,10 @@
   "Updated to the latest version": "Updated to the latest version",
   "This role is no longer in the catalog": "This role is no longer in the catalog",
   "This language is no longer available in the catalog": "This language is no longer available in the catalog",
-  "Connecting… (read-only)": "Connecting… (read-only)"
+  "Connecting… (read-only)": "Connecting… (read-only)",
+  "Apply": "Apply",
+  "Applied": "Applied",
+  "Suggestion applied": "Suggestion applied",
+  "Failed to apply suggestion": "Failed to apply suggestion",
+  "The commented text changed since this suggestion was made; it was not applied.": "The commented text changed since this suggestion was made; it was not applied."
 }

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

@@ -393,6 +393,17 @@
   "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",
@@ -724,7 +735,8 @@
   "Shown as used / total in the chat header. Leave empty to hide the limit.": "Показывается в шапке чата как использовано / всего. Пусто — лимит скрыт.",
   "Delete this chat?": "Удалить этот чат?",
   "Deleted successfully": "Успешно удалено",
-  "Edited by AI agent on behalf of {{name}}": "Отредактировано AI-агентом от имени {{name}}",
+  "AI agent «{{role}}» on behalf of {{person}}": "AI-агент «{{role}}» от имени {{person}}",
+  "AI agent {{name}}": "AI-агент {{name}}",
   "Failed to delete chat": "Не удалось удалить чат",
   "Failed to rename chat": "Не удалось переименовать чат",
   "Failed": "Ошибка",
@@ -1228,5 +1240,10 @@
   "Updated to the latest version": "Обновлено до последней версии",
   "This role is no longer in the catalog": "Эта роль больше не представлена в каталоге",
   "This language is no longer available in the catalog": "Этот язык больше не доступен в каталоге",
-  "Connecting… (read-only)": "Подключение… (только чтение)"
+  "Connecting… (read-only)": "Подключение… (только чтение)",
+  "Apply": "Применить",
+  "Applied": "Применено",
+  "Suggestion applied": "Предложение применено",
+  "Failed to apply suggestion": "Не удалось применить предложение",
+  "The commented text changed since this suggestion was made; it was not applied.": "Прокомментированный текст изменился после создания предложения; оно не было применено."
 }

apps/client/src/components/ui/agent-avatar-stack.test.tsx

@@ -0,0 +1,183 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import { Provider, createStore } from "jotai";
+import { AgentAvatarStack } from "./agent-avatar-stack";
+import { avatarStyle } from "@/lib/avatar-palette";
+import {
+  activeAiChatIdAtom,
+  aiChatWindowOpenAtom,
+  aiChatDraftAtom,
+} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
+
+// matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
+
+type Props = React.ComponentProps<typeof AgentAvatarStack>;
+
+// The DOM normalizes an inline hex `background-color` to `rgb(...)`. Push the
+// expected color through the same CSSOM path so the comparison stays exact and
+// non-vacuous (an empty string — i.e. no inline background, as in the pre-fix
+// Avatar approach — can never match a real color). NOTE: jsdom's CSSOM does not
+// round-trip a `linear-gradient` in the `background` shorthand, which is why the
+// glyph carries an explicit solid `background-color` we assert on here.
+function normalizeColor(value: string): string {
+  const probe = document.createElement("div");
+  probe.style.backgroundColor = value;
+  return probe.style.backgroundColor;
+}
+
+function renderStack(props: Props) {
+  const store = createStore();
+  store.set(aiChatDraftAtom, "leftover draft from another chat");
+  const utils = render(
+    <Provider store={store}>
+      <MantineProvider>
+        <AgentAvatarStack {...props} />
+      </MantineProvider>
+    </Provider>,
+  );
+  return { store, ...utils };
+}
+
+describe("AgentAvatarStack", () => {
+  it("internal chat WITH role: emoji glyph + human launcher badge in front", () => {
+    const { container } = renderStack({
+      agent: { name: "Researcher", emoji: "🔬", avatarUrl: null },
+      launcher: { name: "Alice", avatarUrl: null },
+      aiChatId: "chat-1",
+    });
+
+    // Emoji is used as the glyph (priority 2), NOT the sparkles fallback.
+    expect(screen.getByText("🔬")).toBeDefined();
+    expect(container.querySelector(".tabler-icon-sparkles")).toBeNull();
+    // Label: bold role name + dimmed "· launcher".
+    expect(screen.getByText("Researcher")).toBeDefined();
+    expect(screen.getByText(/·/)).toBeDefined();
+    expect(screen.getByText("Alice")).toBeDefined();
+  });
+
+  it("emoji glyph applies its per-agent gradient as an inline DOM background", () => {
+    // Pins the actual fix: the hashed gradient must reach the DOM as an inline
+    // `background` on the glyph Box. The pre-fix `Avatar variant="filled"` set no
+    // inline background (Mantine's --avatar-bg overrode it), so this fails there.
+    const agent = { name: "Researcher", emoji: "🔬", avatarUrl: null };
+    const { container } = renderStack({
+      agent,
+      launcher: { name: "Alice", avatarUrl: null },
+      aiChatId: "chat-1",
+    });
+
+    const glyph = container.querySelector<HTMLElement>(
+      '[data-testid="agent-glyph"]',
+    );
+    expect(glyph).not.toBeNull();
+    const expected = normalizeColor(avatarStyle(agent.name).bg);
+    // Non-vacuous: the pre-fix Avatar set no inline background at all.
+    expect(expected).not.toBe("");
+    expect(glyph!.style.backgroundColor).toBe(expected);
+    // (The gradient overlay is a browser-only enhancement — jsdom's CSSOM does
+    // not round-trip linear-gradient — so its stops/angle are covered by the
+    // avatarStyle unit tests above, not asserted on the DOM here.)
+  });
+
+  it("agents with distinct styles reach the DOM as distinct backgrounds", () => {
+    // "Researcher" and "Нарратор" hash to different palette entries, so their
+    // applied DOM backgrounds must differ — pins "distinct colors reach the DOM".
+    expect(avatarStyle("Researcher").bg).not.toBe(avatarStyle("Нарратор").bg);
+
+    const a = renderStack({
+      agent: { name: "Researcher", emoji: "🔬", avatarUrl: null },
+      launcher: null,
+      aiChatId: null,
+    });
+    const b = renderStack({
+      agent: { name: "Нарратор", emoji: "📖", avatarUrl: null },
+      launcher: null,
+      aiChatId: null,
+    });
+
+    const glyphA = a.container.querySelector<HTMLElement>(
+      '[data-testid="agent-glyph"]',
+    );
+    const glyphB = b.container.querySelector<HTMLElement>(
+      '[data-testid="agent-glyph"]',
+    );
+    expect(glyphA!.style.backgroundColor).not.toBe("");
+    // Different base colors reach the DOM (the serialized rgb values differ).
+    expect(glyphA!.style.backgroundColor).not.toBe(glyphB!.style.backgroundColor);
+  });
+
+  it("showName=false: renders only the avatars, no inline name label", () => {
+    renderStack({
+      agent: { name: "Researcher", emoji: "🔬", avatarUrl: null },
+      launcher: { name: "Alice", avatarUrl: null },
+      aiChatId: "chat-1",
+      showName: false,
+    });
+
+    // The agent glyph is still rendered...
+    expect(screen.getByText("🔬")).toBeDefined();
+    // ...but neither the agent NOR the launcher inline name label is rendered
+    // (they live only in the hover tooltip, which is not mounted in the initial
+    // DOM) — guards against suppressing only the agent name and leaking the
+    // launcher name.
+    expect(screen.queryByText("Researcher")).toBeNull();
+    expect(screen.queryByText("Alice")).toBeNull();
+  });
+
+  it("internal chat WITHOUT role: sparkles fallback + 'AI agent' + launcher", () => {
+    const { container } = renderStack({
+      agent: { name: "AI agent", avatarUrl: null },
+      launcher: { name: "Bob", avatarUrl: null },
+      aiChatId: "chat-2",
+    });
+
+    // No avatarUrl and no emoji => sparkles glyph (priority 3).
+    expect(container.querySelector(".tabler-icon-sparkles")).not.toBeNull();
+    expect(screen.getByText("AI agent")).toBeDefined();
+    expect(screen.getByText("Bob")).toBeDefined();
+  });
+
+  it("external MCP: agent avatar only, NO human launcher badge", () => {
+    const { container } = renderStack({
+      agent: { name: "MCP Bot", avatarUrl: "http://example.test/a.png" },
+      launcher: null,
+      aiChatId: null,
+    });
+
+    // avatarUrl provided (priority 1) => not the sparkles fallback.
+    expect(container.querySelector(".tabler-icon-sparkles")).toBeNull();
+    expect(screen.getByText("MCP Bot")).toBeDefined();
+    // No human behind => no "·" separator is rendered.
+    expect(screen.queryByText(/·/)).toBeNull();
+    // No internal chat => the stack is not an interactive deep-link button.
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+
+  it("click deep-links into the chat when aiChatId is present", () => {
+    const { store } = renderStack({
+      agent: { name: "Researcher", emoji: "🔬", avatarUrl: null },
+      launcher: { name: "Alice", avatarUrl: null },
+      aiChatId: "chat-1",
+    });
+
+    const button = screen.getByRole("button");
+    fireEvent.click(button);
+
+    expect(store.get(activeAiChatIdAtom)).toBe("chat-1");
+    expect(store.get(aiChatWindowOpenAtom)).toBe(true);
+    expect(store.get(aiChatDraftAtom)).toBe(""); // draft cleared on switch
+  });
+
+  it("click is a no-op / not interactive without a chat target", () => {
+    const onActivate = vi.fn();
+    renderStack({
+      agent: { name: "MCP Bot", avatarUrl: "http://example.test/a.png" },
+      launcher: null,
+      aiChatId: null,
+      onActivate,
+    });
+    expect(screen.queryByRole("button")).toBeNull();
+    expect(onActivate).not.toHaveBeenCalled();
+  });
+});

apps/client/src/components/ui/agent-avatar-stack.tsx

@@ -0,0 +1,234 @@
+import { Box, Group, Text, Tooltip } from "@mantine/core";
+import { IconSparkles } from "@tabler/icons-react";
+import { useCallback } from "react";
+import { useTranslation } from "react-i18next";
+import { useSetAtom } from "jotai";
+import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
+import { avatarStyle, avatarBackgroundCss } from "@/lib/avatar-palette";
+import {
+  activeAiChatIdAtom,
+  aiChatWindowOpenAtom,
+  aiChatDraftAtom,
+} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
+
+// The FRONT identity (the acting agent) and the BEHIND identity (the human who
+// launched it). Both are computed server-side (#300) so the client never branches
+// on the internal-vs-MCP provenance — it just renders whatever it is handed.
+export interface AgentInfo {
+  name: string;
+  emoji?: string | null;
+  avatarUrl?: string | null;
+}
+export interface LauncherInfo {
+  name: string;
+  avatarUrl?: string | null;
+}
+
+const GLYPH_SIZE = 38;
+const LAUNCHER_SIZE = 22;
+// How far the launcher avatar sticks out past the agent's top-right corner — it
+// sits as a small badge over that corner (above the glyph) and stays fully visible.
+const LAUNCHER_OVERHANG = 8;
+
+/**
+ * The front avatar. Image-source priority (#300):
+ *   1. agent.avatarUrl -> a real avatar image (external MCP agent account).
+ *   2. agent.emoji     -> the role emoji on a per-agent gradient circle.
+ *   3. otherwise       -> the IconSparkles glyph on a per-agent gradient circle.
+ */
+function AgentGlyph({ agent }: { agent: AgentInfo }) {
+  if (agent.avatarUrl) {
+    return (
+      <CustomAvatar
+        size={GLYPH_SIZE}
+        avatarUrl={agent.avatarUrl}
+        name={agent.name}
+      />
+    );
+  }
+
+  // Emoji/sparkles glyph on a per-agent gradient circle (color, gradient partner
+  // and split angle all hashed from the agent name via avatarStyle — see
+  // @/lib/avatar-palette). Rendered as a plain Box, NOT a Mantine
+  // `Avatar variant="filled"` — Mantine's `--avatar-bg` overrode the background
+  // (every agent fell back to the theme's violet). The foreground (the sparkles
+  // icon) uses the ring's WCAG-checked readable text color.
+  const style = avatarStyle(agent.name);
+  return (
+    <Box
+      data-testid="agent-glyph"
+      style={{
+        width: GLYPH_SIZE,
+        height: GLYPH_SIZE,
+        borderRadius: "50%",
+        // Solid base color is the fallback (and the testable value); the gradient
+        // paints over it in browsers that support it.
+        backgroundColor: style.bg,
+        backgroundImage: avatarBackgroundCss(style),
+        color:
+          style.text === "white"
+            ? "var(--mantine-color-white)"
+            : "var(--mantine-color-black)",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        lineHeight: 1,
+      }}
+    >
+      {agent.emoji ? (
+        <span style={{ fontSize: Math.round(GLYPH_SIZE * 0.5) }} aria-hidden>
+          {agent.emoji}
+        </span>
+      ) : (
+        <IconSparkles size={Math.round(GLYPH_SIZE * 0.55)} stroke={2} />
+      )}
+    </Box>
+  );
+}
+
+export interface AgentAvatarStackProps {
+  agent: AgentInfo;
+  // null/absent => external MCP (front agent avatar only, no human behind).
+  launcher?: LauncherInfo | null;
+  // Deep-links into the internal AI chat when present (null for external MCP).
+  aiChatId?: string | null;
+  // Fired after the stack deep-links into its chat, so the caller can react
+  // (e.g. the page-history row closes the history modal). Keeps this ui/ primitive
+  // free of cross-feature coupling (inherited from the old AiAgentBadge, #143).
+  onActivate?: () => void;
+  // Whether to render the inline name label next to the avatars (default true).
+  // Set false when the caller renders the name itself (e.g. the comment row).
+  showName?: boolean;
+}
+
+/**
+ * The "agent avatar stack" (#300): the AGENT glyph, and — for an internal AI
+ * chat — the HUMAN who launched it as a smaller avatar badge on top, overhanging
+ * the glyph's top-right corner in FRONT (zIndex 2 > the glyph's zIndex 1) so the
+ * launcher stays fully visible rather than being half-hidden behind the glyph.
+ * Replaces the old text `AI-agent` badge. When the item carries an `aiChatId` the
+ * whole stack is a deep-link into that chat (the click the old badge owned moved
+ * here); the click is contained (stopPropagation) so it does not also trigger an
+ * enclosing row handler.
+ */
+export function AgentAvatarStack({
+  agent,
+  launcher,
+  aiChatId,
+  onActivate,
+  showName = true,
+}: AgentAvatarStackProps) {
+  const { t } = useTranslation();
+  const setAiChatWindowOpen = useSetAtom(aiChatWindowOpenAtom);
+  const setActiveChatId = useSetAtom(activeAiChatIdAtom);
+  const setDraft = useSetAtom(aiChatDraftAtom);
+
+  const clickable = !!aiChatId;
+
+  const openChat = useCallback(
+    (event: React.SyntheticEvent) => {
+      event.stopPropagation();
+      if (!aiChatId) return;
+      setActiveChatId(aiChatId);
+      // Switching chats must start with a clean composer — clear any unsent draft
+      // so it does not leak from the previously open chat.
+      setDraft("");
+      setAiChatWindowOpen(true);
+      onActivate?.();
+    },
+    [aiChatId, setActiveChatId, setDraft, setAiChatWindowOpen, onActivate],
+  );
+
+  // Internal chat => "role on behalf of person"; external MCP => just the agent.
+  const tooltip = launcher
+    ? t("AI agent «{{role}}» on behalf of {{person}}", {
+        role: agent.name,
+        person: launcher.name,
+      })
+    : t("AI agent {{name}}", { name: agent.name });
+
+  // The container is only enlarged when there is a launcher to overhang; with no
+  // human behind it stays tight at the agent glyph size.
+  const stackSize = launcher ? GLYPH_SIZE + LAUNCHER_OVERHANG : GLYPH_SIZE;
+
+  const stack = (
+    <Box
+      pos="relative"
+      style={{
+        width: stackSize,
+        height: stackSize,
+        flexShrink: 0,
+        // Center the (in-flow) agent glyph vertically so it lines up with its
+        // name label; the absolutely-positioned launcher is unaffected by flex.
+        display: "flex",
+        alignItems: "center",
+        cursor: clickable ? "pointer" : undefined,
+      }}
+      {...(clickable
+        ? {
+            role: "button",
+            tabIndex: 0,
+            onClick: openChat,
+            onKeyDown: (event: React.KeyboardEvent) => {
+              if (event.key === "Enter" || event.key === " ") {
+                event.preventDefault();
+                openChat(event);
+              }
+            },
+          }
+        : {})}
+    >
+      {launcher && (
+        // Launcher badge sits ABOVE the agent glyph (zIndex) at the top-right so
+        // it is fully visible, not half-hidden behind the agent circle.
+        <Box pos="absolute" top={0} right={0} style={{ zIndex: 2 }}>
+          <CustomAvatar
+            size={LAUNCHER_SIZE}
+            avatarUrl={launcher.avatarUrl}
+            name={launcher.name}
+            style={{ border: "2px solid var(--mantine-color-body)" }}
+          />
+        </Box>
+      )}
+      {/* The agent glyph keeps its own size (flex-centered in the container); the
+          launcher overhangs it by LAUNCHER_OVERHANG at the top-right and stays visible. */}
+      <Box
+        style={{
+          position: "relative",
+          zIndex: 1,
+          width: GLYPH_SIZE,
+          height: GLYPH_SIZE,
+        }}
+      >
+        <AgentGlyph agent={agent} />
+      </Box>
+    </Box>
+  );
+
+  return (
+    <Group gap={6} wrap="nowrap" style={{ minWidth: 0 }}>
+      <Tooltip label={tooltip} withArrow>
+        {stack}
+      </Tooltip>
+      {showName && (
+        <Group gap={4} wrap="nowrap" style={{ minWidth: 0 }}>
+          <Text size="xs" fw={600} lineClamp={1} lh={1.2}>
+            {agent.name}
+          </Text>
+          {launcher && (
+            <>
+              <Text size="xs" c="dimmed" fw={400} aria-hidden>
+                ·
+              </Text>
+              <Text size="xs" c="dimmed" fw={400} lineClamp={1} lh={1.2}>
+                {launcher.name}
+              </Text>
+            </>
+          )}
+        </Group>
+      )}
+    </Group>
+  );
+}
+
+export default AgentAvatarStack;

apps/client/src/components/ui/ai-agent-badge.test.tsx

@@ -1,96 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { render, screen, fireEvent } from "@testing-library/react";
-import { MantineProvider } from "@mantine/core";
-import { Provider, createStore } from "jotai";
-import { AiAgentBadge } from "./ai-agent-badge";
-import {
-  activeAiChatIdAtom,
-  aiChatWindowOpenAtom,
-  aiChatDraftAtom,
-} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
-
-// matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
-
-function renderBadge(props: { authorName?: string; aiChatId?: string | null }) {
-  return render(
-    <MantineProvider>
-      <AiAgentBadge {...props} />
-    </MantineProvider>,
-  );
-}
-
-// Render a clickable badge inside an explicit jotai store, with a leftover draft
-// and an onActivate + parent-click spy, so the deep-link side effects are
-// assertable. Returns the store and spies.
-function setupClickable() {
-  const store = createStore();
-  store.set(aiChatDraftAtom, "leftover draft from another chat");
-  const onActivate = vi.fn();
-  const onParentClick = vi.fn();
-  render(
-    <Provider store={store}>
-      <MantineProvider>
-        <div onClick={onParentClick}>
-          <AiAgentBadge authorName="Bot" aiChatId="chat-1" onActivate={onActivate} />
-        </div>
-      </MantineProvider>
-    </Provider>,
-  );
-  return { store, onActivate, onParentClick, badge: screen.getByRole("button") };
-}
-
-function expectDeepLinked(store: ReturnType<typeof createStore>, onActivate: ReturnType<typeof vi.fn>) {
-  expect(store.get(activeAiChatIdAtom)).toBe("chat-1");
-  expect(store.get(aiChatWindowOpenAtom)).toBe(true);
-  expect(store.get(aiChatDraftAtom)).toBe(""); // draft cleared
-  expect(onActivate).toHaveBeenCalledTimes(1); // caller closes its own modal etc.
-}
-
-describe("AiAgentBadge", () => {
-  it("renders the AI-agent label", () => {
-    renderBadge({ authorName: "Bot" });
-    expect(screen.getByText("AI-agent")).toBeDefined();
-  });
-
-  it("is clickable (accessible button) when aiChatId is present", () => {
-    renderBadge({ authorName: "Bot", aiChatId: "chat-1" });
-    const badge = screen.getByRole("button");
-    expect(badge).toBeDefined();
-    expect(badge.textContent).toContain("AI-agent");
-  });
-
-  it("click deep-links: sets active chat, clears draft, opens window, fires onActivate, stops propagation", () => {
-    const { store, onActivate, onParentClick, badge } = setupClickable();
-    fireEvent.click(badge);
-    expectDeepLinked(store, onActivate);
-    expect(onParentClick).not.toHaveBeenCalled(); // stopPropagation contained the click
-  });
-
-  it.each(["Enter", " "])(
-    "keyboard %j activates the deep-link (same side effects as click)",
-    (key) => {
-      const { store, onActivate, badge } = setupClickable();
-      fireEvent.keyDown(badge, { key });
-      expectDeepLinked(store, onActivate);
-    },
-  );
-
-  it("an unrelated key does NOT activate the badge", () => {
-    const { store, onActivate, badge } = setupClickable();
-    fireEvent.keyDown(badge, { key: "Tab" });
-    expect(store.get(activeAiChatIdAtom)).toBeNull();
-    expect(store.get(aiChatWindowOpenAtom)).toBe(false);
-    expect(store.get(aiChatDraftAtom)).toBe("leftover draft from another chat");
-    expect(onActivate).not.toHaveBeenCalled();
-  });
-
-  it.each([{ aiChatId: null }, {}])(
-    "is a plain non-clickable label without a chat target (%o)",
-    (props) => {
-      renderBadge({ authorName: "Bot", ...props });
-      expect(screen.getByText("AI-agent")).toBeDefined();
-      // No interactive role is exposed when there is no chat to deep-link into.
-      expect(screen.queryByRole("button")).toBeNull();
-    },
-  );
-});

apps/client/src/components/ui/ai-agent-badge.tsx

@@ -1,99 +0,0 @@
-import { Badge, Tooltip } from "@mantine/core";
-import { IconSparkles } from "@tabler/icons-react";
-import { useCallback } from "react";
-import { useTranslation } from "react-i18next";
-import { useSetAtom } from "jotai";
-import {
-  activeAiChatIdAtom,
-  aiChatWindowOpenAtom,
-  aiChatDraftAtom,
-} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
-
-interface AiAgentBadgeProps {
-  authorName?: string;
-  aiChatId?: string | null;
-  // Fired after the badge deep-links into its chat. The caller handles its own
-  // context (e.g. the page-history row closes the history modal) so this generic
-  // ui/ primitive stays free of cross-feature coupling (#143 review Arch B).
-  onActivate?: () => void;
-}
-
-/**
- * Badge marking content written by the AI agent (provenance C3 / §7.4). It is
- * ADDITIVE — shown next to the human author, never replacing them. Reused by the
- * page-history list and the comments sidebar.
- *
- * When the item carries an `aiChatId` (an internal AI-chat edit), clicking the
- * badge deep-links into that chat: it sets the active-chat atom and opens the
- * floating AI-chat window, then invokes `onActivate` so the caller can react
- * (e.g. the history modal closes itself). When `aiChatId` is null/absent (an
- * external MCP write with no internal ai_chats row), the badge is a plain
- * non-clickable label. The click is contained (stopPropagation) so it does not
- * also trigger an enclosing row's click handler.
- */
-export function AiAgentBadge({
-  authorName,
-  aiChatId,
-  onActivate,
-}: AiAgentBadgeProps) {
-  const { t } = useTranslation();
-  const setAiChatWindowOpen = useSetAtom(aiChatWindowOpenAtom);
-  const setActiveChatId = useSetAtom(activeAiChatIdAtom);
-  const setDraft = useSetAtom(aiChatDraftAtom);
-
-  const tooltip = t("Edited by AI agent on behalf of {{name}}", {
-    name: authorName ?? "",
-  });
-
-  const openChat = useCallback(
-    (event: React.SyntheticEvent) => {
-      event.stopPropagation();
-      if (!aiChatId) return;
-      setActiveChatId(aiChatId);
-      // Switching to another chat must start with a clean composer — clear any
-      // unsent draft so it does not leak from the previously open chat.
-      setDraft("");
-      setAiChatWindowOpen(true);
-      onActivate?.();
-    },
-    [aiChatId, setActiveChatId, setDraft, setAiChatWindowOpen, onActivate],
-  );
-
-  const badge = (
-    <Badge
-      size="sm"
-      variant="light"
-      color="violet"
-      radius="sm"
-      leftSection={<IconSparkles size={12} stroke={2} />}
-      style={aiChatId ? { cursor: "pointer" } : undefined}
-      {...(aiChatId
-        ? {
-            // Keep the default Badge root element (not a <button>) to avoid an
-            // invalid <button>-in-<button> nesting inside a row's
-            // UnstyledButton; expose it as an accessible button via
-            // role/keyboard.
-            role: "button",
-            tabIndex: 0,
-            onClick: openChat,
-            onKeyDown: (event: React.KeyboardEvent) => {
-              if (event.key === "Enter" || event.key === " ") {
-                event.preventDefault();
-                openChat(event);
-              }
-            },
-          }
-        : {})}
-    >
-      {t("AI-agent")}
-    </Badge>
-  );
-
-  return (
-    <Tooltip label={tooltip} withArrow>
-      {badge}
-    </Tooltip>
-  );
-}
-
-export default AiAgentBadge;

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

@@ -164,8 +164,8 @@
     /* NOTE: `white-space: pre-wrap` is intentionally NOT set here. On the
        rendered markdown <div> it would turn the newlines between block tags
        (</li>\n<li>, </p>\n<ol>) into visible blank lines/indents on top of the
-       margins. The plain-text fallback <Text> that needs pre-wrap sets it
-       inline itself (see reasoning-block.tsx). */
+       margins. The streaming plain-text path that needs pre-wrap sets it
+       per chunk instead, in PlainChunk (see streaming-plain-text.tsx). */
 }
 
 .reasoningText p {

apps/client/src/features/ai-chat/components/message-item.test.ts

@@ -65,6 +65,25 @@ describe("arePropsEqual", () => {
     expect(arePropsEqual(props(m), props(m))).toBe(true);
   });
 
+  // REGRESSION (stranded reasoning part): a reasoning part is left at
+  // `state:"streaming"` forever when the turn ends without `reasoning-end`
+  // (manual Stop during thinking). The signature is EQUAL across that turn-end
+  // flip (nothing in the message changed), so the comparator must ALSO compare
+  // `turnStreaming` — otherwise the memo swallows the flip and ReasoningBlock
+  // never switches from chunked plain text to its one-time markdown parse.
+  it("returns false when turnStreaming differs despite an equal signature", () => {
+    const m = msg([
+      { type: "reasoning", text: "thinking", state: "streaming" },
+      { type: "text", text: "answer" },
+    ]);
+    expect(
+      arePropsEqual(
+        props(m, { turnStreaming: true }),
+        props(m, { turnStreaming: false }),
+      ),
+    ).toBe(false);
+  });
+
   it("returns true for the same content in a different message object", () => {
     const a = msg([{ type: "text", text: "answer" }]);
     const b = msg([{ type: "text", text: "answer" }]);

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

@@ -52,6 +52,20 @@ interface MessageItemProps {
    * absent; the public share passes the configured identity (agent role) name.
    */
   assistantName?: string;
+  /**
+   * Whether the WHOLE turn is still streaming (MessageList's `isStreaming`).
+   * A reasoning part may be left `state: "streaming"` forever when the turn
+   * ends without a `reasoning-end` chunk (manual Stop during the thinking
+   * phase, or a provider that never emits it) — the AI SDK finalizes reasoning
+   * state ONLY on `reasoning-end`, not on `finish-step`/`finish`. So part-level
+   * state alone cannot prove liveness; the reasoning part is treated as live
+   * only while the whole turn is still streaming. Defaults to false.
+   *
+   * The parent passes it as "turn is live AND this is the tail row", so a
+   * stranded part in an EARLIER row never re-activates when a later turn
+   * streams.
+   */
+  turnStreaming?: boolean;
 }
 
 /**
@@ -105,6 +119,7 @@ function MessageItem({
   showCitations = true,
   neutralizeInternalLinks = false,
   assistantName,
+  turnStreaming = false,
 }: MessageItemProps) {
   // `signature` is intentionally not read in the body — it exists solely as the
   // memo key (see arePropsEqual). The render reads `message` directly.
@@ -155,8 +170,23 @@ function MessageItem({
           const text = (part as { text?: string }).text ?? "";
           if (!text.trim() && !(reasoningTokens && reasoningTokens > 0))
             return null;
+          // Absent state (persisted rows) and "done" both mean finalized.
+          // `messageSignature` already includes each part's `state`, so the
+          // streaming→done flip changes the row signature and re-renders this
+          // row — which is what lets ReasoningBlock switch from chunked plain
+          // text to its one-time markdown parse (see reasoning-block.tsx).
+          // ALSO require the turn to be live: a part stranded at
+          // `state:"streaming"` after the turn ended (no `reasoning-end` — see
+          // the `turnStreaming` prop doc) must still finalize and parse.
+          const streaming =
+            turnStreaming && (part as { state?: string }).state === "streaming";
           return (
-            <ReasoningBlock key={index} text={text} tokens={reasoningTokens} />
+            <ReasoningBlock
+              key={index}
+              text={text}
+              tokens={reasoningTokens}
+              streaming={streaming}
+            />
           );
         }
 
@@ -245,7 +275,11 @@ export function arePropsEqual(
     prev.signature === next.signature &&
     prev.showCitations === next.showCitations &&
     prev.neutralizeInternalLinks === next.neutralizeInternalLinks &&
-    prev.assistantName === next.assistantName
+    prev.assistantName === next.assistantName &&
+    // The turn-end flip re-renders every row once (cheap, terminal event) —
+    // that is what converts a stranded `state:"streaming"` reasoning part to
+    // its one-time markdown parse (see the `turnStreaming` prop doc).
+    prev.turnStreaming === next.turnStreaming
   );
 }
 

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

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import { render } from "@testing-library/react";
+import { fireEvent, render } from "@testing-library/react";
 import { MantineProvider } from "@mantine/core";
 import type { UIMessage } from "@ai-sdk/react";
 
@@ -50,8 +50,9 @@ vi.stubGlobal(
 
 // One assistant message wrapping the given `parts`. Reused across renders in the
 // regression test to model how the AI SDK hands back the SAME message object.
-const msg = (parts: UIMessage["parts"]): UIMessage =>
-  ({ id: "m1", role: "assistant", parts }) as UIMessage;
+// Pass an explicit `id` when a test renders several rows at once.
+const msg = (parts: UIMessage["parts"], id = "m1"): UIMessage =>
+  ({ id, role: "assistant", parts }) as UIMessage;
 
 describe("MessageList", () => {
   it("wires the real MessageItem and supplies a valid signature end-to-end", () => {
@@ -116,4 +117,102 @@ describe("MessageList", () => {
       renderChatMarkdownSpy.mock.calls.some((c) => c[0] === "streamed answer"),
     ).toBe(true);
   });
+
+  // REGRESSION (stranded reasoning part): the AI SDK sets a reasoning part's
+  // state to "done" ONLY on the `reasoning-end` chunk — `finish-step`/`finish`
+  // do NOT finalize it. A manual Stop during the thinking phase (or a provider
+  // that never emits `reasoning-end`) therefore leaves the part at
+  // `state:"streaming"` forever. MessageItem must derive ReasoningBlock's
+  // `streaming` from part state AND turn liveness (MessageList's `isStreaming`,
+  // forwarded as `turnStreaming`): while the turn streams the expanded block
+  // shows chunked plain text (no parse); once the turn ends — even though the
+  // part is still `state:"streaming"` — the block finalizes and does its
+  // one-time markdown parse. Note the message signature does NOT change across
+  // that flip, so this also exercises the `turnStreaming` memo comparison in
+  // arePropsEqual (without it the row would never re-render).
+  it("finalizes a reasoning part stranded at state:'streaming' when the turn ends", () => {
+    renderChatMarkdownSpy.mockClear();
+    const reasoningText = "**bold** thinking";
+    // Reasoning part stranded mid-stream + a non-empty answer part (a
+    // reasoning-only message renders nothing — see message-content.ts).
+    const message = msg([
+      { type: "reasoning", text: reasoningText, state: "streaming" },
+      { type: "text", text: "partial answer" },
+    ]);
+    const parsesOfReasoning = () =>
+      renderChatMarkdownSpy.mock.calls.filter((c) => c[0] === reasoningText)
+        .length;
+
+    const { rerender, getByRole, queryByText } = render(
+      <MantineProvider>
+        <MessageList messages={[message]} isStreaming />
+      </MantineProvider>,
+    );
+    // Expand the reasoning block (its toggle is the only button in the list).
+    fireEvent.click(getByRole("button"));
+    // Turn live + part streaming -> ReasoningBlock received streaming=true:
+    // the body is chunked plain text (raw markdown syntax), NOT parsed.
+    expect(queryByText(/bold/)).not.toBeNull();
+    expect(parsesOfReasoning()).toBe(0);
+
+    // The turn ends WITHOUT `reasoning-end`: the part object is untouched
+    // (still state:"streaming"), only the turn-level flag flips.
+    rerender(
+      <MantineProvider>
+        <MessageList messages={[message]} isStreaming={false} />
+      </MantineProvider>,
+    );
+    // ReasoningBlock now received streaming=false and did its one-time parse.
+    expect(parsesOfReasoning()).toBe(1);
+  });
+
+  // REGRESSION (turn-global liveness leaking into earlier rows): `isStreaming`
+  // is turn-global, so forwarding it to EVERY row would re-mark a reasoning
+  // part stranded at `state:"streaming"` in a PREVIOUS message (see the test
+  // above) as live again whenever a LATER turn streams — an expanded stranded
+  // block would flip markdown -> raw plain text -> markdown across turn
+  // boundaries, re-parsing each time. MessageList must gate `turnStreaming`
+  // to the TAIL row only.
+  it("keeps a stranded reasoning part in an earlier message finalized while a later turn streams", () => {
+    renderChatMarkdownSpy.mockClear();
+    const reasoningText = "**bold** thinking";
+    // First (earlier) assistant message: its turn was stopped during the
+    // thinking phase, leaving the reasoning part at state:"streaming".
+    const first = msg(
+      [
+        { type: "reasoning", text: reasoningText, state: "streaming" },
+        { type: "text", text: "first answer" },
+      ],
+      "m1",
+    );
+    // Second assistant message: the LATER turn, currently streaming.
+    const second = msg([{ type: "text", text: "second answer" }], "m2");
+    const parsesOfReasoning = () =>
+      renderChatMarkdownSpy.mock.calls.filter((c) => c[0] === reasoningText)
+        .length;
+
+    const { rerender, getByRole, queryByText } = render(
+      <MantineProvider>
+        <MessageList messages={[first, second]} isStreaming />
+      </MantineProvider>,
+    );
+    // Expand the first row's reasoning block (the only toggle in the list —
+    // the second message has no reasoning or tool parts).
+    fireEvent.click(getByRole("button"));
+    // The turn is live but the first row is NOT the tail: its ReasoningBlock
+    // received streaming=false, so the stranded part stays finalized and does
+    // its one-time markdown parse instead of dropping to chunked plain text.
+    expect(queryByText(/bold/)).not.toBeNull();
+    expect(parsesOfReasoning()).toBe(1);
+
+    // A later-turn delta re-renders the list; the earlier block must neither
+    // flip back to streaming nor re-parse.
+    (second.parts[0] as { text: string }).text = "second answer grows";
+    rerender(
+      <MantineProvider>
+        <MessageList messages={[first, second]} isStreaming />
+      </MantineProvider>,
+    );
+    expect(parsesOfReasoning()).toBe(1);
+  });
 });

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

@@ -196,7 +196,7 @@ export default function MessageList({
   return (
     <ScrollArea className={classes.messages} viewportRef={viewportRef} scrollbarSize={6} type="scroll">
       <Stack gap={0} pr="xs">
-        {messages.map((message) => (
+        {messages.map((message, index) => (
           // `signature` is snapshotted HERE (parent render) into an immutable
           // string and handed to MessageItem as its memo key. It must NOT be
           // recomputed inside MessageItem's arePropsEqual: the AI SDK mutates the
@@ -210,6 +210,13 @@ export default function MessageList({
             showCitations={showCitations}
             neutralizeInternalLinks={neutralizeInternalLinks}
             assistantName={assistantName}
+            // Turn-level liveness, gated to the TAIL row: only the tail message
+            // can belong to the in-flight turn, so a reasoning part stranded at
+            // `state:"streaming"` in an EARLIER message (its turn ended without
+            // `reasoning-end`) stays finalized and doesn't flip back to plain
+            // text (and re-parse) whenever a later turn streams — see
+            // message-item.tsx.
+            turnStreaming={isStreaming && index === messages.length - 1}
           />
         ))}
         {typing && (

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

@@ -1,7 +1,14 @@
 import { describe, it, expect, vi } from "vitest";
-import { render, screen } from "@testing-library/react";
+import { render, screen, fireEvent } from "@testing-library/react";
 import { MantineProvider } from "@mantine/core";
 
+// Spy on the markdown renderer so we can assert it is NOT called while the block
+// is collapsed (the #302 fix) and IS called once on expand. The count/fallback
+// tests don't depend on real markdown, so a light stub is safe.
+vi.mock("@/features/ai-chat/utils/markdown.ts", () => ({
+  renderChatMarkdown: vi.fn((md: string) => `<p>${md}</p>`),
+}));
+
 // Stub react-i18next so `t` returns the key with `{{count}}` interpolated. This
 // keeps the assertions on the component's OWN count logic (authoritative vs
 // estimate) rather than on translation, and mirrors the t-mock pattern used by
@@ -17,10 +24,15 @@ vi.mock("react-i18next", () => ({
 
 import ReasoningBlock from "./reasoning-block";
 import { estimateTokens } from "@/features/ai-chat/utils/count-stream-tokens.ts";
+import { renderChatMarkdown } from "@/features/ai-chat/utils/markdown.ts";
 
 // matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
 
-function renderBlock(props: { text: string; tokens?: number }) {
+function renderBlock(props: {
+  text: string;
+  tokens?: number;
+  streaming?: boolean;
+}) {
   return render(
     <MantineProvider>
       <ReasoningBlock {...props} />
@@ -62,4 +74,68 @@ describe("ReasoningBlock", () => {
     // either way the text is present in the document.
     expect(screen.getByText(/reasoning/)).toBeDefined();
   });
+
+  it("does not parse the reasoning markdown while collapsed; parses on expand (#302)", () => {
+    const renderSpy = vi.mocked(renderChatMarkdown);
+    renderSpy.mockClear();
+    renderBlock({ text: "**bold** reasoning", tokens: 5 });
+    // Collapsed is the default. The expensive markdown parse (marked + DOMPurify)
+    // must NOT run for the hidden body — that O(n^2) re-parse on every streamed
+    // delta is exactly what froze the chat (#302). The collapsed body shows the
+    // cheap raw-text fallback instead.
+    expect(renderSpy).not.toHaveBeenCalled();
+    // Expanding parses the current text exactly once (a user-initiated click).
+    fireEvent.click(screen.getByRole("button"));
+    expect(renderSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not parse while expanded and STREAMING; shows chunked plain text", () => {
+    const renderSpy = vi.mocked(renderChatMarkdown);
+    renderSpy.mockClear();
+    renderBlock({
+      text: "первый абзац размышлений\n\nвторой абзац растёт",
+      tokens: 5,
+      streaming: true,
+    });
+    fireEvent.click(screen.getByRole("button"));
+    // Expanded + still streaming: NO markdown parse and NO innerHTML swaps per
+    // delta — the body is chunked plain text (only the tail chunk updates).
+    // This is the O(n²) hole #302 left open (Safari whole-tab freeze).
+    expect(renderSpy).not.toHaveBeenCalled();
+    // Both paragraph chunks' raw text is present in the body.
+    expect(screen.getByText(/первый абзац размышлений/)).toBeDefined();
+    expect(screen.getByText(/второй абзац растёт/)).toBeDefined();
+  });
+
+  it("parses exactly once when streaming flips to done while expanded", () => {
+    const renderSpy = vi.mocked(renderChatMarkdown);
+    renderSpy.mockClear();
+    const { rerender } = renderBlock({
+      text: "**bold** reasoning",
+      tokens: 5,
+      streaming: true,
+    });
+    fireEvent.click(screen.getByRole("button"));
+    expect(renderSpy).not.toHaveBeenCalled();
+
+    // Finalization: the part's state flips streaming→done, the parent
+    // re-renders the row (the flip changes the message signature), and the
+    // block does its ONE markdown parse of the now-stable text.
+    rerender(
+      <MantineProvider>
+        <ReasoningBlock text="**bold** reasoning" tokens={5} streaming={false} />
+      </MantineProvider>,
+    );
+    expect(renderSpy).toHaveBeenCalledTimes(1);
+    // The parsed html branch rendered (the mock wraps the input in <p>…</p>).
+    expect(screen.getByText(/reasoning/)).toBeDefined();
+
+    // Further re-renders with unchanged props do not re-parse.
+    rerender(
+      <MantineProvider>
+        <ReasoningBlock text="**bold** reasoning" tokens={5} streaming={false} />
+      </MantineProvider>,
+    );
+    expect(renderSpy).toHaveBeenCalledTimes(1);
+  });
 });

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

@@ -5,6 +5,7 @@ import { useTranslation } from "react-i18next";
 import { estimateTokens } from "@/features/ai-chat/utils/count-stream-tokens.ts";
 import { collapseBlankLines } from "@/features/ai-chat/utils/collapse-blank-lines.ts";
 import { renderChatMarkdown } from "@/features/ai-chat/utils/markdown.ts";
+import { StreamingPlainText } from "@/features/ai-chat/components/streaming-plain-text.tsx";
 import classes from "@/features/ai-chat/components/ai-chat.module.css";
 
 interface ReasoningBlockProps {
@@ -15,6 +16,10 @@ interface ReasoningBlockProps {
    *  step/turn has finished. When absent (or 0) the count is estimated from the
    *  text length so it ticks live as the reasoning streams in. */
   tokens?: number;
+  /** True while the reasoning part is still streaming (part `state ===
+   *  "streaming"`). False means finalized: persisted history or `state ===
+   *  "done"`. Gates the markdown parse — see the invariant on the memo below. */
+  streaming?: boolean;
 }
 
 /**
@@ -27,22 +32,30 @@ interface ReasoningBlockProps {
  * Providers that don't stream reasoning TEXT still render this block from the
  * authoritative count alone (header only, empty body) so the cost is visible.
  */
-function ReasoningBlock({ text, tokens }: ReasoningBlockProps) {
+function ReasoningBlock({ text, tokens, streaming = false }: ReasoningBlockProps) {
   const { t } = useTranslation();
   const [open, setOpen] = useState(false);
 
   // Authoritative count wins; otherwise estimate live from the streamed text.
   const count = tokens && tokens > 0 ? tokens : estimateTokens(text);
   const trimmed = text.trim();
-  // Memoize the markdown render so toggling `open` (or a parent re-render caused
-  // by an unrelated streamed delta) does not re-parse the reasoning text; it
-  // recomputes only when the reasoning text itself changes (while it streams in).
-  // collapseBlankLines collapses the blank-line gaps the model emits between every
-  // list item / paragraph so the reasoning renders compactly (tight lists, joined
-  // paragraphs) — ONLY here, not in the normal answer.
+  // Markdown parse invariant (per throttled ~20Hz stream delta the text GROWS):
+  //  1. Collapsed -> never parse (#302): the html is only shown inside
+  //     <Collapse in={open}>, so parsing for a hidden body would be an O(n²)
+  //     marked + DOMPurify storm.
+  //  2. Expanded + STREAMING -> no parse and no innerHTML swaps either: the body
+  //     renders as chunked plain text (StreamingPlainText) with a memoized
+  //     stable prefix, so each delta updates only the tail chunk's text node.
+  //     This closes the O(n²) hole #302 left open ("expanded while streaming")
+  //     that froze the whole tab in Safari when watching the thinking stream.
+  //  3. Finalized + expanded -> exactly one parse: `trimmed` and `streaming`
+  //     are stable after the part is done, so this memo runs once per expand.
   const html = useMemo(
-    () => (trimmed ? renderChatMarkdown(collapseBlankLines(trimmed), {}) : ""),
-    [trimmed],
+    () =>
+      open && trimmed && !streaming
+        ? renderChatMarkdown(collapseBlankLines(trimmed), {})
+        : "",
+    [open, trimmed, streaming],
   );
 
   return (
@@ -79,12 +92,12 @@ function ReasoningBlock({ text, tokens }: ReasoningBlockProps) {
               dangerouslySetInnerHTML={{ __html: html }}
             />
           ) : (
-            <Text
-              className={classes.reasoningText}
-              style={{ whiteSpace: "pre-wrap" }}
-            >
-              {trimmed}
-            </Text>
+            // Still streaming (or markdown yielded nothing): chunked plain text.
+            // The wrapper carries the reasoningText styling; each chunk sets its
+            // own pre-wrap inline (NOT on this div — see ai-chat.module.css).
+            <div className={classes.reasoningText}>
+              <StreamingPlainText text={trimmed} />
+            </div>
           )}
         </Collapse>
       )}
@@ -92,7 +105,7 @@ function ReasoningBlock({ text, tokens }: ReasoningBlockProps) {
   );
 }
 
-// Memoized: re-renders only when `text`/`tokens` change (primitive props, default
-// shallow compare), so a parent re-render during streaming of OTHER content does
-// not re-run the markdown parse for an already-finalized reasoning block.
+// Memoized: re-renders only when `text`/`tokens`/`streaming` change (primitive
+// props, default shallow compare), so a parent re-render during streaming of OTHER
+// content does not re-run the markdown parse for an already-finalized reasoning block.
 export default memo(ReasoningBlock);

apps/client/src/features/ai-chat/components/streaming-plain-text.test.tsx

@@ -0,0 +1,146 @@
+import { describe, it, expect } from "vitest";
+import { render } from "@testing-library/react";
+
+import {
+  splitPlainChunks,
+  StreamingPlainText,
+} from "./streaming-plain-text";
+
+describe("splitPlainChunks", () => {
+  // THE load-bearing property (see the invariant comment in the module): under
+  // append-only growth, every chunk except the LAST must be byte-identical
+  // between successive calls, so the memoized chunk components never re-render
+  // for the stable prefix and each stream delta touches only the tail chunk.
+  it("keeps all non-last chunks byte-identical across append-only growth", () => {
+    // A simulated reasoning stream covering: appends inside the last paragraph,
+    // appends that ADD new blank lines, growth of a trailing newline run, and a
+    // trailing separator later followed by text.
+    const steps = [
+      "Пер",
+      "Первый абзац",
+      "Первый абзац\n",
+      "Первый абзац\n\n",
+      "Первый абзац\n\n\n",
+      "Первый абзац\n\n\nВторой",
+      "Первый абзац\n\n\nВторой абзац растёт",
+      "Первый абзац\n\n\nВторой абзац растёт\n\nТретий",
+      "Первый абзац\n\n\nВторой абзац растёт\n\nТретий абзац\n\n",
+      "Первый абзац\n\n\nВторой абзац растёт\n\nТретий абзац\n\nЧетвёртый",
+    ];
+    let prev: string[] = [];
+    for (const text of steps) {
+      const next = splitPlainChunks(text);
+      // Lossless: chunks always reassemble into the exact input.
+      expect(next.join("")).toBe(text);
+      // Chunk count never shrinks (boundaries never disappear).
+      expect(next.length).toBeGreaterThanOrEqual(prev.length);
+      // Every previously-FINAL chunk (all but prev's last) is unchanged.
+      for (let i = 0; i < prev.length - 1; i++) {
+        expect(next[i]).toBe(prev[i]);
+      }
+      prev = next;
+    }
+    // Guard against a vacuous pass: the final split must be multi-chunk.
+    expect(prev.length).toBeGreaterThanOrEqual(4);
+  });
+
+  it("attaches the blank-line separator run to the preceding chunk", () => {
+    expect(splitPlainChunks("a\n\nb")).toEqual(["a\n\n", "b"]);
+    // A longer run is ONE separator, not several boundaries.
+    expect(splitPlainChunks("a\n\n\n\nb")).toEqual(["a\n\n\n\n", "b"]);
+    expect(splitPlainChunks("a\n\nb\n\n\nc")).toEqual(["a\n\n", "b\n\n\n", "c"]);
+  });
+
+  it("single newlines are not boundaries", () => {
+    expect(splitPlainChunks("a\nb\nc")).toEqual(["a\nb\nc"]);
+  });
+
+  // INTENTIONAL: CRLF blank lines are NOT boundaries (the regex is `\n{2,}`
+  // only). Supporting `(?:\r?\n){2,}` would break the stable-prefix invariant:
+  // a lone trailing `\r` is not a boundary, but a later-appended `\n` would
+  // merge with it into a new separator unit and retroactively create a boundary
+  // INSIDE previously-emitted text, moving old chunk edges. So CRLF input stays
+  // in one (still lossless) chunk — only granularity is coarser; LLM output is
+  // `\n` in practice. See the doc comment on splitPlainChunks.
+  it("keeps CRLF blank lines inside one chunk", () => {
+    expect(splitPlainChunks("a\r\n\r\nb")).toEqual(["a\r\n\r\nb"]);
+    // Mixed input: only pure-`\n` runs split.
+    expect(splitPlainChunks("a\r\n\r\nb\n\nc")).toEqual(["a\r\n\r\nb\n\n", "c"]);
+  });
+
+  it("never emits empty phantom chunks (multi-blank-line / trailing newlines)", () => {
+    expect(splitPlainChunks("")).toEqual([]);
+    // A trailing newline run stays inside the last chunk (it may still grow).
+    expect(splitPlainChunks("a\n")).toEqual(["a\n"]);
+    expect(splitPlainChunks("a\n\n")).toEqual(["a\n\n"]);
+    expect(splitPlainChunks("a\n\nb\n\n")).toEqual(["a\n\n", "b\n\n"]);
+    // Degenerate all-newlines input is a single deterministic chunk.
+    expect(splitPlainChunks("\n\n\n")).toEqual(["\n\n\n"]);
+    for (const text of ["a\n\n\nb\n\n", "x\n\n\n\n\ny\n\nz\n"]) {
+      for (const chunk of splitPlainChunks(text)) {
+        expect(chunk.length).toBeGreaterThan(0);
+      }
+    }
+  });
+});
+
+describe("StreamingPlainText", () => {
+  it("renders one block per chunk, stripping trailing separator newlines at display time", () => {
+    const text = "первый абзац\n\nвторой абзац\n\n\nтретий";
+    const { container } = render(<StreamingPlainText text={text} />);
+    const blocks = Array.from(container.querySelectorAll("div"));
+    // One block element per chunk.
+    expect(blocks.length).toBe(splitPlainChunks(text).length);
+    // DISPLAY-ONLY strip: each rendered block drops its chunk's trailing
+    // separator newlines — rendering them inside a pre-wrap block would add an
+    // empty line ON TOP of the block break (a doubled gap). The RAW chunks
+    // keep their separators (losslessness is asserted on splitPlainChunks
+    // above); multi-blank-line runs collapse to one uniform gap, consistent
+    // with collapseBlankLines on the finalized markdown path.
+    expect(blocks.map((b) => b.textContent)).toEqual([
+      "первый абзац",
+      "второй абзац",
+      "третий",
+    ]);
+    // The uniform paragraph gap comes from the block margin instead (matches
+    // the `.reasoningText p { margin: 0 0 4px }` rhythm of the markdown path).
+    for (const block of blocks) {
+      expect((block as HTMLElement).style.marginBottom).toBe("4px");
+    }
+  });
+
+  it("keeps interior newlines intact — only the trailing run is stripped", () => {
+    const text = "строка один\nстрока два\n\nхвост";
+    const { container } = render(<StreamingPlainText text={text} />);
+    const blocks = Array.from(container.querySelectorAll("div"));
+    expect(blocks.map((b) => b.textContent)).toEqual([
+      "строка один\nстрока два",
+      "хвост",
+    ]);
+  });
+
+  // SECURITY INVARIANT — the load-bearing property of the streaming path: the
+  // reasoning text is raw, untrusted model output rendered WITHOUT a sanitizer
+  // (no marked/DOMPurify, no innerHTML). PlainChunk emits it as a React text
+  // node, which escapes it, so HTML in the model output is inert. This test
+  // pins that the path is a TEXT sink, not an HTML sink: a future change to
+  // `dangerouslySetInnerHTML` (reintroducing XSS) MUST fail here.
+  //
+  // The existing tests assert via textContent, which strips tags and so cannot
+  // distinguish an escaped literal from injected DOM. This one asserts on the
+  // parsed DOM directly: if the markup were injected as HTML, the <img>/<b>
+  // would become real elements and querySelector would find them.
+  it("renders HTML-like reasoning as an escaped literal, never as injected DOM", () => {
+    const text = "<img src=x onerror=alert(1)>\n\n<b>hi</b>";
+    const { container } = render(<StreamingPlainText text={text} />);
+    // No DOM elements were created from the payload — it was NOT parsed as HTML.
+    expect(container.querySelector("img")).toBeNull();
+    expect(container.querySelector("b")).toBeNull();
+    // The raw markup survived verbatim as text (proving it is escaped, not
+    // interpreted). textContent alone can't prove this, but combined with the
+    // querySelector assertions above it does: the literals are present AND no
+    // elements exist.
+    expect(container.textContent).toContain("<b>hi</b>");
+    expect(container.textContent).toContain("<img src=x onerror=alert(1)>");
+  });
+});

apps/client/src/features/ai-chat/components/streaming-plain-text.tsx

@@ -0,0 +1,90 @@
+import { memo, useMemo } from "react";
+
+/**
+ * Split plain text into chunks at blank-line (paragraph) boundaries, keeping
+ * each separator run attached to the END of the preceding chunk, so the chunks
+ * always reassemble byte-for-byte into the input.
+ *
+ * A boundary is the end of a maximal `\n{2,}` run that is followed by at least
+ * one more character. A newline run that is a SUFFIX of the text is NOT a
+ * boundary yet: under append-only growth it may still gain more newlines, and
+ * cutting there would move the boundary on the next call.
+ *
+ * CRITICAL INVARIANT (load-bearing for StreamingPlainText's memoization): for
+ * APPEND-ONLY growth of `text`, every chunk except the LAST is byte-identical
+ * between successive calls — previously-emitted boundaries never move. Proof
+ * sketch: appending never modifies existing characters, so (a) an existing
+ * boundary's newline run and its following character are untouched and the
+ * boundary persists at the same offset; (b) no NEW boundary can appear strictly
+ * inside the old text, because a `\n{2,}` run followed by a character entirely
+ * within the old text would already have been a boundary. New boundaries can
+ * only materialize at or after the old text's end, i.e. inside the last chunk.
+ *
+ * CRLF is deliberately NOT a boundary: supporting `(?:\r?\n){2,}` would BREAK
+ * the invariant above — a lone trailing `\r` is not a boundary, but a later-
+ * appended `\n` would merge with it into a new separator unit and retroactively
+ * create a boundary INSIDE previously-emitted text, moving old chunk edges.
+ * With `\n`-only runs, appended characters can never extend a run that is
+ * already followed by a non-`\n` character, so old boundaries are immutable.
+ * CRLF blank lines therefore intentionally stay inside one chunk: correctness/
+ * losslessness are unaffected, only chunk granularity for CRLF input (LLM
+ * output is `\n` in practice).
+ */
+export function splitPlainChunks(text: string): string[] {
+  const chunks: string[] = [];
+  let start = 0;
+  for (const match of text.matchAll(/\n{2,}/g)) {
+    const end = match.index + match[0].length;
+    // Suffix run: not a stable boundary yet (see the invariant above).
+    if (end >= text.length) break;
+    chunks.push(text.slice(start, end));
+    start = end;
+  }
+  if (start < text.length) chunks.push(text.slice(start));
+  return chunks;
+}
+
+/**
+ * One immutable chunk. Memoized on its string prop: during streaming only the
+ * TAIL chunk's text changes (see the splitPlainChunks invariant), so React
+ * skips every stable chunk and the per-delta DOM work is a single text-node
+ * update. `pre-wrap` is set per chunk (like the old raw-text fallback did), NOT
+ * on the surrounding markdown-styled container — see the note in
+ * ai-chat.module.css. Font/size/color are inherited from that container.
+ *
+ * DISPLAY-ONLY newline strip: the raw chunk keeps its trailing `\n{2,}`
+ * separator run attached (the splitPlainChunks invariant, load-bearing for the
+ * memo), but rendering those newlines inside a pre-wrap block would add an
+ * empty line ON TOP of the block break — a doubled gap. So the RENDERED string
+ * drops trailing newlines and the paragraph gap comes from `marginBottom: 4`
+ * instead, matching the `.reasoningText p { margin: 0 0 4px }` rhythm of the
+ * finalized markdown. Multi-blank-line runs thus collapse to one uniform gap,
+ * consistent with `collapseBlankLines` on the markdown path. The last chunk
+ * usually has no trailing newlines (strip is a no-op); its margin is harmless.
+ */
+const PlainChunk = memo(function PlainChunk({ text }: { text: string }) {
+  return (
+    <div style={{ whiteSpace: "pre-wrap", marginBottom: 4 }}>
+      {text.replace(/\n+$/, "")}
+    </div>
+  );
+});
+
+/**
+ * Renders still-streaming plain text as a list of paragraph chunks where only
+ * the tail chunk changes per delta. No markdown, no sanitizer, no innerHTML —
+ * this is the cheap streaming-time stand-in for the one-time markdown parse
+ * that happens after the part is finalized (see reasoning-block.tsx).
+ */
+export function StreamingPlainText({ text }: { text: string }) {
+  const chunks = useMemo(() => splitPlainChunks(text), [text]);
+  return (
+    <>
+      {chunks.map((chunk, index) => (
+        // Index keys are stable here: chunks are append-only (the invariant),
+        // so an index never gets a different chunk's content mid-stream.
+        <PlainChunk key={index} text={chunk} />
+      ))}
+    </>
+  );
+}

apps/client/src/features/ai-chat/hooks/use-open-ai-chat.ts

@@ -27,7 +27,9 @@ export function useOpenAiChatForCurrentPage() {
   // AiChatWindow lives in a pathless parent layout route, so useParams() can't
   // see :pageSlug — match the full path against the authenticated page route.
   const match = useMatch("/s/:spaceSlug/p/:pageSlug");
-  const pageId = extractPageSlugId(match?.params?.pageSlug);
+  // A page slugId (10-char nanoid), NOT a uuid; the server resolves it to the
+  // real page uuid (PageRepo.findById accepts slugId or uuid).
+  const slugId = extractPageSlugId(match?.params?.pageSlug);
 
   return useCallback(async () => {
     // Re-clicks while the window is already open (incl. minimized) must NOT
@@ -40,9 +42,9 @@ export function useOpenAiChatForCurrentPage() {
     // connection the first click reads as a hung control until the POST returns.
     setWindowOpen(true);
     let resolved: string | null = activeChatId; // off-a-page: keep current
-    if (pageId) {
+    if (slugId) {
       try {
-        resolved = await getBoundChat(pageId); // null => fresh chat
+        resolved = await getBoundChat(slugId); // null => fresh chat
       } catch {
         resolved = null; // fail-soft: a fresh chat is always a safe fallback
       }
@@ -58,7 +60,7 @@ export function useOpenAiChatForCurrentPage() {
   }, [
     windowOpen,
     activeChatId,
-    pageId,
+    slugId,
     setWindowOpen,
     setActiveChatId,
     setDraft,

apps/client/src/features/ai-chat/services/ai-chat-service.ts

@@ -46,9 +46,11 @@ export async function getAiChatMessages(
  * Resolve the chat bound to a document (the current user's most-recent chat
  * created on that page), or null when there is none. Drives auto-open-on-page.
  */
-export async function getBoundChat(pageId: string): Promise<string | null> {
+export async function getBoundChat(slugId: string): Promise<string | null> {
+  // The `pageId` body field accepts a page slugId or a uuid; the server resolves
+  // it to the real page uuid (the wire key stays `pageId` for the DTO).
   const req = await api.post<{ chatId: string | null }>("/ai-chat/bound-chat", {
-    pageId,
+    pageId: slugId,
   });
   return req.data.chatId;
 }

apps/client/src/features/comment/components/comment-list-item.test.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import { render, screen } from "@testing-library/react";
+import { render, screen, fireEvent } from "@testing-library/react";
 import { MantineProvider } from "@mantine/core";
 import { IComment } from "@/features/comment/types/comment.types";
 
@@ -7,10 +7,15 @@ import { IComment } from "@/features/comment/types/comment.types";
 
 // The comment mutation hooks reach out to react-query/network — stub them so the
 // component renders in isolation. We only assert the AI-badge rendering branch.
+const applyMutateAsync = vi.fn();
 vi.mock("@/features/comment/queries/comment-query", () => ({
   useDeleteCommentMutation: () => ({ mutateAsync: vi.fn() }),
   useResolveCommentMutation: () => ({ mutateAsync: vi.fn() }),
   useUpdateCommentMutation: () => ({ mutateAsync: vi.fn() }),
+  useApplySuggestionMutation: () => ({
+    mutateAsync: applyMutateAsync,
+    isPending: false,
+  }),
 }));
 
 // CommentEditor pulls in the full TipTap editor stack; replace it with a stub.
@@ -19,6 +24,7 @@ vi.mock("@/features/comment/components/comment-editor", () => ({
 }));
 
 import CommentListItem from "./comment-list-item";
+import { canShowApply } from "@/features/comment/utils/suggestion";
 
 const baseComment = (over?: Partial<IComment>): IComment =>
   ({
@@ -32,28 +38,147 @@ const baseComment = (over?: Partial<IComment>): IComment =>
     ...over,
   }) as IComment;
 
-function renderItem(comment: IComment) {
+function renderItem(comment: IComment, canEdit = true) {
   return render(
     <MantineProvider>
-      <CommentListItem comment={comment} pageId="page-1" canComment={true} />
+      <CommentListItem
+        comment={comment}
+        pageId="page-1"
+        canComment={true}
+        canEdit={canEdit}
+      />
     </MantineProvider>,
   );
 }
 
-describe("CommentListItem — AI badge", () => {
-  it('renders the AI-agent badge when createdSource === "agent"', () => {
-    renderItem(baseComment({ createdSource: "agent", aiChatId: null }));
-    expect(screen.getByText("AI-agent")).toBeDefined();
+describe("CommentListItem — agent avatar stack", () => {
+  it('flips the hierarchy for an agent comment: agent primary, launcher shown once', () => {
+    // Internal-chat shape with DISTINCT names so absence-of-duplication is
+    // assertable: creator is the human "Alice", the acting agent is "Researcher".
+    renderItem(
+      baseComment({
+        creator: { id: "user-1", name: "Alice", avatarUrl: null } as any,
+        createdSource: "agent",
+        aiChatId: "chat-1",
+        agent: { name: "Researcher", emoji: "🔬", avatarUrl: null },
+        launcher: { name: "Alice", avatarUrl: null },
+      }),
+    );
+    // The AGENT is the primary label (the flipped hierarchy).
+    expect(screen.getByText("Researcher")).toBeDefined();
+    // The human launcher name shows exactly once — it is no longer duplicated as
+    // a separate creator name (that duplication is the bug this fixes).
+    expect(screen.getAllByText("Alice").length).toBe(1);
+  });
+
+  it('external MCP agent comment (no launcher): shows the agent name, no separator', () => {
+    // aiChatId null => external MCP: the agent IS the account, no human behind.
+    renderItem(
+      baseComment({
+        creator: { id: "bot-1", name: "MCP Bot", avatarUrl: null } as any,
+        createdSource: "agent",
+        aiChatId: null,
+        agent: { name: "MCP Bot", avatarUrl: null },
+        launcher: null,
+      }),
+    );
+    expect(screen.getByText("MCP Bot")).toBeDefined();
+    // No launcher => no dimmed "·" separator in the header.
+    expect(screen.queryByText("·")).toBeNull();
+  });
+
+  it('does NOT render the stack for a normal user comment (createdSource "user")', () => {
+    const { container } = renderItem(baseComment({ createdSource: "user" }));
+    // No agent glyph (sparkles) is present for a plain human comment.
+    expect(container.querySelector(".tabler-icon-sparkles")).toBeNull();
     expect(screen.getByText("Service Bot")).toBeDefined();
   });
 
-  it('does NOT render the badge for a normal user comment (createdSource "user")', () => {
-    renderItem(baseComment({ createdSource: "user" }));
-    expect(screen.queryByText("AI-agent")).toBeNull();
-    expect(screen.getByText("Service Bot")).toBeDefined();
-  });
-
-  // The non-clickable (null aiChatId) branch is a property of AiAgentBadge itself
-  // and is covered in ai-agent-badge.test.tsx; this integration suite only needs
-  // the insertion gate (agent → badge, user → no badge) above (#143 review).
+  // The stack's own behaviors (glyph priority, launcher-behind, deep-link click)
+  // are covered directly in agent-avatar-stack.test.tsx; this integration suite
+  // only guards the insertion gate (agent → stack, user → no stack).
+});
+
+describe("CommentListItem — suggested edit (#315)", () => {
+  const suggestion = (over?: Partial<IComment>): IComment =>
+    baseComment({
+      selection: "old wording here",
+      suggestedText: "new wording here",
+      ...over,
+    });
+
+  it("renders the было→стало diff and an Apply button when canEdit and not applied/resolved", () => {
+    renderItem(suggestion(), true);
+    // Old text appears both as the selection quote and as the struck diff row.
+    expect(screen.getAllByText("old wording here").length).toBeGreaterThan(0);
+    expect(screen.getByText("new wording here")).toBeDefined();
+    // Apply button is present.
+    expect(screen.getByRole("button", { name: "Apply" })).toBeDefined();
+    // No Applied badge yet.
+    expect(screen.queryByText("Applied")).toBeNull();
+  });
+
+  it("hides the Apply button when canEdit is false", () => {
+    renderItem(suggestion(), false);
+    // Diff still renders...
+    expect(screen.getByText("new wording here")).toBeDefined();
+    // ...but no Apply button.
+    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
+  });
+
+  it("shows an Applied badge (no Apply button) once suggestionAppliedAt is set", () => {
+    renderItem(suggestion({ suggestionAppliedAt: new Date() }), true);
+    expect(screen.getByText("Applied")).toBeDefined();
+    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
+  });
+
+  it("hides the Apply button once the thread is resolved", () => {
+    renderItem(suggestion({ resolvedAt: new Date() }), true);
+    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
+  });
+
+  it("calls the apply mutation when the Apply button is clicked", () => {
+    applyMutateAsync.mockClear();
+    renderItem(suggestion(), true);
+    fireEvent.click(screen.getByRole("button", { name: "Apply" }));
+    expect(applyMutateAsync).toHaveBeenCalledWith({
+      commentId: "c-1",
+      pageId: "page-1",
+    });
+  });
+
+  it("does not render the diff block for a reply (child) comment", () => {
+    renderItem(
+      suggestion({ parentCommentId: "c-0" }),
+      true,
+    );
+    expect(screen.queryByText("new wording here")).toBeNull();
+    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
+  });
+});
+
+describe("canShowApply predicate", () => {
+  const c = (over?: Partial<IComment>): IComment =>
+    ({ suggestedText: "x", ...over }) as IComment;
+
+  it("true when suggestion present, editable, not applied/resolved, top-level", () => {
+    expect(canShowApply(c(), true)).toBe(true);
+  });
+  it("false without edit permission", () => {
+    expect(canShowApply(c(), false)).toBe(false);
+  });
+  it("false when no suggestion", () => {
+    expect(canShowApply(c({ suggestedText: null }), true)).toBe(false);
+  });
+  it("false when already applied", () => {
+    expect(canShowApply(c({ suggestionAppliedAt: new Date() }), true)).toBe(
+      false,
+    );
+  });
+  it("false when resolved", () => {
+    expect(canShowApply(c({ resolvedAt: new Date() }), true)).toBe(false);
+  });
+  it("false for a reply comment", () => {
+    expect(canShowApply(c({ parentCommentId: "p" }), true)).toBe(false);
+  });
 });

apps/client/src/features/comment/components/comment-list-item.tsx

@@ -1,5 +1,5 @@
-import { Group, Text, Box } from "@mantine/core";
-import { AiAgentBadge } from "@/components/ui/ai-agent-badge.tsx";
+import { Group, Text, Box, Badge, Button } from "@mantine/core";
+import { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
 import React, { useEffect, useRef, useState } from "react";
 import classes from "./comment.module.css";
 import { useAtom, useAtomValue } from "jotai";
@@ -11,11 +11,13 @@ import CommentMenu from "@/features/comment/components/comment-menu";
 import ResolveComment from "@/features/comment/components/resolve-comment";
 import { useHover } from "@mantine/hooks";
 import {
+  useApplySuggestionMutation,
   useDeleteCommentMutation,
   useResolveCommentMutation,
   useUpdateCommentMutation,
 } from "@/features/comment/queries/comment-query";
 import { IComment } from "@/features/comment/types/comment.types";
+import { canShowApply } from "@/features/comment/utils/suggestion";
 import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom.ts";
 import { useTranslation } from "react-i18next";
@@ -24,6 +26,10 @@ interface CommentListItemProps {
   comment: IComment;
   pageId: string;
   canComment: boolean;
+  // Real page-edit permission (page.permissions.canEdit) — gates the suggestion
+  // "Apply" button. Distinct from `canComment`, which may be looser (viewers
+  // allowed to comment cannot apply edits).
+  canEdit?: boolean;
   userSpaceRole?: string;
 }
 
@@ -31,6 +37,7 @@ function CommentListItem({
   comment,
   pageId,
   canComment,
+  canEdit,
   userSpaceRole,
 }: CommentListItemProps) {
   const { t } = useTranslation();
@@ -43,6 +50,7 @@ function CommentListItem({
   const updateCommentMutation = useUpdateCommentMutation();
   const deleteCommentMutation = useDeleteCommentMutation(comment.pageId);
   const resolveCommentMutation = useResolveCommentMutation();
+  const applySuggestionMutation = useApplySuggestionMutation();
   const [currentUser] = useAtom(currentUserAtom);
   const createdAtAgo = useTimeAgo(comment.createdAt);
 
@@ -95,6 +103,18 @@ function CommentListItem({
     }
   }
 
+  async function handleApplySuggestion() {
+    try {
+      await applySuggestionMutation.mutateAsync({
+        commentId: comment.id,
+        pageId: comment.pageId,
+      });
+    } catch (error) {
+      // Errors surface via the mutation's onError notification (incl. 409).
+      console.error("Failed to apply suggestion:", error);
+    }
+  }
+
   function handleCommentClick(comment: IComment) {
     const el = document.querySelector(
       `.comment-mark[data-comment-id="${comment.id}"]`,
@@ -119,24 +139,44 @@ function CommentListItem({
   return (
     <Box ref={ref} pb={6}>
       <Group gap="xs">
-        <CustomAvatar
-          size="sm"
-          avatarUrl={comment.creator.avatarUrl}
-          name={comment.creator.name}
-        />
+        {comment.createdSource === "agent" && comment.agent ? (
+          <AgentAvatarStack
+            agent={comment.agent}
+            launcher={comment.launcher}
+            aiChatId={comment.aiChatId}
+            showName={false}
+          />
+        ) : (
+          <CustomAvatar
+            size="sm"
+            avatarUrl={comment.creator.avatarUrl}
+            name={comment.creator.name}
+          />
+        )}
 
         <div style={{ flex: 1 }}>
           <Group justify="space-between" wrap="nowrap">
             <Group gap={6} wrap="nowrap" style={{ minWidth: 0 }}>
-              <Text size="xs" fw={500} lineClamp={1} lh={1.2}>
-                {comment.creator.name}
-              </Text>
-
-              {comment.createdSource === "agent" && (
-                <AiAgentBadge
-                  authorName={comment.creator?.name}
-                  aiChatId={comment.aiChatId}
-                />
+              {comment.createdSource === "agent" && comment.agent ? (
+                <>
+                  <Text size="xs" fw={600} lineClamp={1} lh={1.2}>
+                    {comment.agent.name}
+                  </Text>
+                  {comment.launcher && (
+                    <>
+                      <Text size="xs" c="dimmed" fw={400} aria-hidden>
+                        ·
+                      </Text>
+                      <Text size="xs" c="dimmed" fw={400} lineClamp={1} lh={1.2}>
+                        {comment.launcher.name}
+                      </Text>
+                    </>
+                  )}
+                </>
+              ) : (
+                <Text size="xs" fw={500} lineClamp={1} lh={1.2}>
+                  {comment.creator.name}
+                </Text>
               )}
             </Group>
 
@@ -191,6 +231,47 @@ function CommentListItem({
           </Box>
         )}
 
+        {/* Suggested-edit (#315): "было → стало" diff for a top-level comment
+            carrying a suggestion. Old text struck-through/red, new text green. */}
+        {!comment.parentCommentId && comment.suggestedText && (
+          <Box className={classes.suggestionBlock}>
+            {comment.selection && (
+              <Text size="xs" className={classes.suggestionOld}>
+                {comment.selection}
+              </Text>
+            )}
+            <Text size="xs" className={classes.suggestionNew}>
+              {comment.suggestedText}
+            </Text>
+
+            {comment.suggestionAppliedAt ? (
+              <Badge
+                size="sm"
+                color="green"
+                variant="light"
+                mt={6}
+                aria-label={t("Applied")}
+              >
+                {t("Applied")}
+              </Badge>
+            ) : (
+              canShowApply(comment, canEdit) && (
+                <Button
+                  size="compact-xs"
+                  variant="light"
+                  color="green"
+                  mt={6}
+                  onClick={handleApplySuggestion}
+                  loading={applySuggestionMutation.isPending}
+                  disabled={applySuggestionMutation.isPending}
+                >
+                  {t("Apply")}
+                </Button>
+              )
+            )}
+          </Box>
+        )}
+
         {!isEditing ? (
           <CommentEditor defaultContent={content} editable={false} />
         ) : (

apps/client/src/features/comment/components/comment-list-with-tabs.tsx

@@ -49,8 +49,10 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
   const [isLoading, setIsLoading] = useState(false);
   const { data: space } = useGetSpaceBySlugQuery(page?.space?.slug);
 
+  const canEdit = page?.permissions?.canEdit ?? false;
+
   const canComment =
-    (page?.permissions?.canEdit ?? false) ||
+    canEdit ||
     (space?.settings?.comments?.allowViewerComments === true);
 
   // Separate active and resolved comments
@@ -137,6 +139,7 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
             comment={comment}
             pageId={page?.id}
             canComment={canComment}
+            canEdit={canEdit}
             userSpaceRole={space?.membership?.role}
           />
           <MemoizedChildComments
@@ -144,6 +147,7 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
             parentId={comment.id}
             pageId={page?.id}
             canComment={canComment}
+            canEdit={canEdit}
             userSpaceRole={space?.membership?.role}
           />
         </div>
@@ -160,7 +164,14 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
         )}
       </Paper>
     ),
-    [comments, handleAddReply, isLoading, space?.membership?.role, canComment],
+    [
+      comments,
+      handleAddReply,
+      isLoading,
+      space?.membership?.role,
+      canComment,
+      canEdit,
+    ],
   );
 
   if (isCommentsLoading) {
@@ -300,6 +311,7 @@ interface ChildCommentsProps {
   parentId: string;
   pageId: string;
   canComment: boolean;
+  canEdit?: boolean;
   userSpaceRole?: string;
 }
 const ChildComments = ({
@@ -307,6 +319,7 @@ const ChildComments = ({
   parentId,
   pageId,
   canComment,
+  canEdit,
   userSpaceRole,
 }: ChildCommentsProps) => {
   const getChildComments = useCallback(
@@ -325,6 +338,7 @@ const ChildComments = ({
             comment={childComment}
             pageId={pageId}
             canComment={canComment}
+            canEdit={canEdit}
             userSpaceRole={userSpaceRole}
           />
           <MemoizedChildComments
@@ -332,6 +346,7 @@ const ChildComments = ({
             parentId={childComment.id}
             pageId={pageId}
             canComment={canComment}
+            canEdit={canEdit}
             userSpaceRole={userSpaceRole}
           />
         </div>

apps/client/src/features/comment/components/comment.module.css

@@ -21,6 +21,38 @@
     box-sizing: border-box;
 }
 
+/* Suggested-edit (#315) "было → стало" diff block. */
+.suggestionBlock {
+    margin-top: 8px;
+    margin-left: 6px;
+    padding: 6px;
+    border-radius: var(--mantine-radius-sm);
+    border: 1px solid var(--mantine-color-default-border);
+    overflow-wrap: break-word;
+    word-break: break-word;
+    max-width: 100%;
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+}
+
+.suggestionOld {
+    text-decoration: line-through;
+    color: var(--mantine-color-red-7);
+    background: var(--mantine-color-red-light);
+    border-radius: 2px;
+    padding: 1px 3px;
+}
+
+.suggestionNew {
+    color: var(--mantine-color-green-9);
+    background: var(--mantine-color-green-light);
+    border-radius: 2px;
+    padding: 1px 3px;
+    margin-top: 4px;
+}
+
 .commentEditor {
 
     &[data-editable][data-surface="muted"] .ProseMirror:not(.focused) {

apps/client/src/features/comment/queries/comment-query.ts

@@ -5,6 +5,7 @@ import {
   InfiniteData,
 } from "@tanstack/react-query";
 import {
+  applySuggestion,
   createComment,
   deleteComment,
   getPageComments,
@@ -176,6 +177,63 @@ function updateCommentInCache(
   };
 }
 
+export function useApplySuggestionMutation() {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+
+  return useMutation<IComment, any, { commentId: string; pageId: string }>({
+    // No optimistic update: apply can fail with 409 (the commented text drifted),
+    // so we only mutate the cache once the server confirms.
+    mutationFn: ({ commentId }) => applySuggestion(commentId),
+    onSuccess: (data, variables) => {
+      const cache = queryClient.getQueryData(
+        RQ_KEY(variables.pageId),
+      ) as InfiniteData<IPagination<IComment>> | undefined;
+
+      if (cache) {
+        queryClient.setQueryData(
+          RQ_KEY(variables.pageId),
+          updateCommentInCache(cache, variables.commentId, (comment) => ({
+            ...comment,
+            suggestionAppliedAt: data.suggestionAppliedAt,
+            suggestionAppliedById: data.suggestionAppliedById,
+            // The server auto-resolves the thread on apply — carry that through.
+            resolvedAt: data.resolvedAt,
+            resolvedById: data.resolvedById,
+            resolvedBy: data.resolvedBy,
+          })),
+        );
+      }
+
+      notifications.show({ message: t("Suggestion applied") });
+    },
+    onError: (err: any) => {
+      // 409 => the commented text changed since the suggestion was made. Surface
+      // a specific message (with the current text) rather than a generic error.
+      const status = err?.response?.status;
+      const currentText = err?.response?.data?.currentText;
+      if (status === 409 && typeof currentText === "string") {
+        const shortText =
+          currentText.length > 80
+            ? `${currentText.slice(0, 80)}…`
+            : currentText;
+        notifications.show({
+          title: t(
+            "The commented text changed since this suggestion was made; it was not applied.",
+          ),
+          message: shortText,
+          color: "red",
+        });
+        return;
+      }
+      notifications.show({
+        message: t("Failed to apply suggestion"),
+        color: "red",
+      });
+    },
+  });
+}
+
 export function useResolveCommentMutation() {
   const queryClient = useQueryClient();
   const { t } = useTranslation();

apps/client/src/features/comment/services/comment-service.ts

@@ -18,6 +18,13 @@ export async function resolveComment(data: IResolveComment): Promise<IComment> {
   return req.data;
 }
 
+export async function applySuggestion(commentId: string): Promise<IComment> {
+  // Mirrors resolveComment: let axios reject on non-2xx so the mutation can read
+  // the 409 body (`{ message, currentText }`) off err.response.data.
+  const req = await api.post("/comments/apply-suggestion", { commentId });
+  return req.data.data ?? req.data;
+}
+
 export async function updateComment(
   data: Partial<IComment>,
 ): Promise<IComment> {

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

@@ -1,5 +1,9 @@
 import { IUser } from "@/features/user/types/user.types";
 import { QueryParams } from "@/lib/types.ts";
+import type {
+  AgentInfo,
+  LauncherInfo,
+} from "@/components/ui/agent-avatar-stack.tsx";
 
 export interface IComment {
   id: string;
@@ -24,6 +28,18 @@ export interface IComment {
   createdSource?: string;
   aiChatId?: string | null;
   resolvedSource?: string | null;
+  // Suggested-edit (#315): when an agent proposes a replacement for the
+  // commented `selection`, `suggestedText` holds the "стало" text. Once a user
+  // applies it server-side the backend stamps `suggestionAppliedAt` /
+  // `suggestionAppliedById` and auto-resolves the thread.
+  suggestedText?: string | null;
+  suggestionAppliedAt?: Date | string | null;
+  suggestionAppliedById?: string | null;
+  // Server-normalized "agent avatar stack" provenance (#300), present only when
+  // createdSource === "agent": `agent` is the front identity, `launcher` the
+  // human behind it (null for an external MCP agent).
+  agent?: AgentInfo | null;
+  launcher?: LauncherInfo | null;
   yjsSelection?: {
     anchor: any;
     head: any;

apps/client/src/features/comment/utils/suggestion.ts

@@ -0,0 +1,14 @@
+import { IComment } from "@/features/comment/types/comment.types";
+
+// Whether the suggested-edit (#315) "Apply" button should be shown for a
+// comment: it must carry a suggestion, not already be applied or resolved, be a
+// top-level comment, and the viewer must be able to edit the page.
+export function canShowApply(comment: IComment, canEdit?: boolean): boolean {
+  return Boolean(
+    canEdit &&
+      comment.suggestedText &&
+      !comment.suggestionAppliedAt &&
+      !comment.resolvedAt &&
+      !comment.parentCommentId,
+  );
+}

apps/client/src/features/dictation/components/mic-button.test.tsx

@@ -0,0 +1,92 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+
+// A disabled mic must explain WHY it is unavailable rather than silently saying
+// "Start dictation". This renders MicButton in its idle+disabled state with a
+// forwarded reason and asserts the accessible label resolves to that reason's
+// text via the shared resolver (dictation-status.resolveUnavailableLabel).
+
+// matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
+
+// Pass i18n keys through verbatim so we assert the exact resolved string.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (s: string) => s }),
+}));
+
+// Keep both controllers inert and idle so MicButton renders the idle branch.
+const idleCtl = {
+  status: "idle" as const,
+  start: vi.fn(async () => {}),
+  stop: vi.fn(),
+  cancel: vi.fn(),
+  audioLevel: 0,
+  errorMessage: null,
+};
+vi.mock("@/features/dictation/hooks/use-dictation", () => ({
+  useDictation: () => idleCtl,
+}));
+vi.mock("@/features/dictation/hooks/use-streaming-dictation", () => ({
+  useStreamingDictation: () => idleCtl,
+}));
+
+import { MicButton } from "./mic-button";
+
+function renderButton(props: React.ComponentProps<typeof MicButton>) {
+  render(
+    <MantineProvider>
+      <MicButton {...props} />
+    </MantineProvider>,
+  );
+}
+
+describe("MicButton — disabled reason label", () => {
+  // jsdom has no MediaRecorder / mediaDevices, so isDictationSupported() would
+  // report "unsupported" and mask the forwarded reason. Stub both so the button
+  // is considered supported and the availability reason is what surfaces.
+  beforeEach(() => {
+    (globalThis as unknown as { MediaRecorder: unknown }).MediaRecorder =
+      class {};
+    Object.defineProperty(navigator, "mediaDevices", {
+      configurable: true,
+      value: { getUserMedia: vi.fn() },
+    });
+  });
+  afterEach(() => {
+    delete (globalThis as unknown as { MediaRecorder?: unknown }).MediaRecorder;
+  });
+
+  it("shows the cause-specific reason instead of 'Start dictation' when disabled with a reason", () => {
+    renderButton({ onText: () => {}, disabled: true, unavailableReason: "offline" });
+    const expected =
+      "No connection to the collaboration server — dictation unavailable";
+    // The reason surfaces as the accessible label (and the tooltip text).
+    const button = screen.getByRole("button", { name: expected });
+    expect(button).toBeDefined();
+    // It is marked disabled the Mantine way (data-disabled), NOT the native
+    // `disabled` attribute — otherwise pointer-events:none would kill the tooltip.
+    expect(button.getAttribute("data-disabled")).toBe("true");
+    expect(button.hasAttribute("disabled")).toBe(false);
+    // And it no longer silently reads "Start dictation".
+    expect(screen.queryByRole("button", { name: "Start dictation" })).toBeNull();
+  });
+
+  it("reads 'Start dictation' when enabled with no reason", () => {
+    renderButton({ onText: () => {} });
+    expect(
+      screen.getByRole("button", { name: "Start dictation" }),
+    ).toBeDefined();
+  });
+
+  it("does not advertise 'Start dictation' when disabled with no reason", () => {
+    // A consumer passing bare `disabled` (e.g. the AI chat's isStreaming) with no
+    // unavailableReason must not get a hoverable mic whose tooltip invites
+    // "Start dictation" on a click that is rejected.
+    renderButton({ onText: () => {}, disabled: true });
+    expect(
+      screen.queryByRole("button", { name: "Start dictation" }),
+    ).toBeNull();
+    const button = screen.getByRole("button");
+    expect(button.getAttribute("data-disabled")).toBe("true");
+  });
+});

apps/client/src/features/dictation/components/mic-button.tsx

@@ -4,6 +4,11 @@ import { IconMicrophone, IconPlayerStopFilled } from "@tabler/icons-react";
 import { useTranslation } from "react-i18next";
 import { useDictation } from "@/features/dictation/hooks/use-dictation";
 import { useStreamingDictation } from "@/features/dictation/hooks/use-streaming-dictation";
+import {
+  isDictationSupported,
+  resolveUnavailableLabel,
+  type DictationUnavailableReason,
+} from "@/features/dictation/dictation-status";
 import classes from "./mic-button.module.css";
 
 interface MicButtonProps {
@@ -21,6 +26,9 @@ interface MicButtonProps {
   // When true, use the streaming (Silero-VAD) dictation controller, which emits
   // text progressively as the user pauses; otherwise use the batch controller.
   streaming?: boolean;
+  // When the mic is disabled for an availability reason, this is the cause the
+  // idle tooltip explains (e.g. pre-sync "connecting", "offline", "read-only").
+  unavailableReason?: DictationUnavailableReason;
 }
 
 /**
@@ -37,6 +45,7 @@ export const MicButton: FC<MicButtonProps> = ({
   color,
   iconSize,
   streaming = false,
+  unavailableReason,
 }) => {
   const { t } = useTranslation();
   // Call BOTH hooks unconditionally to respect the rules of hooks: which one is
@@ -46,7 +55,7 @@ export const MicButton: FC<MicButtonProps> = ({
   const batchCtl = useDictation({ onText, onStart });
   const streamingCtl = useStreamingDictation({ onText, onStart });
   const ctl = streaming ? streamingCtl : batchCtl;
-  const { status, start, stop, audioLevel } = ctl;
+  const { status, start, stop, audioLevel, errorMessage } = ctl;
   const resolvedIconSize = iconSize ?? (size === "lg" ? 18 : 16);
 
   if (status === "recording") {
@@ -82,15 +91,28 @@ export const MicButton: FC<MicButtonProps> = ({
   ) {
     // "loading" (streaming hook fetching the VAD model on first use) shows the
     // same spinner+disabled state so the first click is visibly acknowledged and
-    // a confusing second click can't fire while the model loads.
-    const label = status === "loading" ? t("Preparing…") : t("Transcribing…");
+    // a confusing second click can't fire while the model loads. The error case
+    // explains the failure via the hook's resolved errorMessage instead of the
+    // transient "Transcribing…" label.
+    const label =
+      status === "error"
+        ? (errorMessage ?? t("Transcription failed"))
+        : status === "loading"
+          ? t("Preparing…")
+          : t("Transcribing…");
     return (
       <Tooltip label={label} withArrow>
         <ActionIcon
           size={size}
           variant="subtle"
           color={color}
-          disabled
+          // Mark disabled the Mantine way (data-disabled/aria-disabled) rather
+          // than the native `disabled` attribute: native `disabled` sets
+          // `pointer-events:none`, which suppresses hover so the Tooltip never
+          // fires. This is a status display with no click action to guard, so
+          // keeping it hoverable simply lets the error reason be read on hover.
+          data-disabled
+          aria-disabled
           aria-label={label}
         >
           <Loader size="xs" />
@@ -99,18 +121,56 @@ export const MicButton: FC<MicButtonProps> = ({
     );
   }
 
+  // Idle branch. A grey/disabled mic must explain WHY it can't record. An
+  // unsupported browser/context is detected here; otherwise the parent forwards
+  // a cause-specific reason. We must NOT pass the native `disabled` prop: Mantine
+  // renders `<button disabled>` with `pointer-events:none`, which suppresses
+  // hover so the Tooltip never fires. Instead mark it disabled the Mantine way
+  // (data-disabled/aria-disabled) — keeping it hoverable and in the a11y tree —
+  // and guard the click ourselves.
+  const unsupported = !isDictationSupported();
+  const isDisabled = disabled || unsupported;
+  const reason: DictationUnavailableReason | undefined = unsupported
+    ? "unsupported"
+    : unavailableReason;
+  const reasonLabel = reason ? resolveUnavailableLabel(reason, t) : undefined;
+  // A disabled mic with a known reason surfaces it on hover; an enabled mic
+  // invites "Start dictation". But a mic disabled with NO reason (e.g. a
+  // consumer that passes bare `disabled` — the AI chat's isStreaming, with no
+  // unavailableReason) must NOT hover a misleading, actionable "Start dictation"
+  // tooltip on a control that rejects the click. In that case we render the icon
+  // without a Tooltip and give it a neutral accessible label instead.
+  const ariaLabel = reasonLabel ?? (isDisabled ? t("Dictation") : t("Start dictation"));
+  const icon = (
+    <ActionIcon
+      size={size}
+      variant="subtle"
+      color={color}
+      onClick={(e) => {
+        if (isDisabled) {
+          e.preventDefault();
+          return;
+        }
+        void start();
+      }}
+      data-disabled={isDisabled || undefined}
+      aria-disabled={isDisabled}
+      aria-label={ariaLabel}
+    >
+      <IconMicrophone size={resolvedIconSize} />
+    </ActionIcon>
+  );
+  // Suppress the tooltip on a disabled mic that has nothing to explain — hovering
+  // a grey, unclickable mic should not advertise "Start dictation".
+  if (isDisabled && !reasonLabel) {
+    return icon;
+  }
   return (
-    <Tooltip label={t("Start dictation")} withArrow>
-      <ActionIcon
-        size={size}
-        variant="subtle"
-        color={color}
-        onClick={() => void start()}
-        disabled={disabled}
-        aria-label={t("Start dictation")}
-      >
-        <IconMicrophone size={resolvedIconSize} />
-      </ActionIcon>
+    <Tooltip
+      label={reasonLabel ?? t("Start dictation")}
+      withArrow
+    >
+      {icon}
     </Tooltip>
   );
 };

apps/client/src/features/dictation/dictation-status.test.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect } from "vitest";
+import {
+  classifyGetUserMediaError,
+  classifyTranscriptionError,
+  dictationErrorMessage,
+  resolveUnavailableLabel,
+  isDictationSupported,
+} from "./dictation-status";
+
+// Unit tests for the shared dictation-status resolvers (dictation-status.ts).
+// Both dictation hooks and the mic button form their user-facing strings here,
+// so a regression in the classification or message mapping would silently swap
+// what a user reads when the mic is grey or a recording fails. A fake `t`
+// returns its key verbatim so we assert the exact i18n key each branch selects.
+const t = (k: string) => k;
+
+describe("classifyGetUserMediaError", () => {
+  it("maps NotAllowedError / SecurityError to mic-denied", () => {
+    expect(classifyGetUserMediaError({ name: "NotAllowedError" })).toBe(
+      "mic-denied",
+    );
+    expect(classifyGetUserMediaError({ name: "SecurityError" })).toBe(
+      "mic-denied",
+    );
+  });
+
+  it("maps NotFoundError / OverconstrainedError to no-mic", () => {
+    expect(classifyGetUserMediaError({ name: "NotFoundError" })).toBe("no-mic");
+    expect(classifyGetUserMediaError({ name: "OverconstrainedError" })).toBe(
+      "no-mic",
+    );
+  });
+
+  it("maps NotReadableError / AbortError to mic-in-use", () => {
+    expect(classifyGetUserMediaError({ name: "NotReadableError" })).toBe(
+      "mic-in-use",
+    );
+    expect(classifyGetUserMediaError({ name: "AbortError" })).toBe(
+      "mic-in-use",
+    );
+  });
+
+  it("maps anything else / undefined to unknown", () => {
+    expect(classifyGetUserMediaError({ name: "WeirdError" })).toBe("unknown");
+    expect(classifyGetUserMediaError(undefined)).toBe("unknown");
+    expect(classifyGetUserMediaError({})).toBe("unknown");
+  });
+});
+
+describe("classifyTranscriptionError", () => {
+  it("returns the verbatim server message when present", () => {
+    const err = { response: { status: 500, data: { message: "provider 404" } } };
+    expect(classifyTranscriptionError(err)).toEqual({
+      code: "transcription-failed",
+      serverMessage: "provider 404",
+    });
+  });
+
+  it("maps 503 / 403 (no server message) to stt-not-configured", () => {
+    expect(classifyTranscriptionError({ response: { status: 503 } })).toEqual({
+      code: "stt-not-configured",
+    });
+    expect(classifyTranscriptionError({ response: { status: 403 } })).toEqual({
+      code: "stt-not-configured",
+    });
+  });
+
+  it("falls back to transcription-failed with no server message otherwise", () => {
+    expect(classifyTranscriptionError({ response: { status: 500 } })).toEqual({
+      code: "transcription-failed",
+    });
+    expect(classifyTranscriptionError(new Error("network"))).toEqual({
+      code: "transcription-failed",
+    });
+    // Blank server message is ignored (does not win as verbatim text).
+    expect(
+      classifyTranscriptionError({ response: { data: { message: "   " } } }),
+    ).toEqual({ code: "transcription-failed" });
+  });
+});
+
+describe("dictationErrorMessage", () => {
+  it("maps each code to the expected i18n key", () => {
+    expect(dictationErrorMessage("mic-denied", t)).toBe(
+      "Microphone access denied",
+    );
+    expect(dictationErrorMessage("no-mic", t)).toBe("No microphone found");
+    expect(dictationErrorMessage("mic-in-use", t)).toBe(
+      "Microphone is unavailable or already in use",
+    );
+    expect(dictationErrorMessage("no-media-devices", t)).toBe(
+      "Audio recording is not available in this browser/context",
+    );
+    expect(dictationErrorMessage("stt-not-configured", t)).toBe(
+      "Voice dictation is not configured",
+    );
+    expect(dictationErrorMessage("transcription-failed", t)).toBe(
+      "Transcription failed",
+    );
+    expect(dictationErrorMessage("recorder-failed", t)).toBe(
+      "Could not start recording",
+    );
+    expect(dictationErrorMessage("vad-init-failed", t)).toBe(
+      "Could not start recording",
+    );
+    expect(dictationErrorMessage("unknown", t)).toBe(
+      "Could not start recording",
+    );
+  });
+
+  it("returns the server message verbatim for transcription-failed (not the t key)", () => {
+    expect(
+      dictationErrorMessage("transcription-failed", t, {
+        serverMessage: "quota exceeded",
+      }),
+    ).toBe("quota exceeded");
+  });
+
+  it("appends the detail to recorder-failed / unknown", () => {
+    expect(
+      dictationErrorMessage("recorder-failed", t, { detail: "boom" }),
+    ).toBe("Could not start recording: boom");
+    expect(dictationErrorMessage("unknown", t, { detail: "nope" })).toBe(
+      "Could not start recording: nope",
+    );
+  });
+
+  it("appends the detail to transcription-failed when there is no server message", () => {
+    expect(
+      dictationErrorMessage("transcription-failed", t, { detail: "timeout" }),
+    ).toBe("Transcription failed: timeout");
+  });
+});
+
+describe("resolveUnavailableLabel", () => {
+  it("maps each reason to its expected i18n key", () => {
+    expect(resolveUnavailableLabel("connecting", t)).toBe(
+      "Dictation becomes available once the page finishes connecting",
+    );
+    expect(resolveUnavailableLabel("offline", t)).toBe(
+      "No connection to the collaboration server — dictation unavailable",
+    );
+    expect(resolveUnavailableLabel("read-only", t)).toBe(
+      "This page is read-only",
+    );
+    expect(resolveUnavailableLabel("unsupported", t)).toBe(
+      "Audio recording is not available in this browser/context",
+    );
+  });
+});
+
+describe("isDictationSupported", () => {
+  it("returns a boolean", () => {
+    expect(typeof isDictationSupported()).toBe("boolean");
+  });
+});

apps/client/src/features/dictation/dictation-status.ts

@@ -0,0 +1,110 @@
+// Single source of truth for "why dictation is unavailable" and "why it failed".
+// Both dictation hooks and the mic button pull their user-facing strings from
+// the resolvers here so the wording lives in exactly one place.
+
+export type DictationUnavailableReason =
+  | "connecting"
+  | "offline"
+  | "read-only"
+  | "unsupported";
+
+export type DictationErrorCode =
+  | "no-media-devices"
+  | "mic-denied"
+  | "no-mic"
+  | "mic-in-use"
+  | "recorder-failed"
+  | "vad-init-failed"
+  | "stt-not-configured"
+  | "transcription-failed"
+  | "unknown";
+
+// True if this browser/context can record audio.
+export function isDictationSupported(): boolean {
+  return (
+    typeof MediaRecorder !== "undefined" &&
+    typeof navigator !== "undefined" &&
+    !!navigator.mediaDevices?.getUserMedia
+  );
+}
+
+// getUserMedia / VAD.start rejection -> code, by DOMException .name.
+export function classifyGetUserMediaError(err: unknown): DictationErrorCode {
+  const name = (err as { name?: string })?.name;
+  if (name === "NotAllowedError" || name === "SecurityError")
+    return "mic-denied";
+  if (name === "NotFoundError" || name === "OverconstrainedError")
+    return "no-mic";
+  if (name === "NotReadableError" || name === "AbortError") return "mic-in-use";
+  return "unknown";
+}
+
+// Transcription HTTP failure -> code (+ verbatim server message when present).
+export function classifyTranscriptionError(err: unknown): {
+  code: DictationErrorCode;
+  serverMessage?: string;
+} {
+  const resp = (
+    err as { response?: { status?: number; data?: { message?: string } } }
+  )?.response;
+  const serverMessage = resp?.data?.message;
+  if (serverMessage && serverMessage.trim().length > 0)
+    return { code: "transcription-failed", serverMessage };
+  if (resp?.status === 503 || resp?.status === 403)
+    return { code: "stt-not-configured" };
+  return { code: "transcription-failed" };
+}
+
+type TFn = (key: string) => string;
+
+// Code -> user text. The ONE place runtime error strings are formed.
+// serverMessage (verbatim) wins for transcription-failed; detail is appended
+// to the generic "could not start"/"transcription failed" strings.
+export function dictationErrorMessage(
+  code: DictationErrorCode,
+  t: TFn,
+  extra?: { serverMessage?: string; detail?: string },
+): string {
+  const detail = extra?.detail;
+  switch (code) {
+    case "mic-denied":
+      return t("Microphone access denied");
+    case "no-mic":
+      return t("No microphone found");
+    case "mic-in-use":
+      return t("Microphone is unavailable or already in use");
+    case "no-media-devices":
+      return t("Audio recording is not available in this browser/context");
+    case "stt-not-configured":
+      return t("Voice dictation is not configured");
+    case "transcription-failed":
+      if (extra?.serverMessage && extra.serverMessage.trim().length > 0)
+        return extra.serverMessage;
+      return `${t("Transcription failed")}${detail ? `: ${detail}` : ""}`;
+    case "recorder-failed":
+    case "vad-init-failed":
+    case "unknown":
+    default:
+      return `${t("Could not start recording")}${detail ? `: ${detail}` : ""}`;
+  }
+}
+
+// Unavailable reason -> tooltip text (the ONE place these strings are formed).
+export function resolveUnavailableLabel(
+  r: DictationUnavailableReason,
+  t: TFn,
+): string {
+  switch (r) {
+    case "connecting":
+      return t("Dictation becomes available once the page finishes connecting");
+    case "offline":
+      return t(
+        "No connection to the collaboration server — dictation unavailable",
+      );
+    case "read-only":
+      return t("This page is read-only");
+    case "unsupported":
+    default:
+      return t("Audio recording is not available in this browser/context");
+  }
+}

apps/client/src/features/dictation/hooks/use-dictation.ts

@@ -2,6 +2,11 @@ import { useCallback, useEffect, useRef, useState } from "react";
 import { notifications } from "@mantine/notifications";
 import { useTranslation } from "react-i18next";
 import { transcribeAudio } from "@/features/dictation/services/dictation-service";
+import {
+  classifyGetUserMediaError,
+  classifyTranscriptionError,
+  dictationErrorMessage,
+} from "@/features/dictation/dictation-status";
 
 // "loading" is set only by the streaming hook while it lazily loads the VAD
 // model on first use; the batch hook never sets it. It exists so the streaming
@@ -26,6 +31,8 @@ interface UseDictationResult {
   cancel: () => void;
   // Smoothed live microphone level in the 0..1 range while recording (0 when idle).
   audioLevel: number;
+  // The last error shown to the user (null until one occurs / on a new start).
+  errorMessage: string | null;
 }
 
 // Candidate container/codec combinations in preference order. The first one the
@@ -67,6 +74,8 @@ export function useDictation(
   const { t } = useTranslation();
   const [status, setStatus] = useState<DictationStatus>("idle");
   const [audioLevel, setAudioLevel] = useState(0);
+  // Last error message shown to the user; the mic button reads it for its tooltip.
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
 
   // Keep the latest callbacks in a ref so the recorder's onstop closure always
   // calls the current handlers without re-creating the recorder.
@@ -194,15 +203,16 @@ export function useDictation(
     if (startingRef.current || recorderRef.current || streamRef.current) return;
     if (status !== "idle") return;
     startingRef.current = true;
+    // Clear any stale error from a previous attempt.
+    setErrorMessage(null);
 
     if (!navigator.mediaDevices?.getUserMedia) {
       const reason =
         "navigator.mediaDevices.getUserMedia is unavailable in this context";
       console.error("[dictation] " + reason);
-      notifications.show({
-        color: "red",
-        message: t("Audio recording is not available in this browser/context"),
-      });
+      const message = dictationErrorMessage("no-media-devices", t);
+      notifications.show({ color: "red", message });
+      setErrorMessage(message);
       setStatus("idle");
       startingRef.current = false;
       return;
@@ -215,19 +225,16 @@ export function useDictation(
       // Always log the full error for diagnosis (name, message, stack).
       console.error("[dictation] getUserMedia failed", err);
       const name = (err as { name?: string })?.name;
-      const detail = (err as { message?: string })?.message ?? String(err);
-      let message: string;
-      if (name === "NotAllowedError" || name === "SecurityError") {
-        message = t("Microphone access denied");
-      } else if (name === "NotFoundError" || name === "OverconstrainedError") {
-        message = t("No microphone found");
-      } else if (name === "NotReadableError" || name === "AbortError") {
-        message = t("Microphone is unavailable or already in use");
-      } else {
-        // Unknown failure: show the real reason instead of a generic string.
-        message = `${t("Could not start recording")}: ${name ? `${name}: ` : ""}${detail}`;
-      }
+      const rawDetail = (err as { message?: string })?.message ?? String(err);
+      // Prefix the DOMException name (e.g. "TypeError: …") so the generic
+      // resolver branch reproduces this hook's original "Could not start
+      // recording: <name>: <detail>" text. Each caller owns its own detail; the
+      // streaming hook intentionally does not add the name.
+      const detail = `${name ? `${name}: ` : ""}${rawDetail}`;
+      const code = classifyGetUserMediaError(err);
+      const message = dictationErrorMessage(code, t, { detail });
       notifications.show({ color: "red", message });
+      setErrorMessage(message);
       setStatus("idle");
       startingRef.current = false;
       return;
@@ -249,10 +256,10 @@ export function useDictation(
       // The stream was acquired but the recorder failed to construct; stop the
       // tracks so the MediaStream does not leak before bailing out.
       stopTracks();
-      notifications.show({
-        color: "red",
-        message: `${t("Could not start recording")}: ${(err as { message?: string })?.message ?? String(err)}`,
-      });
+      const detail = (err as { message?: string })?.message ?? String(err);
+      const message = dictationErrorMessage("recorder-failed", t, { detail });
+      notifications.show({ color: "red", message });
+      setErrorMessage(message);
       setStatus("idle");
       startingRef.current = false;
       return;
@@ -293,21 +300,14 @@ export function useDictation(
         .catch((err: unknown) => {
           // Log the full error for diagnosis (status + body + stack).
           console.error("[dictation] transcription failed", err);
-          const resp = (
-            err as { response?: { status?: number; data?: { message?: string } } }
-          )?.response;
-          const serverMsg = resp?.data?.message;
-          let message: string;
-          if (serverMsg && serverMsg.trim().length > 0) {
-            // The server already explains the cause (e.g. provider 404, bad
-            // format, STT not configured) — show it verbatim.
-            message = serverMsg;
-          } else if (resp?.status === 503 || resp?.status === 403) {
-            message = t("Voice dictation is not configured");
-          } else {
-            message = `${t("Transcription failed")}: ${(err as { message?: string })?.message ?? String(err)}`;
-          }
+          const { code, serverMessage } = classifyTranscriptionError(err);
+          const detail = (err as { message?: string })?.message ?? String(err);
+          const message = dictationErrorMessage(code, t, {
+            serverMessage,
+            detail,
+          });
           notifications.show({ color: "red", message });
+          setErrorMessage(message);
           setStatus("error");
           if (errorTimerRef.current !== null) {
             clearTimeout(errorTimerRef.current);
@@ -332,10 +332,10 @@ export function useDictation(
       stopTracks();
       recorderRef.current = null;
       startingRef.current = false;
-      notifications.show({
-        color: "red",
-        message: `${t("Could not start recording")}: ${(err as { message?: string })?.message ?? String(err)}`,
-      });
+      const detail = (err as { message?: string })?.message ?? String(err);
+      const message = dictationErrorMessage("recorder-failed", t, { detail });
+      notifications.show({ color: "red", message });
+      setErrorMessage(message);
       setStatus("idle");
       return;
     }
@@ -405,5 +405,5 @@ export function useDictation(
     };
   }, [clearTimer, stopTracks, stopMeter]);
 
-  return { status, start, stop, cancel, audioLevel };
+  return { status, start, stop, cancel, audioLevel, errorMessage };
 }

apps/client/src/features/dictation/hooks/use-streaming-dictation.ts

@@ -4,6 +4,11 @@ import { useTranslation } from "react-i18next";
 import { transcribeAudio } from "@/features/dictation/services/dictation-service";
 import { encodeWavPcm16 } from "@/features/dictation/utils/encode-wav";
 import type { DictationStatus } from "@/features/dictation/hooks/use-dictation";
+import {
+  classifyGetUserMediaError,
+  classifyTranscriptionError,
+  dictationErrorMessage,
+} from "@/features/dictation/dictation-status";
 
 // Lazily-imported MicVAD type. The runtime import happens inside start() so the
 // heavy onnxruntime-web / Silero model is code-split out of the main bundle and
@@ -27,6 +32,8 @@ interface UseStreamingDictationResult {
   cancel: () => void;
   // Smoothed live speech level in the 0..1 range while recording (0 when idle).
   audioLevel: number;
+  // The last error shown to the user (null until one occurs / on a new start).
+  errorMessage: string | null;
 }
 
 // Sample rate of the audio MicVAD hands to onSpeechEnd (Silero VAD runs at 16k).
@@ -60,6 +67,8 @@ export function useStreamingDictation(
   const { t } = useTranslation();
   const [status, setStatus] = useState<DictationStatus>("idle");
   const [audioLevel, setAudioLevel] = useState(0);
+  // Last error message shown to the user; the mic button reads it for its tooltip.
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
 
   // Keep the latest callbacks in a ref so async VAD/HTTP closures always call the
   // current handlers without re-creating the VAD.
@@ -158,26 +167,6 @@ export function useStreamingDictation(
     }
   }, []);
 
-  // Map a transcription error to a user-facing message, mirroring the batch hook.
-  const transcriptionErrorMessage = useCallback(
-    (err: unknown): string => {
-      const resp = (
-        err as { response?: { status?: number; data?: { message?: string } } }
-      )?.response;
-      const serverMsg = resp?.data?.message;
-      if (serverMsg && serverMsg.trim().length > 0) {
-        // The server already explains the cause (e.g. provider 404, bad format,
-        // STT not configured) — show it verbatim.
-        return serverMsg;
-      }
-      if (resp?.status === 503 || resp?.status === 403) {
-        return t("Voice dictation is not configured");
-      }
-      return `${t("Transcription failed")}: ${(err as { message?: string })?.message ?? String(err)}`;
-    },
-    [t],
-  );
-
   // Handle one ended speech segment: encode to WAV and transcribe. Results are
   // buffered by seq and flushed in order. A single failed segment does NOT kill
   // the session: log + one notification, then advance past that seq so later
@@ -204,10 +193,14 @@ export function useStreamingDictation(
           if (epoch !== epochRef.current) return;
           // Log the full error for diagnosis (status + body + stack).
           console.error("[dictation] segment transcription failed", err);
-          notifications.show({
-            color: "red",
-            message: transcriptionErrorMessage(err),
+          const { code, serverMessage } = classifyTranscriptionError(err);
+          const detail = (err as { message?: string })?.message ?? String(err);
+          const message = dictationErrorMessage(code, t, {
+            serverMessage,
+            detail,
           });
+          notifications.show({ color: "red", message });
+          setErrorMessage(message);
           // Skip this seq so later segments can still flush in order.
           if (nextEmitSeqRef.current === seq) {
             nextEmitSeqRef.current += 1;
@@ -226,7 +219,7 @@ export function useStreamingDictation(
           }
         });
     },
-    [drainResults, transcriptionErrorMessage],
+    [drainResults, t],
   );
 
   const start = useCallback(async (): Promise<void> => {
@@ -236,6 +229,8 @@ export function useStreamingDictation(
     if (startingRef.current || vadRef.current || activeRef.current) return;
     if (status !== "idle") return;
     startingRef.current = true;
+    // Clear any stale error from a previous attempt.
+    setErrorMessage(null);
 
     // Notify the caller right when dictation begins (before any async work) so the
     // editor can snapshot the caret position.
@@ -354,10 +349,9 @@ export function useStreamingDictation(
       // actually runs.)
       console.error("[dictation] VAD init failed", err);
       const detail = (err as { message?: string })?.message ?? String(err);
-      notifications.show({
-        color: "red",
-        message: `${t("Could not start recording")}: ${detail}`,
-      });
+      const message = dictationErrorMessage("vad-init-failed", t, { detail });
+      notifications.show({ color: "red", message });
+      setErrorMessage(message);
       // Defensive: if MicVAD.new partially succeeded before throwing, make sure we
       // don't leak it.
       destroyVad();
@@ -379,19 +373,11 @@ export function useStreamingDictation(
     } catch (err) {
       // Always log the full error for diagnosis (name, message, stack).
       console.error("[dictation] VAD.start failed", err);
-      const name = (err as { name?: string })?.name;
       const detail = (err as { message?: string })?.message ?? String(err);
-      let message: string;
-      if (name === "NotAllowedError" || name === "SecurityError") {
-        message = t("Microphone access denied");
-      } else if (name === "NotFoundError" || name === "OverconstrainedError") {
-        message = t("No microphone found");
-      } else if (name === "NotReadableError" || name === "AbortError") {
-        message = t("Microphone is unavailable or already in use");
-      } else {
-        message = `${t("Could not start recording")}: ${detail}`;
-      }
+      const code = classifyGetUserMediaError(err);
+      const message = dictationErrorMessage(code, t, { detail });
       notifications.show({ color: "red", message });
+      setErrorMessage(message);
       activeRef.current = false;
       destroyVad();
       setStatus("idle");
@@ -470,5 +456,5 @@ export function useStreamingDictation(
     };
   }, [clearTimer, destroyVad]);
 
-  return { status, start, stop, cancel, audioLevel };
+  return { status, start, stop, cancel, audioLevel, errorMessage };
 }

apps/client/src/features/editor/atoms/editor-atoms.ts

@@ -1,6 +1,7 @@
 import { atom } from "jotai";
 import { Editor } from "@tiptap/core";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
+import type { DictationUnavailableReason } from "@/features/dictation/dictation-status";
 
 export const pageEditorAtom = atom<Editor | null>(null);
 
@@ -15,3 +16,15 @@ export const showLinkMenuAtom = atom(false);
 // Current page's edit mode — initialized from the user's saved preference on
 // first load, can be toggled locally without persisting to the server.
 export const currentPageEditModeAtom = atom<PageEditMode>(PageEditMode.Edit);
+
+// Whether the dictation mic can start, and (when it can't) the cause-specific
+// reason the mic button surfaces as a tooltip. Published by the page editor,
+// consumed by DictationGroup -> MicButton.
+export type DictationAvailability = {
+  isEditable: boolean;
+  reason: DictationUnavailableReason | null;
+};
+export const dictationAvailabilityAtom = atom<DictationAvailability>({
+  isEditable: false,
+  reason: null,
+});

apps/client/src/features/editor/components/fixed-toolbar/groups/dictation-group.test.tsx

@@ -0,0 +1,60 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, act } from "@testing-library/react";
+import { Provider, createStore } from "jotai";
+import { dictationAvailabilityAtom } from "@/features/editor/atoms/editor-atoms.ts";
+
+// Regression test for the byline mic staying stuck disabled (#311 / #309): on a
+// page the user can edit, the mic must un-grey once the body becomes editable.
+// #311 first fixed this by reading `editor.isEditable` via `useEditorState`; #309
+// superseded that with a reactive `dictationAvailabilityAtom` that page-editor
+// publishes (carrying both the editable gate AND the unavailable reason). The mic
+// now gates on `dictationAvailability.isEditable`, so a change to that atom must
+// re-render the group and flip the disabled state (jotai drives the subscription).
+
+// Detectable stand-in that surfaces the `disabled` prop the component computes.
+vi.mock("@/features/dictation/components/mic-button", () => ({
+  MicButton: ({ disabled }: any) => (
+    <button data-testid="mic" disabled={disabled} />
+  ),
+}));
+
+import { DictationGroup } from "./dictation-group";
+
+// Minimal editor stand-in matching the surface DictationGroup uses (handleStart /
+// handleText). The disabled gate no longer reads this — it reads the atom.
+function makeFakeEditor() {
+  return {
+    isEditable: false,
+    isDestroyed: false,
+    state: { selection: { from: 0, to: 0 }, doc: { content: { size: 0 } } },
+  } as any;
+}
+
+describe("DictationGroup editable reactivity (#309 atom / #311)", () => {
+  it("re-enables the mic when dictationAvailability flips isEditable false -> true", () => {
+    const editor = makeFakeEditor();
+    const store = createStore();
+    // Pre-sync: page editor publishes not-editable (with a reason).
+    store.set(dictationAvailabilityAtom, {
+      isEditable: false,
+      reason: "connecting",
+    });
+
+    const { getByTestId } = render(
+      <Provider store={store}>
+        <DictationGroup editor={editor} />
+      </Provider>,
+    );
+
+    // Not editable yet -> disabled (preserves the #218 pre-sync intent).
+    expect(getByTestId("mic").hasAttribute("disabled")).toBe(true);
+
+    // Collab sync -> page editor republishes editable; the atom change must
+    // re-render the group and enable the mic.
+    act(() => {
+      store.set(dictationAvailabilityAtom, { isEditable: true, reason: null });
+    });
+
+    expect(getByTestId("mic").hasAttribute("disabled")).toBe(false);
+  });
+});

apps/client/src/features/editor/components/fixed-toolbar/groups/dictation-group.tsx

@@ -1,7 +1,8 @@
 import { FC, useRef } from "react";
-import type { Editor } from "@tiptap/react";
+import { Editor } from "@tiptap/react";
 import { useAtomValue } from "jotai";
 import { workspaceAtom } from "@/features/user/atoms/current-user-atom.ts";
+import { dictationAvailabilityAtom } from "@/features/editor/atoms/editor-atoms.ts";
 import { MicButton } from "@/features/dictation/components/mic-button";
 
 interface Props {
@@ -16,6 +17,8 @@ export const DictationGroup: FC<Props> = ({ editor, color, iconSize }) => {
   const workspace = useAtomValue(workspaceAtom);
   const streamingDictation =
     workspace?.settings?.ai?.dictationStreaming === true;
+  // Cause-specific reason the mic is unavailable (published by the page editor).
+  const dictationAvailability = useAtomValue(dictationAvailabilityAtom);
   // Caret snapshot taken when dictation starts (where the first segment lands).
   const rangeRef = useRef<{ from: number; to: number } | null>(null);
   // Running insertion point: after each inserted segment we remember the caret
@@ -80,7 +83,8 @@ export const DictationGroup: FC<Props> = ({ editor, color, iconSize }) => {
       streaming={streamingDictation}
       onStart={handleStart}
       onText={handleText}
-      disabled={!editor.isEditable}
+      disabled={!dictationAvailability.isEditable}
+      unavailableReason={dictationAvailability.reason ?? undefined}
       color={color}
       iconSize={iconSize}
     />

apps/client/src/features/editor/editor-sync-state.test.ts

@@ -1,6 +1,10 @@
 import { describe, it, expect } from "vitest";
 import { WebSocketStatus } from "@hocuspocus/provider";
-import { isCollabSynced, isBodyEditable } from "./editor-sync-state";
+import {
+  isCollabSynced,
+  isBodyEditable,
+  computeDictationAvailability,
+} from "./editor-sync-state";
 
 describe("isCollabSynced", () => {
   it("is true only when Connected and synced", () => {
@@ -30,3 +34,77 @@ describe("isBodyEditable (pre-sync data-loss gate, #218)", () => {
     expect(isBodyEditable({ ...base, inEditMode: false })).toBe(false);
   });
 });
+
+describe("computeDictationAvailability (mic reason precedence, #309)", () => {
+  const base = {
+    editable: true,
+    inEditMode: true,
+    showStatic: false,
+    isDisconnected: false,
+  };
+
+  it("is available with no reason once synced (showStatic false)", () => {
+    expect(computeDictationAvailability(base)).toEqual({
+      isEditable: true,
+      reason: null,
+    });
+  });
+
+  it("reports 'offline' during pre-sync while disconnected", () => {
+    expect(
+      computeDictationAvailability({
+        ...base,
+        showStatic: true,
+        isDisconnected: true,
+      }),
+    ).toEqual({ isEditable: false, reason: "offline" });
+  });
+
+  it("reports 'connecting' during pre-sync while still connecting", () => {
+    expect(
+      computeDictationAvailability({
+        ...base,
+        showStatic: true,
+        isDisconnected: false,
+      }),
+    ).toEqual({ isEditable: false, reason: "connecting" });
+  });
+
+  it("reports 'read-only' without edit permission", () => {
+    expect(
+      computeDictationAvailability({ ...base, editable: false }),
+    ).toEqual({ isEditable: false, reason: "read-only" });
+  });
+
+  it("reports 'read-only' when not in edit mode", () => {
+    expect(
+      computeDictationAvailability({ ...base, inEditMode: false }),
+    ).toEqual({ isEditable: false, reason: "read-only" });
+  });
+
+  // Lack of edit permission takes precedence over the pre-sync reason: a
+  // read-only viewer who is ALSO inside the pre-sync window (showStatic) must
+  // still read "read-only", never "offline"/"connecting". This pins the
+  // `opts.editable &&` guard on the pre-sync branch.
+  it("prefers 'read-only' over pre-sync when a read-only viewer is disconnected", () => {
+    expect(
+      computeDictationAvailability({
+        editable: false,
+        inEditMode: true,
+        showStatic: true,
+        isDisconnected: true,
+      }),
+    ).toEqual({ isEditable: false, reason: "read-only" });
+  });
+
+  it("prefers 'read-only' over pre-sync when a read-only viewer is still connecting", () => {
+    expect(
+      computeDictationAvailability({
+        editable: false,
+        inEditMode: true,
+        showStatic: true,
+        isDisconnected: false,
+      }),
+    ).toEqual({ isEditable: false, reason: "read-only" });
+  });
+});

apps/client/src/features/editor/editor-sync-state.ts

@@ -1,4 +1,5 @@
 import { WebSocketStatus } from "@hocuspocus/provider";
+import type { DictationUnavailableReason } from "@/features/dictation/dictation-status";
 
 /**
  * The collab document is usable only once the provider is Connected AND has
@@ -30,3 +31,32 @@ export function isBodyEditable(opts: {
 }): boolean {
   return opts.editable && opts.inEditMode && !opts.showStatic;
 }
+
+/**
+ * Whether dictation can start and, when it can't, the cause-specific reason the
+ * mic button surfaces. Derives editability from `isBodyEditable` (the single,
+ * tested gate) so the published `isEditable` can never diverge from the actual
+ * body-editable state and make the tooltip lie (#309).
+ *
+ * `isDisconnected` is the caller's own boolean (collab connection is in the
+ * Disconnected state), passed in so this module stays free of the collab enum.
+ */
+export function computeDictationAvailability(opts: {
+  editable: boolean;
+  inEditMode: boolean;
+  showStatic: boolean;
+  isDisconnected: boolean;
+}): { isEditable: boolean; reason: DictationUnavailableReason | null } {
+  const isEditable = isBodyEditable({
+    editable: opts.editable,
+    inEditMode: opts.inEditMode,
+    showStatic: opts.showStatic,
+  });
+  if (isEditable) return { isEditable, reason: null };
+  // Permitted to edit and in edit mode but not yet synced (showStatic) → pre-sync.
+  if (opts.editable && opts.inEditMode && opts.showStatic) {
+    return { isEditable, reason: opts.isDisconnected ? "offline" : "connecting" };
+  }
+  // No edit permission or not in edit mode.
+  return { isEditable, reason: "read-only" };
+}

apps/client/src/features/editor/hooks/use-swap-height-reservation.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import type { RefObject } from "react";
+import { useSwapHeightReservation } from "./use-swap-height-reservation";
+
+// Controllable fake requestAnimationFrame. jsdom's rAF is timer-driven and hard
+// to step deterministically, so we install a manual queue: `tickRaf()` drains the
+// callbacks scheduled so far (a callback that reschedules enqueues a new one for
+// the NEXT tick), letting each test advance the release loop frame by frame.
+let rafQueue: Array<{ id: number; cb: FrameRequestCallback }> = [];
+let nextRafId = 1;
+let realRaf: typeof globalThis.requestAnimationFrame;
+let realCancel: typeof globalThis.cancelAnimationFrame;
+
+function tickRaf(): void {
+  const current = rafQueue;
+  rafQueue = [];
+  for (const { cb } of current) cb(0);
+}
+
+// A mutable stand-in for the live-content container. The hook only reads
+// `scrollHeight`, so tests drive the release condition by mutating this.
+function makeMenuRef(): {
+  ref: RefObject<HTMLElement | null>;
+  setScrollHeight: (h: number) => void;
+} {
+  const el = { scrollHeight: 0 };
+  return {
+    ref: { current: el } as unknown as RefObject<HTMLElement | null>,
+    setScrollHeight: (h: number) => {
+      el.scrollHeight = h;
+    },
+  };
+}
+
+const H = 1000;
+
+describe("useSwapHeightReservation", () => {
+  beforeEach(() => {
+    rafQueue = [];
+    nextRafId = 1;
+    realRaf = globalThis.requestAnimationFrame;
+    realCancel = globalThis.cancelAnimationFrame;
+    globalThis.requestAnimationFrame = ((cb: FrameRequestCallback) => {
+      const id = nextRafId++;
+      rafQueue.push({ id, cb });
+      return id;
+    }) as typeof globalThis.requestAnimationFrame;
+    globalThis.cancelAnimationFrame = ((id: number) => {
+      rafQueue = rafQueue.filter((e) => e.id !== id);
+    }) as typeof globalThis.cancelAnimationFrame;
+  });
+
+  afterEach(() => {
+    globalThis.requestAnimationFrame = realRaf;
+    globalThis.cancelAnimationFrame = realCancel;
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  // (a) reserve-on-swap: the captured height becomes `reservedHeight`, the value
+  // that drives the swap wrapper's minHeight. Captured while static is still up,
+  // then the swap flips showStatic; before any release frame runs the reservation
+  // is held at exactly H.
+  it("(a) holds the captured height as reservedHeight after the swap (drives minHeight)", () => {
+    const { ref, setScrollHeight } = makeMenuRef();
+    setScrollHeight(0); // live content not laid out yet -> release cannot fire.
+    const { result, rerender } = renderHook(
+      ({ showStatic }) => useSwapHeightReservation(showStatic, ref),
+      { initialProps: { showStatic: true } },
+    );
+
+    // Capture happens synchronously at the swap point (static still shown).
+    act(() => {
+      result.current.captureReservation(H);
+    });
+    // The swap flips to the live branch.
+    rerender({ showStatic: false });
+
+    expect(result.current.reservedHeight).toBe(H);
+  });
+
+  // (b) release when the live content is tall enough. Guard is `>=`: with
+  // liveHeight === H the reservation releases. This FAILS if the guard direction
+  // were `<` (liveHeight === H is not `< H`, so it would never release).
+  it("(b) releases once live content reaches the reserved height", () => {
+    const { ref, setScrollHeight } = makeMenuRef();
+    setScrollHeight(0);
+    const { result, rerender } = renderHook(
+      ({ showStatic }) => useSwapHeightReservation(showStatic, ref),
+      { initialProps: { showStatic: true } },
+    );
+
+    act(() => {
+      result.current.captureReservation(H);
+    });
+    rerender({ showStatic: false });
+    expect(result.current.reservedHeight).toBe(H); // still reserved (short live doc)
+
+    // Live editor finishes laying out to the reserved height.
+    setScrollHeight(H);
+    act(() => {
+      tickRaf();
+    });
+
+    expect(result.current.reservedHeight).toBeNull();
+  });
+
+  // (c) cap escape: the live content never reaches the reserved height, so the
+  // height match never fires; the reservation must still release at the 4000ms
+  // cap (no stuck reservation / dead space). This FAILS if there were no cap: the
+  // loop would poll forever while scrollHeight stays below H.
+  it("(c) releases at the 4000ms cap when live content stays too short", () => {
+    // Only fake Date so `Date.now()` (the cap clock) is controllable; leave our
+    // manual rAF queue in place (default fake timers would replace it).
+    vi.useFakeTimers({ toFake: ["Date"] });
+    vi.setSystemTime(0);
+    const { ref, setScrollHeight } = makeMenuRef();
+    setScrollHeight(H - 100); // always shorter than reserved -> height match never fires.
+    const { result, rerender } = renderHook(
+      ({ showStatic }) => useSwapHeightReservation(showStatic, ref),
+      { initialProps: { showStatic: true } },
+    );
+
+    act(() => {
+      result.current.captureReservation(H);
+    });
+    rerender({ showStatic: false });
+
+    // A few frames pass but time has not reached the cap: still reserved.
+    act(() => {
+      tickRaf();
+    });
+    act(() => {
+      tickRaf();
+    });
+    expect(result.current.reservedHeight).toBe(H);
+
+    // Advance past the cap; the next frame releases even though the live content
+    // is still shorter than the reservation.
+    vi.setSystemTime(4001);
+    act(() => {
+      tickRaf();
+    });
+
+    expect(result.current.reservedHeight).toBeNull();
+  });
+
+  // (d) non-swap: without a capture (and while static is shown) there is no
+  // reservation and the release loop never arms, so no rAF is scheduled.
+  it("(d) reserves nothing and arms no loop when the swap never happens", () => {
+    const { ref } = makeMenuRef();
+    const { result } = renderHook(() =>
+      useSwapHeightReservation(true, ref),
+    );
+
+    expect(result.current.reservedHeight).toBeNull();
+    expect(rafQueue.length).toBe(0); // release loop never armed
+    act(() => {
+      tickRaf();
+    });
+    expect(result.current.reservedHeight).toBeNull();
+  });
+});

apps/client/src/features/editor/hooks/use-swap-height-reservation.ts

@@ -0,0 +1,79 @@
+import { RefObject, useCallback, useEffect, useState } from "react";
+
+// Last-resort release deadline. The primary release is the live-content height
+// match below; this cap only exists so a slow/short live doc can never pin the
+// reservation forever. It is generous (well past when the live content normally
+// reaches the reserved height — it renders the SAME content as the static copy)
+// so a slow load doesn't release mid-render and reintroduce the collapse.
+const RELEASE_CAP_MS = 4000;
+
+/**
+ * Reserves the document height across the static -> live editor swap.
+ *
+ * The live editor lays out its content over a few frames, so replacing the
+ * (full-height) static copy with it momentarily shrinks the document; the
+ * browser then clamps window scroll to the top, which yanked the reader off
+ * their restored reading position (and threw their scroll to 0 if they were
+ * scrolling at that moment). Pinning a min-height on the swap wrapper keeps the
+ * document tall through the swap so the scroll position simply survives (#266).
+ * `reservedHeight === null` means no reservation is active.
+ *
+ * The capture is intentionally a CALLBACK the page editor invokes, NOT something
+ * this hook derives by watching `showStatic`. The height MUST be read
+ * synchronously while the static content is still mounted (full natural height),
+ * right before the flip to the live branch. By the time any post-transition
+ * effect here could run, `showStatic` is already false and the wrapper shows the
+ * live/collapsed content, so `offsetHeight` would be wrong. So page-editor calls
+ * `captureReservation(wrapper.offsetHeight)` inside its collab-sync effect,
+ * before `setShowStatic(false)`, preserving that exact timing.
+ *
+ * @param showStatic       whether the static (cached) content is still shown.
+ * @param menuContainerRef the live-branch content container. It is a descendant
+ *   of the swap wrapper inside the live branch, so its `scrollHeight` is the live
+ *   content height (not inflated by the ancestor min-height reservation).
+ */
+export function useSwapHeightReservation(
+  showStatic: boolean,
+  menuContainerRef: RefObject<HTMLElement | null>,
+): {
+  reservedHeight: number | null;
+  captureReservation: (height: number | null) => void;
+} {
+  const [reservedHeight, setReservedHeight] = useState<number | null>(null);
+
+  // Capture the current (static, full-height) content height BEFORE the swap so
+  // the wrapper can reserve it while the live editor lays out — otherwise the
+  // transient shrink clamps window scroll to the top. The caller reads
+  // `offsetHeight` synchronously at the swap point and hands it here.
+  const captureReservation = useCallback(
+    (height: number | null) => setReservedHeight(height),
+    [],
+  );
+
+  // Release the reserved height once the live editor's content has laid out to
+  // at least the reserved height (so removing the reservation cannot collapse
+  // the document). The primary release is that height match; the cap is only a
+  // last-resort so we never pin forever. A shorter-than-reserved live doc (rare:
+  // stale/longer cache) releases at the cap, leaving only harmless bottom dead
+  // space until then.
+  useEffect(() => {
+    if (showStatic || reservedHeight == null) return;
+    let raf = 0;
+    const startedAt = Date.now();
+    const check = () => {
+      const liveHeight = menuContainerRef.current?.scrollHeight ?? 0;
+      if (
+        liveHeight >= reservedHeight ||
+        Date.now() - startedAt > RELEASE_CAP_MS
+      ) {
+        setReservedHeight(null);
+        return;
+      }
+      raf = requestAnimationFrame(check);
+    };
+    raf = requestAnimationFrame(check);
+    return () => cancelAnimationFrame(raf);
+  }, [showStatic, reservedHeight, menuContainerRef]);
+
+  return { reservedHeight, captureReservation };
+}

apps/client/src/features/editor/page-editor.tsx

@@ -27,11 +27,12 @@ import {
   collabExtensions,
   mainExtensions,
 } from "@/features/editor/extensions/extensions";
-import { useAtom, useAtomValue } from "jotai";
+import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import useCollaborationUrl from "@/features/editor/hooks/use-collaboration-url";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom";
 import {
   currentPageEditModeAtom,
+  dictationAvailabilityAtom,
   pageEditorAtom,
   yjsConnectionStatusAtom,
 } from "@/features/editor/atoms/editor-atoms";
@@ -79,6 +80,7 @@ import { jwtDecode } from "jwt-decode";
 import { searchSpotlight } from "@/features/search/constants.ts";
 import { useEditorScroll } from "./hooks/use-editor-scroll";
 import { useScrollRestoreOnSwap } from "./hooks/use-scroll-position";
+import { useSwapHeightReservation } from "./hooks/use-swap-height-reservation";
 import { EditorLinkMenu } from "@/features/editor/components/link/link-menu";
 import ColumnsMenu from "@/features/editor/components/columns/columns-menu.tsx";
 import { TransclusionLookupProvider } from "@/features/editor/components/transclusion/transclusion-lookup-context";
@@ -87,6 +89,7 @@ import { PageEmbedAncestryProvider } from "@/features/editor/components/page-emb
 import PageEmbedPicker from "@/features/editor/components/page-embed/page-embed-picker";
 import { useTranslation } from "react-i18next";
 import {
+  computeDictationAvailability,
   isBodyEditable,
   isCollabSynced,
 } from "@/features/editor/editor-sync-state";
@@ -138,6 +141,7 @@ export default function PageEditor({
   const { pageSlug } = useParams();
   const slugId = extractPageSlugId(pageSlug);
   const currentPageEditMode = useAtomValue(currentPageEditModeAtom);
+  const setDictationAvailability = useSetAtom(dictationAvailabilityAtom);
   const canScroll = useCallback(
     () => Boolean(isComponentMounted.current && editorRef.current),
     [isComponentMounted],
@@ -449,6 +453,22 @@ export default function PageEditor({
   const hasConnectedOnceRef = useRef(false);
   const [showStatic, setShowStatic] = useState(true);
 
+  // Reserved height held across the static -> live editor swap. The live editor
+  // lays out its content over a few frames, so replacing the (full-height) static
+  // copy with it momentarily shrinks the document; the browser then clamps window
+  // scroll to the top, which yanked the reader off their restored reading position
+  // (and threw their scroll to 0 if they were scrolling at that moment). Pinning a
+  // min-height on the swap wrapper keeps the document tall through the swap so the
+  // scroll position simply survives. `null` = no reservation active.
+  const swapWrapperRef = useRef<HTMLDivElement | null>(null);
+  // Reserve/release wiring lives in the hook so its capture trigger and release
+  // guard/cap are directly unit-testable. Capture stays synchronous at the swap
+  // point (see the collab-sync effect below); the hook only owns the release.
+  const { reservedHeight, captureReservation } = useSwapHeightReservation(
+    showStatic,
+    menuContainerRef,
+  );
+
   useEffect(() => {
     const timeout = setTimeout(() => {
       if (yjsConnectionStatus === WebSocketStatus.Connecting || !isSynced) {
@@ -471,12 +491,36 @@ export default function PageEditor({
     );
   }, [currentPageEditMode, editor, editable, showStatic]);
 
+  // Publish whether dictation can start and, if not, the cause-specific reason
+  // the mic button surfaces. Recomputed on the same signals that drive body
+  // editability so the tooltip never lies about the current state.
+  useEffect(() => {
+    setDictationAvailability(
+      computeDictationAvailability({
+        editable,
+        inEditMode: currentPageEditMode === PageEditMode.Edit,
+        showStatic,
+        isDisconnected: yjsConnectionStatus === WebSocketStatus.Disconnected,
+      }),
+    );
+  }, [
+    editable,
+    currentPageEditMode,
+    showStatic,
+    yjsConnectionStatus,
+    setDictationAvailability,
+  ]);
+
   useEffect(() => {
     if (
       !hasConnectedOnceRef.current &&
       isCollabSynced(yjsConnectionStatus, isSynced)
     ) {
       hasConnectedOnceRef.current = true;
+      // Capture the current (static, full-height) content height BEFORE the swap
+      // so the wrapper can reserve it while the live editor lays out — otherwise
+      // the transient shrink clamps window scroll to the top.
+      captureReservation(swapWrapperRef.current?.offsetHeight ?? null);
       setShowStatic(false);
     }
   }, [yjsConnectionStatus, isSynced]);
@@ -490,6 +534,12 @@ export default function PageEditor({
     <TransclusionLookupProvider>
       <PageEmbedLookupProvider>
         <PageEmbedAncestryProvider hostPageId={pageId}>
+      <div
+        ref={swapWrapperRef}
+        style={
+          reservedHeight != null ? { minHeight: reservedHeight } : undefined
+        }
+      >
       {showStatic ? (
         <div style={{ position: "relative" }}>
           {/* Surface the pre-sync read-only window so edits typed before the
@@ -577,6 +627,7 @@ export default function PageEditor({
           ></div>
         </div>
       )}
+      </div>
         </PageEmbedAncestryProvider>
       </PageEmbedLookupProvider>
     </TransclusionLookupProvider>

apps/client/src/features/page-history/components/history-item.tsx

@@ -1,6 +1,6 @@
 import { Text, Group, UnstyledButton, Avatar, Tooltip } from "@mantine/core";
 import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
-import { AiAgentBadge } from "@/components/ui/ai-agent-badge.tsx";
+import { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
 import { formattedDate } from "@/lib/time";
 import classes from "./css/history.module.css";
 import clsx from "clsx";
@@ -99,12 +99,13 @@ const HistoryItem = memo(function HistoryItem({
           </>
         )}
 
-        {isAgentEdit && (
-          <AiAgentBadge
-            authorName={historyItem.lastUpdatedBy?.name}
+        {isAgentEdit && historyItem.agent && (
+          <AgentAvatarStack
+            agent={historyItem.agent}
+            launcher={historyItem.launcher}
             aiChatId={historyItem.lastUpdatedAiChatId}
-            // The history row owns the modal: close it when the badge deep-links
-            // into the chat (the badge no longer reaches into page-history).
+            // The history row owns the modal: close it when the stack deep-links
+            // into the chat (the stack no longer reaches into page-history).
             onActivate={() => setHistoryModalOpen(false)}
           />
         )}

apps/client/src/features/page-history/types/page.types.ts

@@ -1,3 +1,8 @@
+import type {
+  AgentInfo,
+  LauncherInfo,
+} from "@/components/ui/agent-avatar-stack.tsx";
+
 interface IPageHistoryUser {
   id: string;
   name: string;
@@ -24,4 +29,9 @@ export interface IPageHistory {
   // (when present) deep-links to the chat that produced the edit.
   lastUpdatedSource?: string;
   lastUpdatedAiChatId?: string | null;
+  // Server-normalized "agent avatar stack" provenance (#300), present only when
+  // lastUpdatedSource === "agent": `agent` is the front identity, `launcher` the
+  // human behind it (null for an external MCP agent).
+  agent?: AgentInfo | null;
+  launcher?: LauncherInfo | null;
 }

apps/client/src/features/page/components/temporary-note-banner.tsx

@@ -1,4 +1,11 @@
-import { Button, Group, Paper, Text } from "@mantine/core";
+import {
+  ActionIcon,
+  Button,
+  Group,
+  Paper,
+  Text,
+  Tooltip,
+} from "@mantine/core";
 import { IconClockHour4, IconTrash } from "@tabler/icons-react";
 import { useState } from "react";
 import { Trans, useTranslation } from "react-i18next";
@@ -70,7 +77,14 @@ export function TemporaryNoteBanner({ slugId }: TemporaryNoteBannerProps) {
   return (
     <Paper radius="sm" mb="md" px="md" py="xs" bg="orange.0">
       <Group justify="space-between" wrap="wrap" gap="sm">
-        <Group gap="xs" wrap="nowrap" style={{ flex: 1, minWidth: 0 }}>
+        {/* A non-zero flex-basis lets the outer wrap="wrap" drop the buttons to
+            their own row on narrow screens; flex:1 (basis 0) never wraps and
+            instead crushes the text into a one-word-per-line ladder. */}
+        <Group
+          gap="xs"
+          wrap="nowrap"
+          style={{ flex: "1 1 16rem", minWidth: 0 }}
+        >
           <IconClockHour4
             size={18}
             stroke={1.5}
@@ -87,28 +101,58 @@ export function TemporaryNoteBanner({ slugId }: TemporaryNoteBannerProps) {
           </Text>
         </Group>
         {canEdit && (
-          <Group gap="xs" wrap="nowrap">
-            <Button
-              size="xs"
-              variant="subtle"
-              color="red"
-              leftSection={<IconTrash size={16} />}
-              onClick={handleTrashNow}
-              loading={isDeleting}
-            >
-              {t("Move to trash")}
-            </Button>
-            <Button
-              size="xs"
-              variant="light"
-              color="orange"
-              leftSection={<IconClockHour4 size={16} />}
-              onClick={handleMakePermanent}
-              loading={toggleTemporary.isPending}
-            >
-              {t("Make permanent")}
-            </Button>
-          </Group>
+          <>
+            {/* Desktop: full labeled buttons. */}
+            <Group gap="xs" wrap="nowrap" visibleFrom="sm">
+              <Button
+                size="xs"
+                variant="subtle"
+                color="red"
+                leftSection={<IconTrash size={16} />}
+                onClick={handleTrashNow}
+                loading={isDeleting}
+              >
+                {t("Move to trash")}
+              </Button>
+              <Button
+                size="xs"
+                variant="light"
+                color="orange"
+                leftSection={<IconClockHour4 size={16} />}
+                onClick={handleMakePermanent}
+                loading={toggleTemporary.isPending}
+              >
+                {t("Make permanent")}
+              </Button>
+            </Group>
+            {/* Mobile: icon-only actions so they never overflow the narrow row. */}
+            <Group gap="xs" wrap="nowrap" hiddenFrom="sm">
+              <Tooltip label={t("Move to trash")} withArrow>
+                <ActionIcon
+                  size="lg"
+                  variant="subtle"
+                  color="red"
+                  onClick={handleTrashNow}
+                  loading={isDeleting}
+                  aria-label={t("Move to trash")}
+                >
+                  <IconTrash size={18} />
+                </ActionIcon>
+              </Tooltip>
+              <Tooltip label={t("Make permanent")} withArrow>
+                <ActionIcon
+                  size="lg"
+                  variant="light"
+                  color="orange"
+                  onClick={handleMakePermanent}
+                  loading={toggleTemporary.isPending}
+                  aria-label={t("Make permanent")}
+                >
+                  <IconClockHour4 size={18} />
+                </ActionIcon>
+              </Tooltip>
+            </Group>
+          </>
         )}
       </Group>
     </Paper>

apps/client/src/features/page/tree/hooks/use-tree-mutation.ts

@@ -1,5 +1,5 @@
 import { useCallback } from "react";
-import { useAtom, useStore } from "jotai";
+import { useAtom, useSetAtom, useStore } from "jotai";
 import { notifications } from "@mantine/notifications";
 import { useTranslation } from "react-i18next";
 import { useNavigate, useParams } from "react-router-dom";
@@ -20,6 +20,7 @@ import {
 } from "@/features/page/queries/page-query.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
 import { getSpaceUrl } from "@/lib/config.ts";
+import { mobileSidebarAtom } from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
 
 export type UseTreeMutation = {
   handleMove: (sourceId: string, op: DropOp) => Promise<void>;
@@ -43,6 +44,7 @@ export function useTreeMutation(spaceId: string): UseTreeMutation {
   const removePageMutation = useRemovePageMutation();
   const movePageMutation = useMovePageMutation();
   const navigate = useNavigate();
+  const setMobileSidebar = useSetAtom(mobileSidebarAtom);
   const { spaceSlug, pageSlug } = useParams();
 
   const handleMove = useCallback(
@@ -201,8 +203,23 @@ export function useTreeMutation(spaceId: string): UseTreeMutation {
         createdPage.title,
       );
       navigate(pageUrl);
+      // On mobile the create action is triggered from inside the off-canvas
+      // sidebar drawer (space sidebar "+", tree-row "add subpage"). Navigating
+      // alone leaves that drawer open on top of the freshly created page, so the
+      // editor stays hidden behind the tree. Close it here so the new page opens
+      // in the editor — mirrors the row-click drawer-close in space-tree-row.
+      // No-op on desktop, where the mobile drawer atom is already false.
+      setMobileSidebar(false);
     },
-    [spaceId, createPageMutation, setData, store, navigate, spaceSlug],
+    [
+      spaceId,
+      createPageMutation,
+      setData,
+      store,
+      navigate,
+      spaceSlug,
+      setMobileSidebar,
+    ],
   );
 
   const handleRename = useCallback(

apps/client/src/lib/avatar-palette.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect } from "vitest";
+import {
+  PALETTE,
+  avatarStyle,
+  avatarBackgroundCss,
+  normalizeName,
+  minPairwiseDistance,
+  relativeLuminance,
+  contrastRatio,
+  oklchToSrgb,
+  isInGamut,
+} from "./avatar-palette";
+
+/** Parse "#rrggbb" into sRGB components on the 0..1 scale relativeLuminance expects. */
+function hexToRgb01(hex: string): [number, number, number] {
+  return [
+    parseInt(hex.slice(1, 3), 16) / 255,
+    parseInt(hex.slice(3, 5), 16) / 255,
+    parseInt(hex.slice(5, 7), 16) / 255,
+  ];
+}
+
+describe("avatar-palette validation", () => {
+  it("palette colors stay distinguishable", () => {
+    // 0.06 in OKLab is ~4-5 JNDs — safely distinct at avatar size. If a future
+    // RINGS tweak drops this, "almost identical" colors would reappear.
+    expect(minPairwiseDistance().distance).toBeGreaterThanOrEqual(0.06);
+    expect(PALETTE.length).toBe(20);
+  });
+
+  it("every palette entry is WCAG-readable and in sRGB gamut", () => {
+    // white text = luminance 1, black text = luminance 0 (per buildPalette).
+    const textLum = { white: 1, black: 0 } as const;
+    for (const entry of PALETTE) {
+      expect(entry.hex).toMatch(/^#[0-9a-f]{6}$/);
+
+      // (a) The chosen text color really clears the code's 3:1 threshold on the
+      // actual background hex — recomputed independently from the hex, not from
+      // the build-time luminance. A slot that picked the wrong text (or a color
+      // too dim for either text) would fail here.
+      const hexLum = relativeLuminance(hexToRgb01(entry.hex));
+      const chosen = contrastRatio(textLum[entry.text], hexLum);
+      expect(chosen).toBeGreaterThanOrEqual(3);
+      // buildPalette prefers white and only falls back to black when white
+      // fails 3:1. Mirror that decision: black is used *only* when white would
+      // not clear the threshold — so a mis-assigned "black" on a dark color
+      // (where white was fine) fails here.
+      if (entry.text === "black") {
+        expect(contrastRatio(textLum.white, hexLum)).toBeLessThan(3);
+      }
+
+      // (b) The entry's OKLCH is inside the sRGB gamut after chroma clamping;
+      // an out-of-gamut slot (e.g. un-clamped chroma) would produce components
+      // outside [0,1] and fail here.
+      expect(isInGamut(oklchToSrgb(entry.L, entry.C, entry.h))).toBe(true);
+    }
+  });
+});
+
+describe("avatarStyle", () => {
+  it("name-to-avatar mapping is frozen (golden values)", () => {
+    // Golden slice: if this breaks, all existing avatars change — make sure
+    // that is intentional (a config change in avatar-palette.ts).
+    const s = avatarStyle("Backend Developer");
+    expect([s.bg, s.bg2, s.angleDeg]).toEqual(["#a55795", "#90355e", 150]);
+    expect(s.text).toBe("white");
+  });
+
+  it("is deterministic and normalizes the name", () => {
+    expect(avatarStyle("Researcher")).toEqual(avatarStyle("Researcher"));
+    // Casing, surrounding and repeated whitespace must not change the avatar.
+    expect(avatarStyle("  RESEARCHER ")).toEqual(avatarStyle("researcher"));
+    expect(avatarStyle("Backend   Developer")).toEqual(
+      avatarStyle("backend developer"),
+    );
+    expect(normalizeName("  PM ")).toBe("pm");
+  });
+
+  it("returns a valid base color, angle and matching text", () => {
+    const s = avatarStyle("Нарратор");
+    const idx = PALETTE.findIndex((e) => e.hex === s.bg);
+    expect(idx).toBe(s.paletteIndex);
+    expect(idx).toBeGreaterThanOrEqual(0); // bg is a palette entry
+    // Text color comes from the chosen palette entry.
+    expect(s.text).toBe(PALETTE[idx].text);
+    // Split angle is one of the SPLIT_ANGLE_STEPS (24) directions → multiples of 15.
+    expect(s.angleDeg % 15).toBe(0);
+    expect(s.angleDeg).toBeGreaterThanOrEqual(0);
+    expect(s.angleDeg).toBeLessThan(360);
+  });
+
+  it("distinguishes the agents that used to collide as violet", () => {
+    // "Структурный редактор" and "Фактчекер" looked identically violet before.
+    expect(avatarStyle("Структурный редактор")).not.toEqual(
+      avatarStyle("Фактчекер"),
+    );
+  });
+});
+
+describe("avatarBackgroundCss", () => {
+  it("renders a two-stop gradient with a soft boundary", () => {
+    const s = avatarStyle("Backend Developer");
+    expect(avatarBackgroundCss(s)).toBe(
+      "linear-gradient(150deg, #a55795 42%, #90355e 58%)",
+    );
+  });
+});

apps/client/src/lib/avatar-palette.ts

@@ -0,0 +1,267 @@
+/**
+ * Deterministic avatar backgrounds for agent roles.
+ *
+ * The palette is generated from scratch at module load in OKLCH (a perceptually
+ * uniform color space), so every value below is tunable: change the ring
+ * configuration or the partner shifts and the whole palette regenerates.
+ *
+ * Pipeline: name -> normalize -> cyrb53 hash -> split into independent fields:
+ *   - base color index (one of the validated palette colors)
+ *   - partner hue shift: analogous 20..45deg (either side), complementary 180deg,
+ *     or triadic +/-120deg — classic color-wheel schemes; partner is also darker
+ *   - split angle (SPLIT_ANGLE_STEPS directions, soft boundary)
+ * The same name always yields the same avatar, on any platform, forever.
+ */
+
+// ------------------------- Tunable configuration -------------------------
+
+export interface RingConfig {
+  /** OKLCH lightness, 0..1 */
+  L: number;
+  /** OKLCH chroma target; clamped down per-hue to fit the sRGB gamut */
+  C: number;
+  /** Hue of the first color in the ring, degrees */
+  hueStart: number;
+  /** Number of evenly spaced hues in the ring */
+  count: number;
+}
+
+/**
+ * Two lightness rings. 12 light + 8 dark = 20 base colors with a validated
+ * min pairwise deltaE-OK of ~0.066 (clearly distinguishable at avatar size).
+ * Don't add more hues per ring without re-checking minPairwiseDistance():
+ * beyond ~20-24 colors humans stop telling them apart reliably.
+ */
+const RINGS: readonly RingConfig[] = [
+  { L: 0.70, C: 0.14, hueStart: 15, count: 12 }, // light ring
+  { L: 0.57, C: 0.13, hueStart: 20, count: 8 },  // darker ring
+];
+
+/** Partner color: lightness shifted by this much (negative = darker) */
+const PARTNER_L_SHIFT = -0.10;
+/** Analogous scheme: hue shift magnitude range, degrees (inclusive, 5-deg steps) */
+const ANALOG_MIN_SHIFT = 20;
+const ANALOG_SHIFT_STEP = 5;
+const ANALOG_SHIFT_STEPS = 6; // 20, 25, 30, 35, 40, 45
+/** Complementary scheme: fixed hue shift, degrees */
+const COMPLEMENTARY_SHIFT = 180;
+/** Triadic scheme: fixed hue shift magnitude, degrees (either side) */
+const TRIADIC_SHIFT = 120;
+/** Number of split directions (24 -> 15deg per step) */
+const SPLIT_ANGLE_STEPS = 24;
+/** Position of the color boundary, percent of the gradient axis */
+const SPLIT_PERCENT = 50;
+/** Width of the soft transition zone around the boundary, percent (0 = hard edge) */
+const SPLIT_SOFTNESS = 16;
+
+// ------------------------- OKLCH -> sRGB math -------------------------
+// Matrices from Bjorn Ottosson's OKLab reference implementation.
+
+function oklabToLinearSrgb(L: number, a: number, b: number): [number, number, number] {
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
+  const l = l_ ** 3, m = m_ ** 3, s = s_ ** 3;
+  return [
+    +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s,
+  ];
+}
+
+function gammaEncode(c: number): number {
+  return c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055;
+}
+
+export function oklchToSrgb(L: number, C: number, hDeg: number): [number, number, number] {
+  const h = (hDeg * Math.PI) / 180;
+  const [r, g, b] = oklabToLinearSrgb(L, C * Math.cos(h), C * Math.sin(h));
+  return [gammaEncode(r), gammaEncode(g), gammaEncode(b)];
+}
+
+export function isInGamut(rgb: readonly number[]): boolean {
+  return rgb.every((c) => c >= -1e-6 && c <= 1 + 1e-6);
+}
+
+/** Binary-search the max chroma <= C that fits into the sRGB gamut. */
+function clampChroma(L: number, C: number, hDeg: number): number {
+  if (isInGamut(oklchToSrgb(L, C, hDeg))) return C;
+  let lo = 0, hi = C;
+  for (let i = 0; i < 40; i++) {
+    const mid = (lo + hi) / 2;
+    if (isInGamut(oklchToSrgb(L, mid, hDeg))) lo = mid;
+    else hi = mid;
+  }
+  return lo;
+}
+
+function toHex(rgb: readonly number[]): string {
+  return (
+    "#" +
+    rgb
+      .map((c) => Math.round(Math.min(1, Math.max(0, c)) * 255).toString(16).padStart(2, "0"))
+      .join("")
+  );
+}
+
+/** WCAG relative luminance of an sRGB color (components 0..1). */
+export function relativeLuminance(rgb: readonly number[]): number {
+  const lin = rgb.map((c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4));
+  return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2];
+}
+
+export function contrastRatio(l1: number, l2: number): number {
+  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+}
+
+// ------------------------- Palette generation -------------------------
+
+export interface PaletteEntry {
+  /** Base background color */
+  hex: string;
+  /** OKLCH coordinates of the base color (used to derive partner colors) */
+  L: number;
+  C: number;
+  h: number;
+  /** Text/icon color with the best WCAG contrast on the base color */
+  text: "white" | "black";
+  /** OKLab coordinates of the base color (kept for validation) */
+  lab: readonly [number, number, number];
+}
+
+function buildPalette(): PaletteEntry[] {
+  const entries: PaletteEntry[] = [];
+  for (const ring of RINGS) {
+    const step = 360 / ring.count;
+    for (let i = 0; i < ring.count; i++) {
+      const h = (ring.hueStart + i * step) % 360;
+      const C = clampChroma(ring.L, ring.C, h);
+      const rgb = oklchToSrgb(ring.L, C, h);
+      const lum = relativeLuminance(rgb);
+      entries.push({
+        hex: toHex(rgb),
+        L: ring.L,
+        C,
+        h,
+        // White text needs >= 3:1 contrast; otherwise fall back to black.
+        text: contrastRatio(lum, 1) >= 3 ? "white" : "black",
+        lab: [
+          ring.L,
+          C * Math.cos((h * Math.PI) / 180),
+          C * Math.sin((h * Math.PI) / 180),
+        ],
+      });
+    }
+  }
+  return entries;
+}
+
+/** Partner color for the split: base hue shifted by shiftDeg, darker by PARTNER_L_SHIFT. */
+function partnerHex(entry: PaletteEntry, shiftDeg: number): string {
+  const h2 = (entry.h + shiftDeg + 360) % 360;
+  const L2 = entry.L + PARTNER_L_SHIFT;
+  return toHex(oklchToSrgb(L2, clampChroma(L2, entry.C, h2), h2));
+}
+
+/** Generated once at module load; regenerates on every build from the config above. */
+export const PALETTE: readonly PaletteEntry[] = buildPalette();
+
+// ------------------------- Name -> avatar style -------------------------
+
+/** Normalize so that "PM ", "pm" and "Pm" map to the same avatar. */
+export function normalizeName(name: string): string {
+  return name.normalize("NFC").trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+/**
+ * cyrb53: deterministic 53-bit string hash with good avalanche.
+ * Pure JS, cross-platform — never use language built-in hashing here.
+ */
+function cyrb53(str: string, seed = 0): number {
+  let h1 = 0xdeadbeef ^ seed;
+  let h2 = 0x41c6ce57 ^ seed;
+  for (let i = 0; i < str.length; i++) {
+    const ch = str.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+  return 4294967296 * (2097151 & h2) + (h1 >>> 0);
+}
+
+export interface AvatarStyle {
+  /** Index of the base color in PALETTE */
+  paletteIndex: number;
+  /** Base color hex */
+  bg: string;
+  /** Second color hex (split partner) */
+  bg2: string;
+  /** Signed hue shift of the partner, degrees (e.g. -35, +45, 180, -120) */
+  hueShift: number;
+  /** Direction of the split, degrees */
+  angleDeg: number;
+  /** Text/icon color for the base color */
+  text: "white" | "black";
+}
+
+/** Pure function: the same (normalized) name always returns the same style. */
+export function avatarStyle(agentName: string): AvatarStyle {
+  const h = cyrb53(normalizeName(agentName));
+  // Slice the hash into independent fields, like digits of a number:
+  const paletteIndex = h % PALETTE.length;
+  let rest = Math.floor(h / PALETTE.length);
+  const angleDeg = (rest % SPLIT_ANGLE_STEPS) * (360 / SPLIT_ANGLE_STEPS);
+  rest = Math.floor(rest / SPLIT_ANGLE_STEPS);
+  // Scheme: 0,1 -> analogous (minus/plus); 2 -> complementary; 3 -> triadic
+  const scheme = rest % 4;
+  rest = Math.floor(rest / 4);
+  let hueShift: number;
+  if (scheme === 2) {
+    hueShift = COMPLEMENTARY_SHIFT;
+  } else if (scheme === 3) {
+    hueShift = rest % 2 ? TRIADIC_SHIFT : -TRIADIC_SHIFT;
+  } else {
+    const magnitude = ANALOG_MIN_SHIFT + (rest % ANALOG_SHIFT_STEPS) * ANALOG_SHIFT_STEP;
+    hueShift = scheme === 0 ? -magnitude : magnitude;
+  }
+  const entry = PALETTE[paletteIndex];
+  return {
+    paletteIndex,
+    bg: entry.hex,
+    bg2: partnerHex(entry, hueShift),
+    hueShift,
+    angleDeg,
+    text: entry.text,
+  };
+}
+
+/** CSS background value: two colors with a slightly blurred boundary. */
+export function avatarBackgroundCss(style: AvatarStyle): string {
+  const from = SPLIT_PERCENT - SPLIT_SOFTNESS / 2;
+  const to = SPLIT_PERCENT + SPLIT_SOFTNESS / 2;
+  return `linear-gradient(${style.angleDeg}deg, ${style.bg} ${from}%, ${style.bg2} ${to}%)`;
+}
+
+// ------------------------- Validation -------------------------
+
+/**
+ * Min pairwise deltaE-OK (euclidean distance in OKLab) between base colors.
+ * Re-check after tweaking RINGS: keep it >= ~0.06 so no two palette colors
+ * look alike. Intended for a unit test or a dev-time assertion.
+ */
+export function minPairwiseDistance(): { distance: number; pair: [string, string] } {
+  let min = Infinity;
+  let pair: [string, string] = ["", ""];
+  for (let i = 0; i < PALETTE.length; i++) {
+    for (let j = i + 1; j < PALETTE.length; j++) {
+      const a = PALETTE[i].lab, b = PALETTE[j].lab;
+      const d = Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+      if (d < min) {
+        min = d;
+        pair = [PALETTE[i].hex, PALETTE[j].hex];
+      }
+    }
+  }
+  return { distance: min, pair };
+}

apps/server/src/collaboration/collaboration.gateway.spec.ts

@@ -0,0 +1,60 @@
+import { CollaborationGateway } from './collaboration.gateway';
+import { CollaborationHandler } from './collaboration.handler';
+
+/**
+ * Focused test for the COLLAB_DISABLE_REDIS fallback in handleYjsEvent.
+ *
+ * With Redis disabled the gateway builds no RedisSyncExtension, so the old code
+ * (`return this.redisSync?.handleEvent(...)`) returned undefined and every
+ * doc-mutation event silently no-opped. The fallback must instead invoke the
+ * handler locally against the single hocuspocus instance and return its verdict.
+ *
+ * We construct the gateway with stub extensions and an EnvironmentService whose
+ * isCollabDisableRedis() returns true (redisSync stays null, real hocuspocus is
+ * still built), then spy getHandlers so no real direct connection is opened.
+ */
+
+const stubExtension = {} as any;
+
+function makeEnv() {
+  return {
+    getRedisUrl: () => 'redis://localhost:6379',
+    isCollabDisableRedis: () => true,
+  } as any;
+}
+
+describe('CollaborationGateway.handleYjsEvent (no-Redis fallback)', () => {
+  it('invokes the handler locally and returns its verdict instead of undefined', async () => {
+    const collabHandler = new CollaborationHandler();
+    const verdict = { applied: true, currentText: 'new' };
+    const fakeHandler = jest.fn().mockResolvedValue(verdict);
+    // Bypass the real direct-connection code path — assert dispatch only.
+    jest
+      .spyOn(collabHandler, 'getHandlers')
+      .mockReturnValue({ applyCommentSuggestion: fakeHandler } as any);
+
+    const gateway = new CollaborationGateway(
+      stubExtension,
+      stubExtension,
+      stubExtension,
+      makeEnv(),
+      collabHandler,
+    );
+
+    const payload = {
+      commentId: 'c1',
+      expectedText: 'old',
+      newText: 'new',
+      user: { id: 'u1' } as any,
+    };
+    const result = await gateway.handleYjsEvent(
+      'applyCommentSuggestion' as any,
+      'doc-1',
+      payload as any,
+    );
+
+    expect(fakeHandler).toHaveBeenCalledWith('doc-1', payload);
+    expect(result).toEqual(verdict);
+    expect(result).not.toBeUndefined();
+  });
+});

apps/server/src/collaboration/collaboration.gateway.ts

@@ -147,8 +147,41 @@ export class CollaborationGateway {
     eventName: TName,
     documentName: string,
     payload: Parameters<CollabEventHandlers[TName]>[1],
-  ) {
-    return this.redisSync?.handleEvent(eventName, documentName, payload);
+  ): ReturnType<CollabEventHandlers[TName]> {
+    if (this.redisSync) {
+      // Normal path: the Redis bridge routes the event to the instance that owns
+      // the document (local or another worker) and carries the handler's return
+      // value back to us (customEventComplete + replyId).
+      return this.redisSync.handleEvent(
+        eventName,
+        documentName,
+        payload,
+      ) as ReturnType<CollabEventHandlers[TName]>;
+    }
+
+    // COLLAB_DISABLE_REDIS: there is no cross-process bridge, so a single local
+    // hocuspocus instance owns every document. Invoke the handler directly
+    // against it instead of returning undefined — otherwise doc-mutation events
+    // (setCommentMark / resolveCommentMark / applyCommentSuggestion) would
+    // silently no-op and, for suggestions, the caller could never learn the
+    // verdict. openDirectConnection loads the doc via the persistence extension
+    // if it is not already in memory.
+    if (this.hocuspocus) {
+      const handlers = this.collabEventsService.getHandlers(this.hocuspocus);
+      const handler = handlers[eventName] as (
+        documentName: string,
+        payload: unknown,
+      ) => ReturnType<CollabEventHandlers[TName]>;
+      return handler(documentName, payload);
+    }
+
+    // Collaboration was never initialized (no live instance). Fail loudly rather
+    // than silently dropping a mutation; phase 4's caller maps this to a 5xx.
+    throw new Error(
+      `Cannot handle collaboration event "${String(
+        eventName,
+      )}": requires a live collaboration instance`,
+    );
   }
 
   openDirectConnection(documentName: string, context?: any) {

apps/server/src/collaboration/collaboration.handler.spec.ts

@@ -0,0 +1,132 @@
+import * as Y from 'yjs';
+import { CollaborationHandler } from './collaboration.handler';
+import * as yjsUtil from './yjs.util';
+import { User } from '@docmost/db/types/entity.types';
+
+/**
+ * Unit tests for the `applyCommentSuggestion` collab handler (phase 3 of #315).
+ *
+ * The handler runs `replaceYjsMarkedText` inside the owning instance's Y
+ * transaction and returns the verdict to the caller. We exercise it against a
+ * REAL in-memory Y.Doc carrying a marked comment run, driven through a FAKE
+ * hocuspocus whose openDirectConnection().transact(fn) simply runs fn(doc) —
+ * mirroring how the real hocuspocus DirectConnection invokes the callback with
+ * the shared document (it does not forward the callback's return value, which is
+ * exactly why withYdocConnection captures it via a closure).
+ */
+
+// Build a Y.Doc with a single paragraph whose text carries a `comment` mark for
+// the given commentId — the shape `replaceYjsMarkedText` walks in production.
+function buildDocWithComment(text: string, commentId: string) {
+  const doc = new Y.Doc();
+  const fragment = doc.getXmlFragment('default');
+  const paragraph = new Y.XmlElement('paragraph');
+  const xmlText = new Y.XmlText();
+  xmlText.insert(0, text);
+  xmlText.format(0, text.length, { comment: { commentId, resolved: false } });
+  paragraph.insert(0, [xmlText]);
+  fragment.insert(0, [paragraph]);
+  return doc;
+}
+
+// Fake hocuspocus exposing only what withYdocConnection needs: a direct
+// connection whose transact() runs the callback against `doc`.
+function fakeHocuspocus(doc: Y.Doc) {
+  const connection = {
+    transact: jest.fn(async (fn: (d: Y.Doc) => void) => {
+      fn(doc);
+    }),
+    disconnect: jest.fn(async () => {}),
+  };
+  const hocuspocus = {
+    openDirectConnection: jest.fn(async () => connection),
+  } as any;
+  return { hocuspocus, connection };
+}
+
+const user = { id: 'u1' } as unknown as User;
+
+describe('CollaborationHandler.applyCommentSuggestion', () => {
+  it('applies the replacement and returns the verdict when the marked text matches', async () => {
+    const doc = buildDocWithComment('Hello world', 'c1');
+    const { hocuspocus, connection } = fakeHocuspocus(doc);
+    const handler = new CollaborationHandler();
+    const handlers = handler.getHandlers(hocuspocus);
+
+    const result = await handlers.applyCommentSuggestion('doc-1', {
+      commentId: 'c1',
+      expectedText: 'Hello world',
+      newText: 'Goodbye world',
+      user,
+    });
+
+    expect(result).toEqual({ applied: true, currentText: 'Goodbye world' });
+    // The mutation ran inside the transaction and hit the real doc.
+    expect(connection.transact).toHaveBeenCalledTimes(1);
+    expect(connection.disconnect).toHaveBeenCalledTimes(1);
+    expect(doc.getXmlFragment('default').toString()).toContain(
+      'Goodbye world',
+    );
+  });
+
+  it('rejects (applied=false) and returns the current text when it changed', async () => {
+    const doc = buildDocWithComment('Hello world', 'c1');
+    const { hocuspocus } = fakeHocuspocus(doc);
+    const handler = new CollaborationHandler();
+    const handlers = handler.getHandlers(hocuspocus);
+
+    const result = await handlers.applyCommentSuggestion('doc-1', {
+      commentId: 'c1',
+      expectedText: 'Stale expected text',
+      newText: 'Goodbye world',
+      user,
+    });
+
+    expect(result).toEqual({ applied: false, currentText: 'Hello world' });
+    // Nothing was replaced.
+    expect(doc.getXmlFragment('default').toString()).toContain(
+      'Hello world',
+    );
+  });
+
+  it('forwards the exact args to replaceYjsMarkedText and returns its result', async () => {
+    const doc = buildDocWithComment('abc', 'c9');
+    const { hocuspocus } = fakeHocuspocus(doc);
+    const spy = jest
+      .spyOn(yjsUtil, 'replaceYjsMarkedText')
+      .mockReturnValue({ applied: true, currentText: 'xyz' });
+    const handler = new CollaborationHandler();
+    const handlers = handler.getHandlers(hocuspocus);
+
+    const result = await handlers.applyCommentSuggestion('doc-1', {
+      commentId: 'c9',
+      expectedText: 'abc',
+      newText: 'xyz',
+      user,
+    });
+
+    expect(spy).toHaveBeenCalledWith(
+      doc.getXmlFragment('default'),
+      'c9',
+      'abc',
+      'xyz',
+    );
+    expect(result).toEqual({ applied: true, currentText: 'xyz' });
+    spy.mockRestore();
+  });
+
+  it('withYdocConnection returns the callback result (transact does not forward it)', async () => {
+    const doc = new Y.Doc();
+    const { hocuspocus } = fakeHocuspocus(doc);
+    const handler = new CollaborationHandler();
+
+    const value = await handler.withYdocConnection(
+      hocuspocus,
+      'doc-1',
+      {},
+      () => 42,
+    );
+
+    expect(value).toBe(42);
+  });
+});

apps/server/src/collaboration/collaboration.handler.ts

@@ -5,7 +5,12 @@ import {
   prosemirrorNodeToYElement,
   tiptapExtensions,
 } from './collaboration.util';
-import { setYjsMark, updateYjsMarkAttribute, YjsSelection } from './yjs.util';
+import {
+  replaceYjsMarkedText,
+  setYjsMark,
+  updateYjsMarkAttribute,
+  YjsSelection,
+} from './yjs.util';
 import * as Y from 'yjs';
 import { User } from '@docmost/db/types/entity.types';
 
@@ -73,6 +78,35 @@ export class CollaborationHandler {
           },
         );
       },
+      applyCommentSuggestion: async (
+        documentName: string,
+        payload: {
+          commentId: string;
+          expectedText: string;
+          newText: string;
+          user: User;
+        },
+      ): Promise<{ applied: boolean; currentText: string | null }> => {
+        const { commentId, expectedText, newText, user } = payload;
+        // Run the check-and-replace inside the owning instance's Y transaction so
+        // the delete+insert are atomic. The verdict from replaceYjsMarkedText is
+        // returned to the API-server caller (cross-process via the Redis bridge,
+        // or locally when Redis is disabled — see collaboration.gateway.ts).
+        return this.withYdocConnection(
+          hocuspocus,
+          documentName,
+          { user },
+          (doc) => {
+            const fragment = doc.getXmlFragment('default');
+            return replaceYjsMarkedText(
+              fragment,
+              commentId,
+              expectedText,
+              newText,
+            );
+          },
+        );
+      },
       updatePageContent: async (
         documentName: string,
         payload: {
@@ -115,18 +149,28 @@ export class CollaborationHandler {
     };
   }
 
-  async withYdocConnection(
+  async withYdocConnection<T>(
     hocuspocus: Hocuspocus,
     documentName: string,
     context: any = {},
-    fn: (doc: Document) => void,
-  ): Promise<void> {
+    // `fn` MUST be synchronous: hocuspocus `connection.transact(fn)` runs fn
+    // synchronously and does NOT await it, so any mutations after an `await`
+    // inside fn would execute OUTSIDE the Yjs transaction and lose atomicity.
+    fn: (doc: Document) => T,
+  ): Promise<T> {
     const connection = await hocuspocus.openDirectConnection(
       documentName,
       context,
     );
     try {
-      await connection.transact(fn);
+      // hocuspocus `connection.transact(fn)` invokes fn(document) but does NOT
+      // forward fn's return value, so we capture it in a closure and return it
+      // after the transaction (and its storeDocument hooks) resolve.
+      let result: T;
+      await connection.transact((doc) => {
+        result = fn(doc);
+      });
+      return result!;
     } finally {
       await connection.disconnect();
     }

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

@@ -10,6 +10,7 @@ import {
   setYjsMark,
   removeYjsMarkByAttribute,
   updateYjsMarkAttribute,
+  replaceYjsMarkedText,
   type YjsSelection,
 } from './yjs.util';
 
@@ -276,3 +277,256 @@ describe('updateYjsMarkAttribute', () => {
     expect(text.toDelta()).toEqual(before);
   });
 });
+
+describe('replaceYjsMarkedText', () => {
+  // Build a single-paragraph XmlText from runs. Insert the whole string as
+  // plain text FIRST, then format only the marked ranges — otherwise text
+  // inserted right after a marked run inherits its comment mark (Yjs carries
+  // formatting from the left insertion boundary).
+  function buildRuns(
+    runs: Array<{
+      text: string;
+      comment?: { commentId: string; resolved: boolean };
+    }>,
+  ): { 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.comment) {
+        text.format(offset, run.text.length, { comment: run.comment });
+      }
+      offset += run.text.length;
+    }
+    return { fragment, text };
+  }
+
+  // Two paragraphs, each with its own XmlText, both marked with the same
+  // commentId — mirrors a suggestion anchor that got split across blocks.
+  function buildTwoParagraphs(
+    a: { text: string; comment?: { commentId: string; resolved: boolean } },
+    b: { text: string; comment?: { commentId: string; resolved: boolean } },
+  ): { fragment: Y.XmlFragment; textA: Y.XmlText; textB: Y.XmlText } {
+    const ydoc = new Y.Doc();
+    const fragment = ydoc.getXmlFragment('default');
+    const build = (seg: typeof a) => {
+      const para = new Y.XmlElement('paragraph');
+      const text = new Y.XmlText();
+      para.insert(0, [text]);
+      text.insert(0, seg.text);
+      if (seg.comment) {
+        text.format(0, seg.text.length, { comment: seg.comment });
+      }
+      return { para, text };
+    };
+    const pa = build(a);
+    const pb = build(b);
+    fragment.insert(0, [pa.para, pb.para]);
+    return { fragment, textA: pa.text, textB: pb.text };
+  }
+
+  it('happy path: replaces marked text with newText and keeps the comment mark', () => {
+    const { fragment, text } = buildRuns([
+      { text: 'Hello ' },
+      { text: 'world', comment: { commentId: 'c1', resolved: false } },
+      { text: '!' },
+    ]);
+
+    const result = replaceYjsMarkedText(fragment, 'c1', 'world', 'planet');
+
+    expect(result).toEqual({ applied: true, currentText: 'planet' });
+    // New text carries the SAME comment mark; surrounding text is untouched.
+    expect(text.toDelta()).toEqual([
+      { insert: 'Hello ' },
+      {
+        insert: 'planet',
+        attributes: { comment: { commentId: 'c1', resolved: false } },
+      },
+      { insert: '!' },
+    ]);
+  });
+
+  it('matches by commentId even when the mark is resolved', () => {
+    const { fragment, text } = buildWithComments([
+      { text: 'foo', comment: { commentId: 'c9', resolved: true } },
+    ]);
+
+    const result = replaceYjsMarkedText(fragment, 'c9', 'foo', 'bar');
+
+    expect(result).toEqual({ applied: true, currentText: 'bar' });
+    expect(text.toDelta()).toEqual([
+      {
+        insert: 'bar',
+        attributes: { comment: { commentId: 'c9', resolved: true } },
+      },
+    ]);
+  });
+
+  it('changed text: marked text differs from expected → no-op, doc unchanged', () => {
+    const { fragment, text } = buildWithComments([
+      { text: 'abc', comment: { commentId: 'c1', resolved: false } },
+    ]);
+    const before = text.toDelta();
+
+    const result = replaceYjsMarkedText(fragment, 'c1', 'expected', 'new');
+
+    expect(result).toEqual({ applied: false, currentText: 'abc' });
+    expect(text.toDelta()).toEqual(before);
+  });
+
+  // F1 regression: the marked doc text is TYPOGRAPHIC (smart quotes / em-dash)
+  // and expectedText equals that raw typographic text — as it now does, because
+  // the MCP client stores the RAW anchored substring (getAnchoredText) rather
+  // than the agent's ASCII input. The strict `joinedText !== expectedText`
+  // compare must therefore MATCH and the suggestion apply (not a spurious 409).
+  it('typographic marked text applies when expectedText is the raw typographic text', () => {
+    const marked = '“hello”—world';
+    const { fragment, text } = buildRuns([
+      { text: 'say ' },
+      { text: marked, comment: { commentId: 'c1', resolved: false } },
+      { text: '!' },
+    ]);
+
+    const result = replaceYjsMarkedText(fragment, 'c1', marked, 'bye');
+
+    expect(result).toEqual({ applied: true, currentText: 'bye' });
+    expect(text.toDelta()).toEqual([
+      { insert: 'say ' },
+      {
+        insert: 'bye',
+        attributes: { comment: { commentId: 'c1', resolved: false } },
+      },
+      { insert: '!' },
+    ]);
+  });
+
+  it('anchor deleted: no mark with that commentId → { applied: false, currentText: null }', () => {
+    const { fragment, text } = buildWithComments([
+      { text: 'abc', comment: { commentId: 'c1', resolved: false } },
+    ]);
+    const before = text.toDelta();
+
+    const result = replaceYjsMarkedText(fragment, 'missing', 'abc', 'new');
+
+    expect(result).toEqual({ applied: false, currentText: null });
+    expect(text.toDelta()).toEqual(before);
+  });
+
+  it('paragraph split: same commentId in two XmlText nodes → no-op, doc unchanged', () => {
+    const { fragment, textA, textB } = buildTwoParagraphs(
+      { text: 'Hello ', comment: { commentId: 'c1', resolved: false } },
+      { text: 'world', comment: { commentId: 'c1', resolved: false } },
+    );
+    const beforeA = textA.toDelta();
+    const beforeB = textB.toDelta();
+
+    const result = replaceYjsMarkedText(fragment, 'c1', 'Hello world', 'new');
+
+    expect(result).toEqual({ applied: false, currentText: 'Hello world' });
+    expect(textA.toDelta()).toEqual(beforeA);
+    expect(textB.toDelta()).toEqual(beforeB);
+  });
+
+  it('interleaved unmarked text: marked run not contiguous → no-op, doc unchanged', () => {
+    const { fragment, text } = buildRuns([
+      { text: 'abc', comment: { commentId: 'c1', resolved: false } },
+      { text: 'X' },
+      { text: 'def', comment: { commentId: 'c1', resolved: false } },
+    ]);
+    const before = text.toDelta();
+
+    const result = replaceYjsMarkedText(fragment, 'c1', 'abcdef', 'new');
+
+    // Joined marked text ("abcdef") is returned, but the run is not contiguous.
+    expect(result).toEqual({ applied: false, currentText: 'abcdef' });
+    expect(text.toDelta()).toEqual(before);
+  });
+
+  it('preserves surrounding text and merges adjacent marked segments on apply', () => {
+    // The marked run itself is split into two adjacent delta segments; they must
+    // be treated as one contiguous run and replaced as a whole.
+    const { fragment, text } = buildRuns([
+      { text: 'pre ' },
+      { text: 'ab', comment: { commentId: 'c1', resolved: false } },
+      { text: 'cd', comment: { commentId: 'c1', resolved: false } },
+      { text: ' post' },
+    ]);
+
+    const result = replaceYjsMarkedText(fragment, 'c1', 'abcd', 'Z');
+
+    expect(result).toEqual({ applied: true, currentText: 'Z' });
+    expect(text.toDelta()).toEqual([
+      { insert: 'pre ' },
+      {
+        insert: 'Z',
+        attributes: { comment: { commentId: 'c1', resolved: false } },
+      },
+      { insert: ' post' },
+    ]);
+  });
+
+  it('embed before the marked run: offset accounts for the embed unit → replaces the right text, embed intact', () => {
+    // "AB", then a Yjs embed (1 index unit), then marked "world". Before the
+    // fix the embed was skipped WITHOUT advancing offset, so the computed start
+    // for "world" was too low by 1 → delete/insert would have hit the embed/text
+    // instead of "world", mangling the embed. With the fix offset is correct.
+    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, 'AB');
+    text.insertEmbed(2, { image: { src: 'x' } });
+    text.insert(3, 'world');
+    text.format(3, 'world'.length, {
+      comment: { commentId: 'c1', resolved: false },
+    });
+
+    const result = replaceYjsMarkedText(fragment, 'c1', 'world', 'planet');
+
+    expect(result).toEqual({ applied: true, currentText: 'planet' });
+    // "AB" untouched, embed still present and intact, "world" → "planet"
+    // carrying the SAME comment mark.
+    expect(text.toDelta()).toEqual([
+      { insert: 'AB' },
+      { insert: { image: { src: 'x' } } },
+      {
+        insert: 'planet',
+        attributes: { comment: { commentId: 'c1', resolved: false } },
+      },
+    ]);
+  });
+
+  it('embed inside the marked run: embed splits the run → non-contiguous → no-op, doc unchanged', () => {
+    // marked "abc", an embed, marked "def" — same commentId. The embed occupies
+    // one index unit between the two marked segments, so they are not contiguous
+    // → the guard rejects it and nothing is mutated (embed intact).
+    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, 'abc');
+    text.insertEmbed(3, { image: { src: 'y' } });
+    text.insert(4, 'def');
+    text.format(0, 'abc'.length, {
+      comment: { commentId: 'c1', resolved: false },
+    });
+    text.format(4, 'def'.length, {
+      comment: { commentId: 'c1', resolved: false },
+    });
+    const before = text.toDelta();
+
+    const result = replaceYjsMarkedText(fragment, 'c1', 'abcdef', 'new');
+
+    expect(result).toEqual({ applied: false, currentText: 'abcdef' });
+    expect(text.toDelta()).toEqual(before);
+  });
+});

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

@@ -133,6 +133,137 @@ export function removeYjsMarkByAttribute(
   }
 }
 
+/**
+ * A single marked delta segment collected during the walk, together with the
+ * Y.XmlText node that owns it, the segment's start offset within that node,
+ * and the full `comment` mark attributes object (needed to re-attach the mark
+ * to the replacement text).
+ */
+type MarkedSegment = {
+  node: Y.XmlText;
+  offset: number;
+  length: number;
+  text: string;
+  markAttrs: Record<string, any>;
+};
+
+/**
+ * Atomically check-and-replace the text currently under a comment mark.
+ *
+ * Walks the fragment collecting every delta segment whose `comment` mark has the
+ * given commentId. The replacement is applied ONLY if the marked run is intact:
+ * it lives in a single Y.XmlText node, is contiguous (no unmarked text spliced
+ * into the middle), and its joined text still equals `expectedText`. On success
+ * the run is deleted and `newText` is inserted at the same offset carrying the
+ * SAME comment attributes, so the comment thread stays anchored to the new text.
+ *
+ * This mutates the passed fragment/text directly and does NOT open its own Y
+ * transaction — the caller is expected to wrap the call in connection.transact()
+ * so the delete+insert are atomic (mirrors updateYjsMarkAttribute's direct
+ * mutation style).
+ *
+ * @returns `{ applied: true, currentText: newText }` on replacement, otherwise
+ * `{ applied: false, currentText }` where currentText is the text currently
+ * under the mark (or null when the mark/anchor no longer exists).
+ */
+export function replaceYjsMarkedText(
+  fragment: Y.XmlFragment,
+  commentId: string,
+  expectedText: string,
+  newText: string,
+): { applied: boolean; currentText: string | null } {
+  // 1. Collect every marked segment in document order.
+  const segments: MarkedSegment[] = [];
+
+  const processItem = (item: any) => {
+    if (item instanceof Y.XmlText) {
+      const deltas = item.toDelta();
+      let offset = 0;
+
+      for (const delta of deltas) {
+        const insert = delta.insert;
+        // Non-string inserts (embeds) carry no text length we can splice on.
+        if (typeof insert !== 'string') {
+          // A Yjs embed occupies one unit in the index space used by delete/
+          // insert/format — advance offset so a marked segment after an embed
+          // gets the right position (and an embed inside a marked run creates a
+          // gap → the contiguity guard rejects it as a changed anchor).
+          offset += 1;
+          continue;
+        }
+        const length = insert.length;
+        const attributes = delta.attributes ?? {};
+        const markAttr = attributes['comment'];
+
+        if (markAttr && markAttr.commentId === commentId) {
+          segments.push({
+            node: item,
+            offset,
+            length,
+            text: insert,
+            markAttrs: markAttr,
+          });
+        }
+        offset += length;
+      }
+    } else if (item instanceof Y.XmlElement) {
+      for (let i = 0; i < item.length; i++) {
+        processItem(item.get(i));
+      }
+    }
+  };
+
+  for (let i = 0; i < fragment.length; i++) {
+    processItem(fragment.get(i));
+  }
+
+  const joinedText = segments.map((s) => s.text).join('');
+
+  // 2a. No segments — the mark/anchor was deleted.
+  if (segments.length === 0) {
+    return { applied: false, currentText: null };
+  }
+
+  // 2b. Segments span more than one Y.XmlText node (paragraph split by Enter,
+  // or the mark bled across blocks) — treat as changed.
+  const node = segments[0].node;
+  const sameNode = segments.every((s) => s.node === node);
+  if (!sameNode) {
+    return { applied: false, currentText: joinedText };
+  }
+
+  // 2c. Non-contiguous within the single node: unmarked text is spliced between
+  // the first and last marked segment. Since collected segments are in document
+  // order, contiguity holds iff each segment starts where the previous ended.
+  let contiguous = true;
+  for (let i = 1; i < segments.length; i++) {
+    if (segments[i].offset !== segments[i - 1].offset + segments[i - 1].length) {
+      contiguous = false;
+      break;
+    }
+  }
+  if (!contiguous) {
+    return { applied: false, currentText: joinedText };
+  }
+
+  // 2d. The text under the mark changed.
+  if (joinedText !== expectedText) {
+    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.
+  const start = segments[0].offset;
+  const len = segments.reduce((sum, s) => sum + s.length, 0);
+  const markAttrs = segments[0].markAttrs;
+
+  node.delete(start, len);
+  node.insert(start, newText, { comment: markAttrs });
+
+  return { applied: true, currentText: newText };
+}
+
 /**
  * Updates a mark's attributes for all text that has the specified attribute value.
  * Useful for resolving/unresolving comments by commentId.

apps/server/src/common/events/audit-events.ts

@@ -51,6 +51,7 @@ export const AuditEvent = {
   COMMENT_UPDATED: 'comment.updated',
   COMMENT_RESOLVED: 'comment.resolved',
   COMMENT_REOPENED: 'comment.reopened',
+  COMMENT_SUGGESTION_APPLIED: 'comment.suggestion_applied',
 
   // Page
   PAGE_CREATED: 'page.created',

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

@@ -2,43 +2,91 @@ import { AiChatController } from './ai-chat.controller';
 import type { User, Workspace } from '@docmost/db/types/entity.types';
 
 /**
- * Wiring spec for the #191 `POST /ai-chat/bound-chat` endpoint. It must forward
- * the requesting user + workspace + pageId to findLatestByPage and return the
- * matched chat's id, or `{ chatId: null }` when there is none. The repo already
- * scopes to the caller's OWN chats, so a foreign pageId simply yields no match
- * (null) — no extra page-access check is needed. Exercised with hand-rolled
- * mocks, no Nest graph and no DB.
+ * Wiring spec for the #191 `POST /ai-chat/bound-chat` endpoint, hardened for
+ * #312. `dto.pageId` carries either a page slugId (10-char nanoid, off a slug
+ * URL) or a page uuid, so the controller must FIRST resolve it to a real page
+ * uuid via PageRepo.findById (which accepts both) — passing the raw slugId into
+ * the uuid ai_chats.page_id column caused a Postgres 22P02 500. Only then is the
+ * caller's most-recent OWN chat for that page looked up (by the resolved uuid),
+ * and a page in a different workspace (or an unknown id) yields { chatId: null }
+ * without ever touching the chat lookup. Exercised with hand-rolled mocks, no
+ * Nest graph and no DB.
  */
 describe('AiChatController.boundChat', () => {
   const user = { id: 'u1' } as User;
   const workspace = { id: 'ws1' } as Workspace;
 
-  function makeController(chat: unknown) {
+  function makeController(opts: { page: unknown; chat?: unknown }) {
     const aiChatRepo = {
-      findLatestByPage: jest.fn().mockResolvedValue(chat),
+      findLatestByPage: jest.fn().mockResolvedValue(opts.chat),
+    };
+    const pageRepo = {
+      findById: jest.fn().mockResolvedValue(opts.page),
     };
     const controller = new AiChatController(
       {} as never,
       aiChatRepo as never,
       {} as never,
       {} as never,
+      pageRepo as never,
     );
-    return { controller, aiChatRepo };
+    return { controller, aiChatRepo, pageRepo };
   }
 
-  it('returns the owned chat id and scopes the lookup to user + workspace + page', async () => {
-    const { controller, aiChatRepo } = makeController({
-      id: 'c1',
-      creatorId: 'u1',
+  it('resolves a slugId to the page uuid and returns the owned chat id', async () => {
+    const { controller, aiChatRepo, pageRepo } = makeController({
+      // findById accepts a slugId and returns the page with its real uuid.
+      page: { id: 'page-uuid-1', workspaceId: 'ws1' },
+      chat: { id: 'c1', creatorId: 'u1' },
     });
-    const res = await controller.boundChat({ pageId: 'p1' }, user, workspace);
-    expect(aiChatRepo.findLatestByPage).toHaveBeenCalledWith('u1', 'ws1', 'p1');
+    // The client sends a 10-char nanoid slugId, NOT a uuid.
+    const res = await controller.boundChat(
+      { pageId: 'i82qXsivsx' },
+      user,
+      workspace,
+    );
+    expect(pageRepo.findById).toHaveBeenCalledWith('i82qXsivsx');
+    // findLatestByPage must receive the RESOLVED uuid, never the raw slugId.
+    expect(aiChatRepo.findLatestByPage).toHaveBeenCalledWith(
+      'u1',
+      'ws1',
+      'page-uuid-1',
+    );
     expect(res).toEqual({ chatId: 'c1' });
   });
 
-  it('returns { chatId: null } for a page with no owned chat (incl. foreign pageId)', async () => {
-    const { controller } = makeController(undefined);
-    const res = await controller.boundChat({ pageId: 'foreign' }, user, workspace);
+  it('returns { chatId: null } for a page in a DIFFERENT workspace without a chat lookup', async () => {
+    const { controller, aiChatRepo, pageRepo } = makeController({
+      page: { id: 'page-uuid-2', workspaceId: 'other-ws' },
+    });
+    const res = await controller.boundChat(
+      { pageId: 'foreignSlug' },
+      user,
+      workspace,
+    );
+    expect(pageRepo.findById).toHaveBeenCalledWith('foreignSlug');
+    // No cross-workspace leak: the chat lookup must never run.
+    expect(aiChatRepo.findLatestByPage).not.toHaveBeenCalled();
+    expect(res).toEqual({ chatId: null });
+  });
+
+  it('returns { chatId: null } for an unknown id without throwing or looking up a chat', async () => {
+    const { controller, aiChatRepo } = makeController({ page: undefined });
+    const res = await controller.boundChat(
+      { pageId: 'does-not-exist' },
+      user,
+      workspace,
+    );
+    expect(aiChatRepo.findLatestByPage).not.toHaveBeenCalled();
+    expect(res).toEqual({ chatId: null });
+  });
+
+  it('returns { chatId: null } when the resolved page has no owned chat', async () => {
+    const { controller } = makeController({
+      page: { id: 'page-uuid-3', workspaceId: 'ws1' },
+      chat: undefined,
+    });
+    const res = await controller.boundChat({ pageId: 'p3' }, user, workspace);
     expect(res).toEqual({ chatId: null });
   });
 });

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

@@ -56,6 +56,7 @@ describe('AiChatController.export', () => {
       aiChatRepo as never,
       aiChatMessageRepo as never,
       {} as never,
+      {} as never,
     );
     return { controller, aiChatRepo, aiChatMessageRepo };
   }

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

@@ -24,6 +24,7 @@ import { AiChat, User, Workspace } from '@docmost/db/types/entity.types';
 import { PaginationOptions } from '@docmost/db/pagination/pagination-options';
 import { AiChatRepo } from '@docmost/db/repos/ai-chat/ai-chat.repo';
 import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
+import { PageRepo } from '@docmost/db/repos/page/page.repo';
 import { UserThrottlerGuard } from '../../integrations/throttle/user-throttler.guard';
 import { AI_CHAT_THROTTLER } from '../../integrations/throttle/throttler-names';
 import { FileInterceptor } from '../../common/interceptors/file.interceptor';
@@ -55,6 +56,7 @@ export class AiChatController {
     private readonly aiChatRepo: AiChatRepo,
     private readonly aiChatMessageRepo: AiChatMessageRepo,
     private readonly aiTranscription: AiTranscriptionService,
+    private readonly pageRepo: PageRepo,
   ) {}
 
   /** List the requesting user's chats in this workspace (paginated). */
@@ -71,9 +73,15 @@ export class AiChatController {
   /**
    * Resolve the chat bound to a document for the requesting user: the most-recent
    * non-deleted chat created on that page (ai_chats.page_id). Returns
-   * { chatId: null } when the page has no owned chat (-> a fresh chat). No page
-   * access check needed: only the caller's OWN chats are matched, so a foreign
-   * pageId reveals nothing.
+   * { chatId: null } when the page has no owned chat (-> a fresh chat).
+   *
+   * `dto.pageId` carries EITHER a page slugId (10-char nanoid, sent by the client
+   * off a slug URL) OR a page uuid, so it must be resolved to a real page uuid
+   * before it touches the uuid ai_chats.page_id column — passing a slugId straight
+   * through triggered a Postgres 22P02 "invalid input syntax for type uuid" 500
+   * (#312). PageRepo.findById accepts both forms. The workspace guard rejects an
+   * unknown or cross-workspace page (-> { chatId: null }) so a foreign id cannot
+   * probe another workspace's chats. Only the caller's OWN chats are then matched.
    */
   @HttpCode(HttpStatus.OK)
   @Post('bound-chat')
@@ -82,10 +90,14 @@ export class AiChatController {
     @AuthUser() user: User,
     @AuthWorkspace() workspace: Workspace,
   ): Promise<{ chatId: string | null }> {
+    const page = await this.pageRepo.findById(dto.pageId); // accepts slugId OR uuid
+    if (!page || page.workspaceId !== workspace.id) {
+      return { chatId: null }; // unknown or foreign-workspace page — no binding, no leak
+    }
     const chat = await this.aiChatRepo.findLatestByPage(
       user.id,
       workspace.id,
-      dto.pageId,
+      page.id, // the real uuid, never the incoming slugId
     );
     return { chatId: chat?.id ?? null };
   }

apps/server/src/core/ai-chat/ai-chat.generate-page-title.spec.ts

@@ -60,6 +60,7 @@ describe('AiChatController.generatePageTitle', () => {
       {} as never,
       {} as never,
       {} as never,
+      {} as never,
     );
     return { controller, aiChatService };
   }

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

@@ -27,7 +27,11 @@ const SAFETY_FRAMEWORK = [
   '- You can read pages, comments and page history, and modify the workspace:',
   '  create/rename/move pages and make structural edits (text, nodes, tables);',
   '  manage page history (diff/restore); copy, import and export content; and',
-  '  create/resolve comments. Page edits are REVERSIBLE — they keep page',
+  '  create/resolve comments. An inline comment can carry a suggestedText — a',
+  '  proposed replacement for its selected text that the user applies with one',
+  '  click; when you propose a concrete rewording of a specific fragment,',
+  '  attach it as suggestedText instead of only describing the change. Page',
+  '  edits are REVERSIBLE — they keep page',
   '  history and a trashed page can be restored. One exception to keep in mind:',
   '  sharing a page makes it PUBLICLY accessible — do that only when the user',
   '  asked.',

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

@@ -518,6 +518,20 @@ describe('AiChatToolsService model-friendly input validation (#190)', () => {
     });
   });
 
+  it('createComment: accepts an optional suggestedText alongside a selection', async () => {
+    const tools = await buildTools();
+    const result = await inputSchemaOf(tools.createComment).validate({
+      pageId: '019efe44-0000-0000-0000-000000000000',
+      content: 'A remark',
+      selection: 'титановый проводник',
+      suggestedText: 'медный проводник',
+    });
+    expect(result.success).toBe(true);
+    expect(result.value).toMatchObject({
+      suggestedText: 'медный проводник',
+    });
+  });
+
   it('sharedTool-built tools (getOutline) also get the friendly message on a dropped pageId', async () => {
     const tools = await buildTools();
     const result = await inputSchemaOf(tools.getOutline).validate({});

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

@@ -173,6 +173,11 @@ export class AiChatToolsService {
       });
 
     return {
+      // INTENTIONAL per-transport divergence (not in the shared registry): this
+      // in-app search runs a semantic + keyword hybrid (RRF) with in-process
+      // access control and a tuned schema (limit 1-20); the standalone MCP
+      // `search` is a plain REST full-text search (limit up to 100). Different
+      // behaviour AND schema, so kept per-layer.
       searchPages: tool({
         description:
           'Search the wiki for pages relevant to a query. Combines exact ' +
@@ -298,7 +303,9 @@ export class AiChatToolsService {
       getPage: tool({
         description:
           'Fetch a single page as Markdown by its page id. Returns the page ' +
-          'title and its Markdown content.',
+          'title and its Markdown content. Inline <span data-comment-id> tags ' +
+          'in the markdown are comment highlight anchors (also present for ' +
+          'RESOLVED threads) — treat them as markup, not page text.',
         inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id (or slugId) of the page.'),
         }),
@@ -432,6 +439,10 @@ export class AiChatToolsService {
         },
       }),
 
+      // INTENTIONAL per-transport divergence (not shared): the description is
+      // tuned for the in-app agent (e.g. "retry with a corrected EXACT selection"
+      // and "Reversible via the comment UI"); the standalone MCP `create_comment`
+      // keeps its own wording. Kept per-layer.
       createComment: tool({
         description:
           'Add an INLINE comment to a page, or reply to an existing top-level ' +
@@ -441,8 +452,10 @@ export class AiChatToolsService {
           "new top-level comment REQUIRES a `selection`. Replies inherit the " +
           "parent's anchor and take no selection. If the call fails with a " +
           '"selection not found" error, retry with a corrected EXACT selection ' +
-          'copied verbatim from a single paragraph/block. Reversible via the ' +
-          'comment UI.',
+          'copied verbatim from a single paragraph/block. You may also attach a ' +
+          '`suggestedText` proposing a replacement for the `selection` (a human ' +
+          'applies it from the UI); when set, the `selection` must occur exactly ' +
+          'once in the page. Reversible via the comment UI.',
         inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page to comment on.'),
           content: z.string().describe('The comment body as Markdown.'),
@@ -464,24 +477,57 @@ export class AiChatToolsService {
               'Optional id of a TOP-LEVEL comment to reply to (one level ' +
                 'of replies only).',
             ),
+          suggestedText: z
+            .string()
+            .min(1)
+            .max(2000)
+            .optional()
+            .describe(
+              'Optional proposed replacement (PLAIN TEXT) for the `selection`, ' +
+                'applied by a human via the UI (never auto-applied). REQUIRES a ' +
+                '`selection`; NOT allowed on a reply. When set, the `selection` ' +
+                'must be UNIQUE in the page — expand it with surrounding context ' +
+                '(still <=250 chars) if it occurs more than once, or the call is ' +
+                'refused.',
+            ),
         }),
-        execute: async ({ pageId, content, selection, parentCommentId }) => {
-          // createComment(pageId, content, type, selection?, parentCommentId?).
-          // Top-level comments are inline and must carry a selection to anchor
-          // on; replies inherit the parent's anchor (no selection). Throwing
-          // here surfaces a tool error to the model (Vercel `ai` SDK) so the
-          // agent retries with a better selection — do not catch/suppress it.
+        execute: async ({
+          pageId,
+          content,
+          selection,
+          parentCommentId,
+          suggestedText,
+        }) => {
+          // createComment(pageId, content, type, selection?, parentCommentId?,
+          // suggestedText?). Top-level comments are inline and must carry a
+          // selection to anchor on; replies inherit the parent's anchor (no
+          // selection). Throwing here surfaces a tool error to the model (Vercel
+          // `ai` SDK) so the agent retries with a better selection — do not
+          // catch/suppress it.
           if (!parentCommentId && (!selection || !selection.trim())) {
             throw new Error(
               "createComment requires a 'selection' (exact text to anchor on) for a new top-level comment.",
             );
           }
+          if (suggestedText !== undefined) {
+            if (parentCommentId) {
+              throw new Error(
+                "createComment: 'suggestedText' cannot be attached to a reply; it applies only to a top-level inline comment.",
+              );
+            }
+            if (!selection || !selection.trim()) {
+              throw new Error(
+                "createComment: 'suggestedText' requires a 'selection' to anchor and rewrite.",
+              );
+            }
+          }
           const result = await client.createComment(
             pageId,
             content,
             'inline',
             selection,
             parentCommentId,
+            suggestedText,
           );
           const data = (result?.data ?? {}) as { id?: string };
           return { commentId: data.id, pageId };
@@ -519,6 +565,10 @@ export class AiChatToolsService {
         async () => await client.getSpaces(),
       ),
 
+      // INTENTIONAL per-transport divergence (not shared): keeps the `tree:true`
+      // hierarchy mode but is worded for the in-app agent; the standalone MCP
+      // `list_pages` carries its own wording. Kept per-layer so each side tunes
+      // its own guidance.
       listPages: tool({
         description:
           'List the most recent pages, optionally scoped to a single space. ' +
@@ -599,7 +649,9 @@ export class AiChatToolsService {
 
       listComments: tool({
         description:
-          'List all comments on a page (content as Markdown).',
+          'List ALL comments on a page in one call, including RESOLVED ' +
+          'threads — filter by resolvedAt when you need only open ones. ' +
+          'Content is returned as Markdown.',
         inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page.'),
         }),
@@ -692,85 +744,25 @@ export class AiChatToolsService {
         async ({ pageId }) => await client.stashPage(pageId),
       ),
 
-      patchNode: tool({
-        description:
-          'Replace a single content block (by id) with a new ProseMirror ' +
-          'node; the replacement keeps the same nodeId. Example node: a ' +
-          'paragraph {"type":"paragraph","content":[{"type":"text","text":"Hello"}]} ' +
-          'or a heading {"type":"heading","attrs":{"level":2},"content":' +
-          '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-          '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node arg ' +
-          'may be a JSON object or a JSON string (both accepted). Reversible: ' +
-          'the previous version is kept in page history.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page.'),
-          nodeId: z
-            .string()
-            .describe('The block id to replace (from getOutline/getPageJson).'),
-          node: z
-            .any()
-            .describe(
-              'The replacement ProseMirror node, e.g. ' +
-                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-                'JSON object or JSON string both accepted.',
-            ),
-        }),
-        execute: async ({ pageId, nodeId, node }) => {
-          // Parity with the standalone MCP server (index.ts patch_node): the
-          // model sometimes serializes the node as a JSON string. Parse it
-          // before the client's typeof-object guard rejects it.
+      // Schema + description from the shared registry (identical across both
+      // transports). The execute body keeps its OWN parseNodeArg normalization:
+      // the model sometimes serializes the node as a JSON string, and we parse it
+      // before the client's typeof-object guard rejects it (parity with the
+      // standalone MCP server, index.ts patch_node).
+      patchNode: sharedTool(
+        sharedToolSpecs.patchNode,
+        async ({ pageId, nodeId, node }) => {
           const parsedNode = parseNodeArg(node);
           return await client.patchNode(pageId, nodeId, parsedNode);
         },
-      }),
+      ),
 
-      insertNode: tool({
-        description:
-          'Insert a ProseMirror node relative to an anchor, or append it at ' +
-          'the top level. For before/after you MUST provide EXACTLY ONE of ' +
-          'anchorNodeId or anchorText. Example node: a paragraph ' +
-          '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
-          'heading {"type":"heading","attrs":{"level":2},"content":' +
-          '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-          '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node arg ' +
-          'may be a JSON object or a JSON string (both accepted). Reversible ' +
-          'via page history.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page.'),
-          node: z
-            .any()
-            .describe(
-              'The ProseMirror node to insert, e.g. ' +
-                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-                'JSON object or JSON string both accepted.',
-            ),
-          position: z
-            .enum(['before', 'after', 'append'])
-            .describe('Where to insert relative to the anchor.'),
-          anchorNodeId: z
-            .string()
-            .optional()
-            .describe('Anchor block id (for before/after).'),
-          anchorText: z
-            .string()
-            .optional()
-            .describe(
-              'Anchor text fragment (for before/after), matched against the ' +
-                "block's literal rendered plain text (no markdown). " +
-                'Markdown/emoji are tolerated as a fallback; prefer plain text ' +
-                'or anchorNodeId.',
-            ),
-        }),
-        execute: async ({
-          pageId,
-          node,
-          position,
-          anchorNodeId,
-          anchorText,
-        }) => {
-          // Parity with the standalone MCP server (index.ts insert_node): the
-          // model sometimes serializes the node as a JSON string. Parse it
-          // before the client's typeof-object guard rejects it.
+      // Shared registry schema + description; execute retains parseNodeArg on the
+      // incoming node (parity with the standalone MCP server, index.ts
+      // insert_node).
+      insertNode: sharedTool(
+        sharedToolSpecs.insertNode,
+        async ({ pageId, node, position, anchorNodeId, anchorText }) => {
           const parsedNode = parseNodeArg(node);
           return await client.insertNode(pageId, parsedNode, {
             position,
@@ -778,7 +770,7 @@ export class AiChatToolsService {
             anchorText,
           });
         },
-      }),
+      ),
 
       deleteNode: sharedTool(
         sharedToolSpecs.deleteNode,
@@ -821,6 +813,10 @@ export class AiChatToolsService {
         },
       }),
 
+      // NOT in the shared registry: this layer names the table argument
+      // `tableRef`, while the standalone MCP tool names it `table` (index.ts).
+      // Sharing one buildShape would rename a model-facing parameter on one
+      // transport, so the table row/cell tools stay per-layer by design.
       tableInsertRow: tool({
         description:
           'Insert a row of plain-text cells into a table. Reversible via ' +
@@ -841,6 +837,8 @@ export class AiChatToolsService {
           await client.tableInsertRow(pageId, tableRef, cells, index),
       }),
 
+      // NOT shared — same `tableRef` (here) vs `table` (MCP) parameter-name
+      // divergence as tableInsertRow.
       tableDeleteRow: tool({
         description:
           'Delete a table row at a 0-based index. Reversible via page history.',
@@ -855,6 +853,8 @@ export class AiChatToolsService {
           await client.tableDeleteRow(pageId, tableRef, index),
       }),
 
+      // NOT shared — same `tableRef` (here) vs `table` (MCP) parameter-name
+      // divergence as tableInsertRow.
       tableUpdateCell: tool({
         description:
           'Set the plain-text content of a table cell at [row, col] (0-based). ' +
@@ -884,6 +884,10 @@ export class AiChatToolsService {
           await client.importPageMarkdown(pageId, markdown),
       ),
 
+      // INTENTIONAL per-transport divergence (not shared): adds a security
+      // confirmation framing ("Only share when the user explicitly asked, since
+      // this exposes the page to anyone with the link") for the in-app agent; the
+      // standalone MCP `share_page` keeps the plain public-URL wording.
       sharePage: tool({
         description:
           'Make a page PUBLICLY accessible and return its public URL. ' +
@@ -910,6 +914,10 @@ export class AiChatToolsService {
         async ({ historyId }) => await client.restorePageVersion(historyId),
       ),
 
+      // INTENTIONAL per-transport divergence (not shared): deliberately omits the
+      // `deleteComments` schema field (comment-deletion guardrail) and carries a
+      // much shorter description; the standalone MCP `docmost_transform` exposes
+      // the full helper catalogue. Different schema, so kept per-layer.
       transformPage: tool({
         description:
           'Run a sandboxed JS transform of the form `(doc, ctx) => doc` over a ' +

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

@@ -177,6 +177,7 @@ export interface DocmostClientLike {
     type?: 'page' | 'inline',
     selection?: string,
     parentCommentId?: string,
+    suggestedText?: string,
   ): Promise<{ data: Record<string, unknown>; success: boolean }>;
   resolveComment(
     commentId: string,

apps/server/src/core/ai-chat/tools/shared-tool-specs.contract.spec.ts

@@ -113,9 +113,15 @@ describe('SHARED_TOOL_SPECS contract parity', () => {
       const expectedKeys = Object.keys(shape).sort();
       expect(actualKeys).toEqual(expectedKeys);
 
-      // A non-.optional() field must surface as required in the advertised schema.
+      // A field that was NOT wrapped in `.optional()` must surface as required in
+      // the advertised schema. We test for the ZodOptional wrapper rather than
+      // `isOptional()`: `z.any()`/`z.unknown()` accept `undefined` and so report
+      // `isOptional() === true`, yet z.toJSONSchema still lists them under
+      // `required` (they carry no `.optional()`). Matching on the wrapper is what
+      // the emitted JSON schema actually does, so it stays correct for the
+      // registry's `node: z.any()` fields (patchNode/insertNode).
       const expectedRequired = Object.entries(shape)
-        .filter(([, field]) => !(field as z.ZodTypeAny).isOptional?.())
+        .filter(([, field]) => !(field instanceof z.ZodOptional))
         .map(([k]) => k)
         .sort();
       expect((json.required ?? []).slice().sort()).toEqual(expectedRequired);

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

@@ -0,0 +1,119 @@
+import {
+  ForbiddenException,
+  NotFoundException,
+} from '@nestjs/common';
+import { CommentController } from './comment.controller';
+
+/**
+ * Authz-gate tests for the apply-suggestion route. Applying a suggestion
+ * rewrites the page text, so the route MUST call
+ * pageAccessService.validateCanEdit BEFORE handing off to
+ * commentService.applySuggestion (which performs the document mutation + stamp).
+ * That ordering is a security boundary: an unauthorized user must never reach
+ * the mutation. These tests pin it against a fully mocked controller so any
+ * regression that drops the gate (or reorders it after the mutation) fails here.
+ */
+describe('CommentController apply-suggestion authz', () => {
+  function makeController() {
+    const commentService = {
+      applySuggestion: jest.fn(async () => ({ id: 'c-1', applied: true })),
+    };
+    const commentRepo = { findById: jest.fn() };
+    const pageRepo = { findById: jest.fn() };
+    const spaceAbility = {} as any;
+    const pageAccessService = {
+      validateCanEdit: jest.fn(async () => undefined),
+    };
+    const wsService = {} as any;
+    const auditService = { log: jest.fn() };
+
+    const controller = new CommentController(
+      commentService as any,
+      commentRepo as any,
+      pageRepo as any,
+      spaceAbility,
+      pageAccessService as any,
+      wsService,
+      auditService as any,
+    );
+    return {
+      controller,
+      commentService,
+      commentRepo,
+      pageRepo,
+      pageAccessService,
+    };
+  }
+
+  const user: any = { id: 'u-1' };
+  const workspace: any = { id: 'ws-1' };
+  const provenance: any = undefined;
+  const dto: any = { commentId: 'c-1' };
+
+  const comment = {
+    id: 'c-1',
+    pageId: 'p-1',
+    spaceId: 'sp-1',
+    suggestedText: 'new text',
+    selection: 'old text',
+  };
+  const page = { id: 'p-1', spaceId: 'sp-1', deletedAt: null };
+
+  it('validateCanEdit throwing Forbidden rejects AND applySuggestion is never called', async () => {
+    const { controller, commentRepo, pageRepo, pageAccessService, commentService } =
+      makeController();
+    commentRepo.findById.mockResolvedValue(comment);
+    pageRepo.findById.mockResolvedValue(page);
+    pageAccessService.validateCanEdit.mockRejectedValue(
+      new ForbiddenException('no edit access'),
+    );
+
+    await expect(
+      controller.applySuggestion(dto, user, workspace, provenance),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+
+    // The security boundary: the mutation/stamp must NOT run for an
+    // unauthorized user.
+    expect(pageAccessService.validateCanEdit).toHaveBeenCalledWith(page, user);
+    expect(commentService.applySuggestion).not.toHaveBeenCalled();
+  });
+
+  it('happy path: validateCanEdit resolves → applySuggestion is called and its result returned', async () => {
+    const { controller, commentRepo, pageRepo, pageAccessService, commentService } =
+      makeController();
+    commentRepo.findById.mockResolvedValue(comment);
+    pageRepo.findById.mockResolvedValue(page);
+    const applied = { id: 'c-1', applied: true };
+    commentService.applySuggestion.mockResolvedValue(applied);
+
+    const result = await controller.applySuggestion(
+      dto,
+      user,
+      workspace,
+      provenance,
+    );
+
+    // Authorization ran before the mutation, then the service was invoked.
+    expect(pageAccessService.validateCanEdit).toHaveBeenCalledWith(page, user);
+    expect(commentService.applySuggestion).toHaveBeenCalledWith(
+      comment,
+      user,
+      provenance,
+    );
+    expect(result).toBe(applied);
+  });
+
+  it('missing comment: NotFound is thrown without authorizing or applying', async () => {
+    const { controller, commentRepo, pageRepo, pageAccessService, commentService } =
+      makeController();
+    commentRepo.findById.mockResolvedValue(null);
+
+    await expect(
+      controller.applySuggestion(dto, user, workspace, provenance),
+    ).rejects.toBeInstanceOf(NotFoundException);
+
+    expect(pageRepo.findById).not.toHaveBeenCalled();
+    expect(pageAccessService.validateCanEdit).not.toHaveBeenCalled();
+    expect(commentService.applySuggestion).not.toHaveBeenCalled();
+  });
+});

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

@@ -14,6 +14,7 @@ import { CommentService } from './comment.service';
 import { CreateCommentDto } from './dto/create-comment.dto';
 import { UpdateCommentDto } from './dto/update-comment.dto';
 import { ResolveCommentDto } from './dto/resolve-comment.dto';
+import { ApplySuggestionDto } from './dto/apply-suggestion.dto';
 import { PageIdDto, CommentIdDto } from './dto/comments.input';
 import { AuthUser } from '../../common/decorators/auth-user.decorator';
 import { AuthWorkspace } from '../../common/decorators/auth-workspace.decorator';
@@ -197,6 +198,42 @@ export class CommentController {
     return updated;
   }
 
+  @HttpCode(HttpStatus.OK)
+  @Post('apply-suggestion')
+  async applySuggestion(
+    @Body() dto: ApplySuggestionDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+    @AuthProvenance() provenance: AuthProvenanceData,
+  ) {
+    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 any structural detail about the comment
+    // (metadata-disclosure hygiene). Applying a suggestion rewrites the page
+    // text, so require edit access (NOT just comment access). Running this
+    // first means a cross-workspace user with a guessed comment UUID gets a
+    // uniform 403 regardless of the comment's type or suggestion state — it can
+    // never distinguish those before the access check. The structural 400s
+    // (top-level / has-a-suggested-edit) are re-checked by the service below.
+    await this.pageAccessService.validateCanEdit(page, user);
+
+    // The service re-validates the comment's state, returns idempotent success
+    // for an already-applied suggestion, and lets ConflictException (409, with
+    // currentText in the payload) propagate untouched.
+    return this.commentService.applySuggestion(comment, user, provenance);
+  }
+
   @HttpCode(HttpStatus.OK)
   @Post('delete')
   async delete(@Body() input: CommentIdDto, @AuthUser() user: User, @AuthWorkspace() workspace: Workspace) {

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

@@ -0,0 +1,245 @@
+import {
+  BadRequestException,
+  ConflictException,
+  InternalServerErrorException,
+} from '@nestjs/common';
+import { CommentService } from './comment.service';
+import { AuditEvent, AuditResource } from '../../common/events/audit-events';
+
+/**
+ * Focused coverage for CommentService.applySuggestion (comment.service.ts).
+ * The service is constructed directly with jest-mocked deps (the @InjectQueue
+ * tokens can't be resolved by Test.createTestingModule — see the sibling specs).
+ *
+ * The collaboration gateway verdict is the pivot of the whole flow, so each test
+ * pins a specific { applied, currentText } and asserts the DB persistence,
+ * auto-resolve, audit, ws broadcast, and error mapping that follow from it.
+ */
+describe('CommentService — applySuggestion', () => {
+  const UPDATED = { id: 'c-1', __updated: true } as any;
+
+  function makeService(verdict: unknown) {
+    const commentRepo: any = {
+      // Both the applied-stamp re-read and resolveComment's re-read go through
+      // findById; return a recognizable enriched row.
+      findById: jest.fn(async () => UPDATED),
+      updateComment: jest.fn(async () => undefined),
+    };
+    const pageRepo: any = {};
+    const wsService: any = { emitCommentEvent: jest.fn() };
+    const collaborationGateway: any = {
+      handleYjsEvent: jest.fn(async () => verdict),
+    };
+    const generalQueue: any = { add: jest.fn(() => Promise.resolve()) };
+    const notificationQueue: any = { add: jest.fn(async () => undefined) };
+    const auditService: any = { log: jest.fn() };
+
+    const service = new CommentService(
+      commentRepo,
+      pageRepo,
+      wsService,
+      collaborationGateway,
+      generalQueue,
+      notificationQueue,
+      auditService,
+    );
+
+    return {
+      service,
+      commentRepo,
+      wsService,
+      collaborationGateway,
+      auditService,
+    };
+  }
+
+  const suggestionComment = (over?: Partial<any>): any => ({
+    id: 'c-1',
+    pageId: 'page-1',
+    spaceId: 'space-1',
+    workspaceId: 'ws-1',
+    creatorId: 'user-1',
+    parentCommentId: null,
+    selection: 'old text',
+    suggestedText: 'new text',
+    suggestionAppliedAt: null,
+    resolvedAt: null,
+    ...over,
+  });
+  const user = (over?: Partial<any>): any => ({ id: 'user-1', ...over });
+
+  // Pull the updateComment patch that carries the applied stamps.
+  const appliedPatch = (commentRepo: any) =>
+    commentRepo.updateComment.mock.calls
+      .map((c: any[]) => c[0])
+      .find((patch: any) => 'suggestionAppliedAt' in patch);
+
+  it('applied=true → replaces text, persists applied stamps, auto-resolves, audits, returns updated', async () => {
+    const { service, commentRepo, wsService, collaborationGateway, auditService } =
+      makeService({ applied: true, currentText: 'new text' });
+
+    const result = await service.applySuggestion(suggestionComment(), user());
+
+    // The atomic replace was requested against the exact marked text.
+    expect(collaborationGateway.handleYjsEvent).toHaveBeenCalledWith(
+      'applyCommentSuggestion',
+      'page.page-1',
+      expect.objectContaining({
+        commentId: 'c-1',
+        expectedText: 'old text',
+        newText: 'new text',
+        user: expect.objectContaining({ id: 'user-1' }),
+      }),
+    );
+
+    // Applied stamps persisted.
+    const patch = appliedPatch(commentRepo);
+    expect(patch.suggestionAppliedAt).toBeInstanceOf(Date);
+    expect(patch.suggestionAppliedById).toBe('user-1');
+
+    // Auto-resolved: resolveComment writes a resolvedAt/resolvedById patch too.
+    const resolvePatch = commentRepo.updateComment.mock.calls
+      .map((c: any[]) => c[0])
+      .find((p: any) => 'resolvedAt' in p);
+    expect(resolvePatch.resolvedAt).toBeInstanceOf(Date);
+    expect(resolvePatch.resolvedById).toBe('user-1');
+
+    // Audit + broadcast + return.
+    expect(auditService.log).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event: AuditEvent.COMMENT_SUGGESTION_APPLIED,
+        resourceType: AuditResource.COMMENT,
+        resourceId: 'c-1',
+        spaceId: 'space-1',
+        metadata: { pageId: 'page-1' },
+      }),
+    );
+    expect(wsService.emitCommentEvent).toHaveBeenCalledWith(
+      'space-1',
+      'page-1',
+      expect.objectContaining({ operation: 'commentUpdated', comment: UPDATED }),
+    );
+    expect(result).toBe(UPDATED);
+  });
+
+  it('applied=false but currentText === suggestedText → idempotent success (no 409)', async () => {
+    const { service, commentRepo, auditService } = makeService({
+      applied: false,
+      currentText: 'new text',
+    });
+
+    const result = await service.applySuggestion(suggestionComment(), user());
+
+    // The stamps are still persisted (reconciling a crash between the doc
+    // mutation and the DB write) and the call succeeds.
+    const patch = appliedPatch(commentRepo);
+    expect(patch.suggestionAppliedAt).toBeInstanceOf(Date);
+    expect(patch.suggestionAppliedById).toBe('user-1');
+    expect(auditService.log).toHaveBeenCalledTimes(1);
+    expect(result).toBe(UPDATED);
+  });
+
+  it('applied=false and currentText differs → ConflictException with currentText in payload', async () => {
+    const { service, commentRepo, auditService } = makeService({
+      applied: false,
+      currentText: 'someone else edited this',
+    });
+
+    const err = await service
+      .applySuggestion(suggestionComment(), user())
+      .catch((e) => e);
+
+    expect(err).toBeInstanceOf(ConflictException);
+    expect(err.getResponse()).toMatchObject({
+      currentText: 'someone else edited this',
+    });
+    // No persistence and no audit on a conflict.
+    expect(appliedPatch(commentRepo)).toBeUndefined();
+    expect(auditService.log).not.toHaveBeenCalled();
+  });
+
+  it('already-applied AND already-resolved → idempotent success, no collab call, no re-resolve (#315 double-click)', async () => {
+    const { service, collaborationGateway, commentRepo, auditService } =
+      makeService({ applied: true, currentText: 'new text' });
+
+    const result = await service.applySuggestion(
+      suggestionComment({
+        suggestionAppliedAt: new Date(),
+        resolvedAt: new Date(),
+        resolvedById: 'user-1',
+      }),
+      user(),
+    );
+
+    // Idempotent SUCCESS, not a 409. The suggestion is already applied, so the
+    // collaborative document is never touched again and nothing is re-stamped
+    // or re-resolved.
+    expect(result).toBe(UPDATED);
+    expect(collaborationGateway.handleYjsEvent).not.toHaveBeenCalled();
+    expect(commentRepo.updateComment).not.toHaveBeenCalled();
+    // Same success shape as the applied path (broadcast + audit).
+    expect(auditService.log).toHaveBeenCalledTimes(1);
+  });
+
+  it('already-applied but NOT resolved (crash window) → idempotent success, self-heals resolve, no re-apply', async () => {
+    const { service, collaborationGateway, commentRepo } = makeService({
+      applied: true,
+      currentText: 'new text',
+    });
+
+    const result = await service.applySuggestion(
+      suggestionComment({ suggestionAppliedAt: new Date(), resolvedAt: null }),
+      user(),
+    );
+
+    expect(result).toBe(UPDATED);
+
+    // The suggestion is NOT re-applied to the document…
+    expect(collaborationGateway.handleYjsEvent).not.toHaveBeenCalledWith(
+      'applyCommentSuggestion',
+      expect.anything(),
+      expect.anything(),
+    );
+    // …but the open thread is self-healed to resolved via resolveComment, which
+    // writes the resolve patch and updates the resolve mark.
+    const resolvePatch = commentRepo.updateComment.mock.calls
+      .map((c: any[]) => c[0])
+      .find((p: any) => 'resolvedAt' in p);
+    expect(resolvePatch.resolvedAt).toBeInstanceOf(Date);
+    expect(resolvePatch.resolvedById).toBe('user-1');
+    expect(collaborationGateway.handleYjsEvent).toHaveBeenCalledWith(
+      'resolveCommentMark',
+      'page.page-1',
+      expect.objectContaining({ commentId: 'c-1', resolved: true }),
+    );
+    // The applied stamps are NOT re-written (already stamped).
+    expect(appliedPatch(commentRepo)).toBeUndefined();
+  });
+
+  it('rejects a comment with no suggestedText', async () => {
+    const { service, collaborationGateway } = makeService({
+      applied: true,
+      currentText: 'x',
+    });
+
+    await expect(
+      service.applySuggestion(
+        suggestionComment({ suggestedText: null }),
+        user(),
+      ),
+    ).rejects.toThrow(BadRequestException);
+    expect(collaborationGateway.handleYjsEvent).not.toHaveBeenCalled();
+  });
+
+  it('gateway returning undefined → hard error, not a silent success', async () => {
+    const { service, commentRepo, auditService } = makeService(undefined);
+
+    await expect(
+      service.applySuggestion(suggestionComment(), user()),
+    ).rejects.toThrow(InternalServerErrorException);
+
+    // Nothing persisted, nothing audited.
+    expect(appliedPatch(commentRepo)).toBeUndefined();
+    expect(auditService.log).not.toHaveBeenCalled();
+  });
+});

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

@@ -60,6 +60,7 @@ describe('CommentService — behavior', () => {
     };
     const generalQueue: any = { add: jest.fn(() => Promise.resolve()) };
     const notificationQueue: any = { add: jest.fn(async () => undefined) };
+    const auditService: any = { log: jest.fn() };
 
     const service = new CommentService(
       commentRepo,
@@ -68,14 +69,17 @@ describe('CommentService — behavior', () => {
       collaborationGateway,
       generalQueue,
       notificationQueue,
+      auditService,
     );
 
     return {
       service,
       commentRepo,
       wsService,
+      collaborationGateway,
       generalQueue,
       notificationQueue,
+      auditService,
     };
   }
 
@@ -181,6 +185,95 @@ describe('CommentService — behavior', () => {
     });
   });
 
+  describe('create — suggested edit validation & storage', () => {
+    it('rejects a suggestedText on a reply (not a top-level comment)', async () => {
+      const parentComment = {
+        id: 'parent-1',
+        pageId: 'page-1',
+        parentCommentId: null,
+      };
+      const { service, commentRepo } = makeService({ parentComment });
+
+      await expect(
+        service.create(
+          { page: page(), workspaceId: 'ws-1', user: user() },
+          {
+            content: JSON.stringify(docMentioning()),
+            parentCommentId: 'parent-1',
+            selection: 'hello world',
+            suggestedText: 'goodbye world',
+          } as any,
+        ),
+      ).rejects.toThrow(BadRequestException);
+
+      expect(commentRepo.insertComment).not.toHaveBeenCalled();
+    });
+
+    it('rejects a suggestedText without a selection', async () => {
+      const { service, commentRepo } = makeService();
+
+      await expect(
+        service.create(
+          { page: page(), workspaceId: 'ws-1', user: user() },
+          {
+            content: JSON.stringify(docMentioning()),
+            suggestedText: 'new text',
+          } as any,
+        ),
+      ).rejects.toThrow(BadRequestException);
+
+      expect(commentRepo.insertComment).not.toHaveBeenCalled();
+    });
+
+    it('rejects a suggestedText identical to the selection (no-op)', async () => {
+      const { service, commentRepo } = makeService();
+
+      await expect(
+        service.create(
+          { page: page(), workspaceId: 'ws-1', user: user() },
+          {
+            content: JSON.stringify(docMentioning()),
+            selection: 'same text',
+            // Only differs by surrounding whitespace → still a no-op after trim.
+            suggestedText: '  same text  ',
+          } as any,
+        ),
+      ).rejects.toThrow(BadRequestException);
+
+      expect(commentRepo.insertComment).not.toHaveBeenCalled();
+    });
+
+    it('stores a valid suggestedText (trimmed) on the inserted row', async () => {
+      const { service, commentRepo } = makeService();
+
+      await service.create(
+        { page: page(), workspaceId: 'ws-1', user: user() },
+        {
+          content: JSON.stringify(docMentioning()),
+          selection: 'old text',
+          type: 'inline',
+          suggestedText: '  new text  ',
+        } as any,
+      );
+
+      const insertArg = commentRepo.insertComment.mock.calls[0][0];
+      expect(insertArg.suggestedText).toBe('new text');
+      expect(insertArg.selection).toBe('old text');
+    });
+
+    it('leaves suggestedText null for an ordinary comment', async () => {
+      const { service, commentRepo } = makeService();
+
+      await service.create(
+        { page: page(), workspaceId: 'ws-1', user: user() },
+        { content: JSON.stringify(docMentioning()) } as any,
+      );
+
+      const insertArg = commentRepo.insertComment.mock.calls[0][0];
+      expect(insertArg.suggestedText).toBeNull();
+    });
+  });
+
   describe('resolveComment — provenance & resolve notifications', () => {
     it('stamps resolvedSource:"agent" when an agent resolves', async () => {
       const { service, commentRepo } = makeService();

apps/server/src/core/comment/comment.service.provenance-broadcast.spec.ts

@@ -0,0 +1,240 @@
+import { CommentService } from './comment.service';
+
+/**
+ * Caller-contract coverage for the three live comment broadcasts (#300/#304):
+ *   - commentCreated   (create @153)
+ *   - commentUpdated   (update @214)  ← the fragile path this suite spotlights
+ *   - commentResolved  (resolveComment @283)
+ *
+ * All three must emit a payload carrying the {agent,launcher} avatar stack for an
+ * AGENT comment, and NEITHER field for a non-agent comment. The enrichment lives
+ * in CommentRepo.findById(..., {includeCreator:true}); the service contract these
+ * tests pin is that every broadcast reads its payload from that enriched
+ * single-row load rather than from an un-enriched object.
+ *
+ * NON-VACUITY for the update path: the service is handed an UN-enriched input
+ * comment (no agent/launcher), while findById returns the ENRICHED shape. The
+ * pre-#304 update() re-emitted the caller's object in place, so it would emit the
+ * un-enriched input and the `agent`/`launcher` assertions would FAIL. The fix
+ * re-fetches via findById, so the broadcast carries the stack regardless of how
+ * the caller pre-loaded the comment.
+ */
+describe('CommentService — broadcast carries the agent avatar stack', () => {
+  // An enriched agent comment as CommentRepo.findById(..., includeCreator:true)
+  // returns it: the {agent,launcher} pair is attached and agentRole is stripped.
+  const enrichedAgentComment = (over?: Record<string, unknown>) => ({
+    id: 'comment-new',
+    pageId: 'page-1',
+    spaceId: 'space-1',
+    workspaceId: 'ws-1',
+    content: { type: 'doc', content: [] },
+    createdSource: 'agent',
+    agent: { name: 'Researcher', emoji: '🔬', avatarUrl: null },
+    launcher: { name: 'Alice', avatarUrl: 'a.png' },
+    ...over,
+  });
+
+  // A plain human comment: findById attaches neither agent nor launcher.
+  const plainHumanComment = (over?: Record<string, unknown>) => ({
+    id: 'comment-new',
+    pageId: 'page-1',
+    spaceId: 'space-1',
+    workspaceId: 'ws-1',
+    content: { type: 'doc', content: [] },
+    createdSource: 'user',
+    ...over,
+  });
+
+  function makeService(findByIdReturn: unknown) {
+    const commentRepo: any = {
+      // In these flows findById is only the post-write enriched re-read
+      // (no parentCommentId is set, so no parent lookup path is taken).
+      findById: jest.fn(async () => findByIdReturn),
+      insertComment: jest.fn(async () => ({ id: 'comment-new' })),
+      updateComment: jest.fn(async () => undefined),
+    };
+    const pageRepo: any = {};
+    const wsService: any = { emitCommentEvent: jest.fn() };
+    const collaborationGateway: any = {
+      handleYjsEvent: jest.fn(async () => undefined),
+    };
+    const generalQueue: any = { add: jest.fn(() => Promise.resolve()) };
+    const notificationQueue: any = { add: jest.fn(async () => undefined) };
+
+    const auditService: any = { log: jest.fn() };
+
+    const service = new CommentService(
+      commentRepo,
+      pageRepo,
+      wsService,
+      collaborationGateway,
+      generalQueue,
+      notificationQueue,
+      auditService,
+    );
+
+    return { service, commentRepo, wsService };
+  }
+
+  // Pull the emitted event object (3rd arg of emitCommentEvent) for an operation.
+  const emittedEvent = (wsService: any, operation: string) =>
+    wsService.emitCommentEvent.mock.calls
+      .map((c: any[]) => c[2])
+      .find((e: any) => e.operation === operation);
+
+  const page = { id: 'page-1', spaceId: 'space-1' } as any;
+  const user = (id = 'user-1') => ({ id }) as any;
+  const emptyDoc = JSON.stringify({ type: 'doc', content: [] });
+
+  describe('commentCreated', () => {
+    it('emits agent + launcher for an agent comment', async () => {
+      const { service, wsService } = makeService(enrichedAgentComment());
+
+      await service.create(
+        { page, workspaceId: 'ws-1', user: user() },
+        { content: emptyDoc } as any,
+        { actor: 'agent', aiChatId: 'chat-1' },
+      );
+
+      const event = emittedEvent(wsService, 'commentCreated');
+      expect(event).toBeDefined();
+      expect(event.comment.agent).toEqual({
+        name: 'Researcher',
+        emoji: '🔬',
+        avatarUrl: null,
+      });
+      expect(event.comment.launcher).toEqual({ name: 'Alice', avatarUrl: 'a.png' });
+    });
+
+    it('emits neither field for a non-agent comment', async () => {
+      const { service, wsService } = makeService(plainHumanComment());
+
+      await service.create(
+        { page, workspaceId: 'ws-1', user: user() },
+        { content: emptyDoc } as any,
+      );
+
+      const event = emittedEvent(wsService, 'commentCreated');
+      expect(event).toBeDefined();
+      expect(event.comment).not.toHaveProperty('agent');
+      expect(event.comment).not.toHaveProperty('launcher');
+    });
+  });
+
+  describe('commentUpdated — the fragile path (spotlight)', () => {
+    it('emits agent + launcher even when the caller pre-loaded an UN-enriched comment', async () => {
+      // findById (the re-fetch) returns the enriched shape...
+      const { service, wsService, commentRepo } = makeService(
+        enrichedAgentComment(),
+      );
+
+      // ...but the caller hands in an object with NO agent/launcher. The pre-#304
+      // update() re-emitted THIS object in place, so this test fails against it;
+      // the re-fetch fix makes the broadcast independent of the pre-load.
+      const inputComment: any = {
+        id: 'comment-new',
+        creatorId: 'user-1',
+        pageId: 'page-1',
+        spaceId: 'space-1',
+        workspaceId: 'ws-1',
+        content: { type: 'doc', content: [] },
+        // deliberately no `agent` / `launcher`
+      };
+
+      await service.update(
+        inputComment,
+        { content: emptyDoc } as any,
+        user('user-1'),
+      );
+
+      // The broadcast must re-read the enriched row (persisted update, then load).
+      expect(commentRepo.updateComment).toHaveBeenCalled();
+      expect(commentRepo.findById).toHaveBeenCalledWith('comment-new', {
+        includeCreator: true,
+        includeResolvedBy: true,
+      });
+
+      const event = emittedEvent(wsService, 'commentUpdated');
+      expect(event).toBeDefined();
+      expect(event.comment.agent).toEqual({
+        name: 'Researcher',
+        emoji: '🔬',
+        avatarUrl: null,
+      });
+      expect(event.comment.launcher).toEqual({ name: 'Alice', avatarUrl: 'a.png' });
+    });
+
+    it('emits neither field for a non-agent comment', async () => {
+      const { service, wsService } = makeService(plainHumanComment());
+
+      const inputComment: any = {
+        id: 'comment-new',
+        creatorId: 'user-1',
+        pageId: 'page-1',
+        spaceId: 'space-1',
+        workspaceId: 'ws-1',
+        content: { type: 'doc', content: [] },
+      };
+
+      await service.update(
+        inputComment,
+        { content: emptyDoc } as any,
+        user('user-1'),
+      );
+
+      const event = emittedEvent(wsService, 'commentUpdated');
+      expect(event).toBeDefined();
+      expect(event.comment).not.toHaveProperty('agent');
+      expect(event.comment).not.toHaveProperty('launcher');
+    });
+  });
+
+  describe('commentResolved', () => {
+    it('emits agent + launcher for an agent comment', async () => {
+      const { service, wsService } = makeService(enrichedAgentComment());
+
+      await service.resolveComment(
+        {
+          id: 'comment-new',
+          creatorId: 'user-1',
+          pageId: 'page-1',
+          spaceId: 'space-1',
+          workspaceId: 'ws-1',
+        } as any,
+        true,
+        user('user-1'),
+        { actor: 'agent', aiChatId: 'chat-1' },
+      );
+
+      const event = emittedEvent(wsService, 'commentResolved');
+      expect(event).toBeDefined();
+      expect(event.comment.agent).toEqual({
+        name: 'Researcher',
+        emoji: '🔬',
+        avatarUrl: null,
+      });
+      expect(event.comment.launcher).toEqual({ name: 'Alice', avatarUrl: 'a.png' });
+    });
+
+    it('emits neither field for a non-agent comment', async () => {
+      const { service, wsService } = makeService(plainHumanComment());
+
+      await service.resolveComment(
+        {
+          id: 'comment-new',
+          creatorId: 'user-1',
+          pageId: 'page-1',
+          spaceId: 'space-1',
+          workspaceId: 'ws-1',
+        } as any,
+        true,
+        user('user-1'),
+      );
+
+      const event = emittedEvent(wsService, 'commentResolved');
+      expect(event).toBeDefined();
+      expect(event.comment).not.toHaveProperty('agent');
+      expect(event.comment).not.toHaveProperty('launcher');
+    });
+  });
+});

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

@@ -14,6 +14,7 @@ describe('CommentService', () => {
       {} as any, // collaborationGateway
       {} as any, // generalQueue
       {} as any, // notificationQueue
+      {} as any, // auditService
     );
   });
 

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

@@ -1,7 +1,10 @@
 import {
   BadRequestException,
+  ConflictException,
   ForbiddenException,
+  Inject,
   Injectable,
+  InternalServerErrorException,
   Logger,
   NotFoundException,
 } from '@nestjs/common';
@@ -26,6 +29,11 @@ import {
   AuthProvenanceData,
   agentSourceFields,
 } from '../../common/decorators/auth-provenance.decorator';
+import { AuditEvent, AuditResource } from '../../common/events/audit-events';
+import {
+  AUDIT_SERVICE,
+  IAuditService,
+} from '../../integrations/audit/audit.service';
 
 @Injectable()
 export class CommentService {
@@ -40,6 +48,7 @@ export class CommentService {
     private generalQueue: Queue,
     @InjectQueue(QueueName.NOTIFICATION_QUEUE)
     private notificationQueue: Queue,
+    @Inject(AUDIT_SERVICE) private auditService: IAuditService,
   ) {}
 
   async findById(commentId: string) {
@@ -78,15 +87,58 @@ export class CommentService {
       }
     }
 
+    // Do NOT lossily truncate at 250: for a suggestion the client sends the RAW
+    // anchored document substring (the exact text under the comment mark) as the
+    // selection, which can be LONGER than the agent's <=250-char typed input
+    // (normalization collapses whitespace/typographic runs, so the raw span can
+    // exceed the normalized selection). Truncating it shorter than the mark span
+    // would break the apply-time equality check and make the suggestion
+    // un-appliable. Keep a generous 2000-char safety bound (matching
+    // suggestedText) so a legitimate anchored substring is never cut.
+    const selection = createCommentDto?.selection?.substring(0, 2000) ?? null;
+
+    // A suggested edit rewrites the exact text under an inline comment mark, so
+    // it is only meaningful on a top-level inline comment that carries a
+    // selection, and only if the suggestion actually changes that text.
+    let suggestedText: string | null = null;
+    if (
+      createCommentDto.suggestedText !== undefined &&
+      createCommentDto.suggestedText !== null
+    ) {
+      if (createCommentDto.parentCommentId) {
+        throw new BadRequestException(
+          'A suggested edit can only be attached to a top-level comment, not a reply',
+        );
+      }
+      if (!selection || selection.trim().length === 0) {
+        throw new BadRequestException(
+          'A suggested edit requires an inline comment with a non-empty text selection',
+        );
+      }
+      const trimmed = createCommentDto.suggestedText.trim();
+      if (trimmed.length === 0) {
+        throw new BadRequestException('A suggested edit cannot be empty');
+      }
+      // A no-op suggestion (identical to the selection) is meaningless and would
+      // make "apply" indistinguishable from "already applied".
+      if (trimmed === selection.trim()) {
+        throw new BadRequestException(
+          'A suggested edit must differ from the selected text',
+        );
+      }
+      suggestedText = trimmed;
+    }
+
     const inserted = await this.commentRepo.insertComment({
       pageId: page.id,
       content: commentContent,
-      selection: createCommentDto?.selection?.substring(0, 250) ?? null,
+      selection,
       type: createCommentDto.type ?? 'page',
       parentCommentId: createCommentDto?.parentCommentId,
       creatorId: user.id,
       workspaceId: workspaceId,
       spaceId: page.spaceId,
+      suggestedText,
       // Agent-edit provenance: the user stays creatorId; this only annotates the
       // source. Normal user requests leave the column default ('user').
       ...agentSourceFields(provenance, 'createdSource', 'aiChatId'),
@@ -207,17 +259,27 @@ export class CommentService {
       false,
     );
 
-    comment.content = commentContent;
-    comment.editedAt = editedAt;
-    comment.updatedAt = editedAt;
+    // Re-fetch the enriched comment before broadcasting, symmetric with
+    // create()/resolveComment(). updateComment() above has already persisted the
+    // new content/timestamps, so this single-row read reflects the edit AND
+    // carries the same {agent,launcher} avatar stack (via includeCreator) as the
+    // other two broadcasts. This deliberately does NOT reuse the caller's
+    // pre-loaded `comment`: relying on the controller happening to load it with
+    // includeCreator:true is exactly the fragile coupling that let the agent
+    // stack silently vanish on edit once already (#300/#304) — a future caller
+    // dropping that flag must not regress the broadcast.
+    const updatedComment = await this.commentRepo.findById(comment.id, {
+      includeCreator: true,
+      includeResolvedBy: true,
+    });
 
     this.wsService.emitCommentEvent(comment.spaceId, comment.pageId, {
       operation: 'commentUpdated',
       pageId: comment.pageId,
-      comment,
+      comment: updatedComment,
     });
 
-    return comment;
+    return updatedComment;
   }
 
   async resolveComment(
@@ -289,6 +351,152 @@ export class CommentService {
     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
+   * the comment's suggestedText, then stamp the applied fields and auto-resolve
+   * the thread. The controller authorizes (validateCanEdit); this re-checks the
+   * comment's own state so the invariant holds regardless of caller.
+   */
+  async applySuggestion(
+    comment: Comment,
+    user: User,
+    provenance?: AuthProvenanceData,
+  ): Promise<Comment> {
+    // Structural guards.
+    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 to apply');
+    }
+    // State guards. Order matters — the already-applied check precedes the
+    // resolved check because an applied comment is normally also resolved.
+    //
+    // Already applied → IDEMPOTENT SUCCESS (issue #315 DoD: double-click /
+    // two-user race → idempotent "already applied", NOT a 409). The suggestion
+    // is already in the document, so do NOT call the collab gateway again.
+    // finalizeAppliedSuggestion re-fetches/broadcasts the same success shape as
+    // the applied branch and, when the thread is still open (the rare "applied
+    // but not resolved" crash window), self-heals it via resolveComment.
+    if (comment.suggestionAppliedAt) {
+      return this.finalizeAppliedSuggestion(comment, user, provenance);
+    }
+    // Not-yet-applied on a resolved thread → reject. The client hides the apply
+    // button once a thread is resolved; this is the defensive server check.
+    if (comment.resolvedAt) {
+      throw new BadRequestException(
+        'Cannot apply a suggested edit on a resolved comment thread',
+      );
+    }
+
+    // Derive the document name the same way create()/resolveComment() do for
+    // the comment marks: `page.${pageId}`.
+    const documentName = `page.${comment.pageId}`;
+
+    let verdict: { applied: boolean; currentText: string | null } | undefined;
+    try {
+      verdict = await this.collaborationGateway.handleYjsEvent(
+        'applyCommentSuggestion',
+        documentName,
+        {
+          commentId: comment.id,
+          expectedText: comment.selection,
+          newText: comment.suggestedText,
+          user,
+        },
+      );
+    } catch (error) {
+      // A throwing gateway (or the phase-3 fallback failing) is a hard error —
+      // never silently succeed, the document may or may not have changed.
+      this.logger.error(
+        `Failed to apply suggested edit for comment ${comment.id}`,
+        error,
+      );
+      throw new InternalServerErrorException('Failed to apply the suggested edit');
+    }
+
+    if (!verdict) {
+      // Should not happen given the phase-3 fallback; treat as a hard error
+      // rather than assuming success.
+      throw new InternalServerErrorException('Failed to apply the suggested edit');
+    }
+
+    if (verdict.applied === true) {
+      return this.finalizeAppliedSuggestion(comment, user, provenance);
+    }
+
+    // Idempotent branch: the mutation didn't run now, but the text under the
+    // mark is ALREADY the suggested text (double-click, two-user race, or a
+    // crash between the doc mutation and the DB write). Reconcile the DB /
+    // resolved state and report success — do NOT 409.
+    if (
+      verdict.applied === false &&
+      verdict.currentText === comment.suggestedText
+    ) {
+      return this.finalizeAppliedSuggestion(comment, user, provenance);
+    }
+
+    // The commented text changed since the suggestion was made. Surface the
+    // current text so the client can tell the user what it is now.
+    throw new ConflictException({
+      message:
+        'The commented text changed since this suggestion was made; it was not applied.',
+      currentText: verdict.currentText,
+    });
+  }
+
+  /**
+   * Persist the applied stamps (idempotently), auto-resolve the thread and
+   * broadcast + audit the applied suggestion. Shared by the applied and the
+   * idempotent "already-applied" branches of applySuggestion.
+   */
+  private async finalizeAppliedSuggestion(
+    comment: Comment,
+    user: User,
+    provenance?: AuthProvenanceData,
+  ): Promise<Comment> {
+    if (!comment.suggestionAppliedAt) {
+      await this.commentRepo.updateComment(
+        {
+          suggestionAppliedAt: new Date(),
+          suggestionAppliedById: user.id,
+        },
+        comment.id,
+      );
+    }
+
+    // Auto-resolve the thread. resolveComment handles the resolve mark, its ws
+    // broadcast and the resolve notification. The guard above guarantees the
+    // thread was open when we entered, but stay defensive on re-entry.
+    if (!comment.resolvedAt) {
+      await this.resolveComment(comment, true, user, provenance);
+    }
+
+    const updatedComment = await this.commentRepo.findById(comment.id, {
+      includeCreator: true,
+      includeResolvedBy: true,
+    });
+
+    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 },
+    });
+
+    return updatedComment;
+  }
+
   private async queueCommentNotification(
     content: any,
     oldMentionIds: string[],

apps/server/src/core/comment/dto/apply-suggestion.dto.ts

@@ -0,0 +1,6 @@
+import { IsUUID } from 'class-validator';
+
+export class ApplySuggestionDto {
+  @IsUUID()
+  commentId: string;
+}

apps/server/src/core/comment/dto/create-comment.dto.ts

@@ -1,4 +1,12 @@
-import { IsIn, IsJSON, IsObject, IsOptional, IsString, IsUUID } from 'class-validator';
+import {
+  IsIn,
+  IsJSON,
+  IsObject,
+  IsOptional,
+  IsString,
+  IsUUID,
+  MaxLength,
+} from 'class-validator';
 import { z } from 'zod';
 
 const yjsIdSchema = z.object({
@@ -25,8 +33,15 @@ export class CreateCommentDto {
   @IsJSON()
   content: any;
 
+  // The agent tool caps what it TYPES at 250 chars, but for a suggestion the
+  // client resolves and sends the RAW anchored document substring (the exact
+  // text under the mark), which can be longer once normalization is undone. Bound
+  // the stored value at 2000 (matching suggestedText) so a legitimate anchored
+  // substring is never rejected — the service used to lossily truncate at 250,
+  // which broke the apply-time equality check.
   @IsOptional()
   @IsString()
+  @MaxLength(2000)
   selection: string;
 
   @IsOptional()
@@ -43,4 +58,12 @@ export class CreateCommentDto {
     anchor: any;
     head: any;
   };
+
+  // Optional suggested replacement for the selected text (a "suggested edit").
+  // Only valid on a top-level inline comment that carries a non-empty selection;
+  // enforced in CommentService.create.
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  suggestedText?: string;
 }

apps/server/src/database/migrations/20260703T190000-comment-suggestions.ts

@@ -0,0 +1,26 @@
+import { type Kysely } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  // Agent comment suggestions (#315): a comment may carry a proposed replacement
+  // for its anchored `selection`, which a human applies via the comment UI.
+  await db.schema
+    .alterTable('comments')
+    // The proposed replacement text (plain text). NULL for ordinary comments.
+    .addColumn('suggested_text', 'text')
+    // When the suggestion was applied (NULL until applied).
+    .addColumn('suggestion_applied_at', 'timestamptz')
+    // Who applied it (NULL until applied).
+    .addColumn('suggestion_applied_by_id', 'uuid', (col) =>
+      col.references('users.id').onDelete('set null'),
+    )
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .alterTable('comments')
+    .dropColumn('suggested_text')
+    .dropColumn('suggestion_applied_at')
+    .dropColumn('suggestion_applied_by_id')
+    .execute();
+}

apps/server/src/database/repos/agent-provenance.spec.ts

@@ -0,0 +1,129 @@
+import { resolveAgentProvenance } from './agent-provenance';
+import { commentAgentRoleQuery } from './comment/comment.repo';
+import { pageHistoryAgentRoleQuery } from './page/page-history.repo';
+
+/**
+ * The server-authoritative "agent avatar stack" resolver (#300) normalizes the
+ * two provenance shapes into { agent (front), launcher (behind) } so the client
+ * never branches. These tests pin the exact resolved shape for the three agent
+ * cases plus the non-agent pass-through.
+ */
+describe('resolveAgentProvenance', () => {
+  const human = { name: 'Alice', avatarUrl: 'a.png' };
+
+  it('internal chat WITH role: agent = role (emoji, no avatar), launcher = human', () => {
+    const result = resolveAgentProvenance({
+      isAgent: true,
+      aiChatId: 'chat-1',
+      creator: human,
+      agentRole: { name: 'Researcher', emoji: '🔬' },
+    });
+    expect(result).toEqual({
+      agent: { name: 'Researcher', emoji: '🔬', avatarUrl: null },
+      launcher: { name: 'Alice', avatarUrl: 'a.png' },
+    });
+  });
+
+  it('internal chat WITHOUT role: agent = "AI agent" fallback, launcher = human', () => {
+    const result = resolveAgentProvenance({
+      isAgent: true,
+      aiChatId: 'chat-1',
+      creator: human,
+      agentRole: null,
+    });
+    expect(result).toEqual({
+      agent: { name: 'AI agent', avatarUrl: null },
+      launcher: { name: 'Alice', avatarUrl: 'a.png' },
+    });
+    // The fallback agent carries no emoji (only sparkles glyph on the client).
+    expect(result?.agent).not.toHaveProperty('emoji');
+  });
+
+  it('external MCP (aiChatId null): agent = the account itself, launcher = null', () => {
+    const result = resolveAgentProvenance({
+      isAgent: true,
+      aiChatId: null,
+      creator: { name: 'MCP Bot', avatarUrl: 'bot.png' },
+      agentRole: null,
+    });
+    expect(result).toEqual({
+      agent: { name: 'MCP Bot', avatarUrl: 'bot.png' },
+      launcher: null,
+    });
+  });
+
+  it('non-agent content: returns null so the caller omits both fields', () => {
+    expect(
+      resolveAgentProvenance({
+        isAgent: false,
+        aiChatId: null,
+        creator: human,
+        agentRole: null,
+      }),
+    ).toBeNull();
+  });
+});
+
+/**
+ * The role-resolution subquery must NOT filter on enabled/deletedAt: historical
+ * agent content keeps its signature even after the role is disabled or
+ * soft-deleted (same rule as AiAgentRoleRepo.findById, NOT findLiveEnabled). We
+ * record the query-builder calls and assert the join binds only id<->roleId and
+ * that `where` is never called with an enabled/deletedAt filter.
+ */
+describe('agent role subquery — no live/enabled filter', () => {
+  function makeRecorder() {
+    const calls: { method: string; args: unknown[] }[] = [];
+    const builder = new Proxy(
+      {},
+      {
+        get(_t, prop: string) {
+          return (...args: unknown[]) => {
+            calls.push({ method: prop, args });
+            return builder;
+          };
+        },
+      },
+    );
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const eb = { selectFrom: (...args: unknown[]) => (calls.push({ method: 'selectFrom', args }), builder) } as any;
+    return { eb, calls };
+  }
+
+  function assertNoLiveFilter(
+    query: (eb: any) => unknown, // eslint-disable-line @typescript-eslint/no-explicit-any
+    chatIdColumn: string,
+  ) {
+    const { eb, calls } = makeRecorder();
+    query(eb);
+
+    const innerJoin = calls.find((c) => c.method === 'innerJoin');
+    expect(innerJoin?.args).toEqual([
+      'aiAgentRoles',
+      'aiAgentRoles.id',
+      'aiChats.roleId',
+    ]);
+
+    const whereRef = calls.find((c) => c.method === 'whereRef');
+    expect(whereRef?.args).toEqual(['aiChats.id', '=', chatIdColumn]);
+
+    // The security-narrowing filters used by findLiveEnabled must be ABSENT.
+    const filtered = calls
+      .flatMap((c) => c.args)
+      .filter((a) => a === 'enabled' || a === 'deletedAt');
+    expect(filtered).toEqual([]);
+    // No `where(...)` at all (only the join + whereRef).
+    expect(calls.some((c) => c.method === 'where')).toBe(false);
+  }
+
+  it('comment subquery joins by id only, keyed on comments.aiChatId', () => {
+    assertNoLiveFilter(commentAgentRoleQuery, 'comments.aiChatId');
+  });
+
+  it('page-history subquery joins by id only, keyed on lastUpdatedAiChatId', () => {
+    assertNoLiveFilter(
+      pageHistoryAgentRoleQuery,
+      'pageHistory.lastUpdatedAiChatId',
+    );
+  });
+});

apps/server/src/database/repos/agent-provenance.ts

@@ -0,0 +1,93 @@
+/**
+ * Server-authoritative "agent avatar stack" provenance (#300).
+ *
+ * Agent-authored content (comments / page-history snapshots) is displayed as a
+ * two-avatar stack: the AGENT in front, and the HUMAN who launched it behind.
+ * This module normalizes the two provenance shapes the client can encounter into
+ * the SAME pair of sub-objects so the client never has to branch:
+ *
+ *   agent    — FRONT  (the acting agent identity)
+ *   launcher — BEHIND (the human on whose behalf it acted; null when there is none)
+ *
+ * The discriminator is purely SERVER-SIDE data (createdSource / lastUpdatedSource
+ * plus aiChatId) that only the server can set — none of it is read from request
+ * input, so an external caller cannot spoof an `agent` badge.
+ */
+
+/** Front avatar identity. `avatarUrl`/`emoji` feed the glyph source priority. */
+export interface AgentInfo {
+  name: string;
+  emoji?: string | null;
+  avatarUrl?: string | null;
+}
+
+/** Behind avatar identity — the human who launched the agent (internal chat). */
+export interface LauncherInfo {
+  name: string;
+  avatarUrl?: string | null;
+}
+
+/**
+ * Inputs to the resolver, drawn entirely from server-side columns:
+ * - `isAgent`  — createdSource/lastUpdatedSource === 'agent'.
+ * - `aiChatId` — internal-AI-chat discriminator: non-null => internal chat (the
+ *   provenance token was minted for the human, so `creator` is the human and the
+ *   agent identity comes from the chat's role); null => external MCP (the login
+ *   IS a dedicated agent account, so `creator` is the agent, no separate human).
+ * - `creator`  — the row's human author (internal) OR agent account (MCP).
+ * - `agentRole`— the chat's bound role (name + optional emoji), resolved WITHOUT
+ *   any enabled/deleted filter so historical content keeps its signature even
+ *   after the role is disabled or soft-deleted; null when the chat has no role.
+ */
+export interface AgentProvenanceInput {
+  isAgent: boolean;
+  aiChatId: string | null | undefined;
+  creator: { name: string; avatarUrl?: string | null } | null | undefined;
+  agentRole: { name: string; emoji?: string | null } | null | undefined;
+}
+
+export interface AgentProvenance {
+  agent: AgentInfo;
+  launcher: LauncherInfo | null;
+}
+
+/** Fallback display name for an internal agent edit whose chat has no role. */
+export const AGENT_FALLBACK_NAME = 'AI agent';
+
+/**
+ * Resolve the front/behind identities from server-side provenance. Returns
+ * `null` for non-agent content so the caller can OMIT both fields (the client
+ * then keeps its plain single-human avatar).
+ */
+export function resolveAgentProvenance(
+  input: AgentProvenanceInput,
+): AgentProvenance | null {
+  if (!input.isAgent) return null;
+
+  // External MCP: no internal chat row; the login itself is the agent account.
+  if (input.aiChatId == null) {
+    return {
+      agent: {
+        name: input.creator?.name ?? AGENT_FALLBACK_NAME,
+        avatarUrl: input.creator?.avatarUrl ?? null,
+      },
+      launcher: null,
+    };
+  }
+
+  // Internal AI chat: the agent identity is the chat's role (or the fallback
+  // when the chat has no role), and the launcher is the human chat owner.
+  const agent: AgentInfo = input.agentRole
+    ? {
+        name: input.agentRole.name,
+        emoji: input.agentRole.emoji ?? null,
+        avatarUrl: null,
+      }
+    : { name: AGENT_FALLBACK_NAME, avatarUrl: null };
+
+  const launcher: LauncherInfo | null = input.creator
+    ? { name: input.creator.name, avatarUrl: input.creator.avatarUrl ?? null }
+    : null;
+
+  return { agent, launcher };
+}

apps/server/src/database/repos/comment/comment.repo.spec.ts

@@ -0,0 +1,124 @@
+import { CommentRepo } from './comment.repo';
+
+/**
+ * Enrichment coverage for CommentRepo.findById (#300).
+ *
+ * The {agent,launcher} avatar stack must be attached on the SINGLE-ROW read
+ * path, not only on findPageComments — the live websocket broadcasts
+ * (commentCreated/commentUpdated/commentResolved) return a comment loaded via
+ * findById. These tests would FAIL against the previous un-enriched findById
+ * (which returned the raw row without calling attachCommentAgent and without
+ * selecting the agent-role subquery).
+ *
+ * The Kysely db is replaced by a chainable recorder so the query never touches a
+ * real database: it records the `.select(...)` args (to prove the agent-role
+ * subquery is selected on the includeCreator path) and returns a preset row from
+ * executeTakeFirst (to prove attachCommentAgent maps it into {agent,launcher}).
+ */
+describe('CommentRepo.findById — agent avatar stack enrichment', () => {
+  function makeRepo(row: unknown) {
+    const selectArgs: unknown[] = [];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const builder: any = {
+      selectFrom: () => builder,
+      selectAll: () => builder,
+      select: (arg: unknown) => {
+        selectArgs.push(arg);
+        return builder;
+      },
+      // Kysely's $if(condition, cb) invokes cb(qb) only when the condition is
+      // truthy; mirror that so gating (includeCreator) is exercised faithfully.
+      $if: (cond: unknown, cb: (qb: unknown) => unknown) => {
+        if (cond) cb(builder);
+        return builder;
+      },
+      where: () => builder,
+      executeTakeFirst: async () => row,
+    };
+    const db = { selectFrom: () => builder };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const repo = new CommentRepo(db as any);
+    return { repo, selectArgs };
+  }
+
+  const enrichOpts = { includeCreator: true, includeResolvedBy: true };
+
+  it('internal agent chat WITH role: returns agent = role, launcher = creator, and strips agentRole', async () => {
+    const { repo, selectArgs } = makeRepo({
+      id: 'c-1',
+      createdSource: 'agent',
+      aiChatId: 'chat-1',
+      creator: { name: 'Alice', avatarUrl: 'a.png' },
+      agentRole: { name: 'Researcher', emoji: '🔬' },
+    });
+
+    const result: any = await repo.findById('c-1', enrichOpts);
+
+    expect(result.agent).toEqual({
+      name: 'Researcher',
+      emoji: '🔬',
+      avatarUrl: null,
+    });
+    expect(result.launcher).toEqual({ name: 'Alice', avatarUrl: 'a.png' });
+    // The internal join column must never leak to the client.
+    expect(result).not.toHaveProperty('agentRole');
+    // The enrichment SELECTs the agent-role subquery on the includeCreator path
+    // (mirrors the list-query proof; absent in the pre-fix findById).
+    expect(selectArgs).toContain(repo.withAgentRole);
+  });
+
+  it('external MCP agent (aiChatId null): agent = the account, launcher = null', async () => {
+    const { repo } = makeRepo({
+      id: 'c-2',
+      createdSource: 'agent',
+      aiChatId: null,
+      creator: { name: 'MCP Bot', avatarUrl: 'bot.png' },
+      agentRole: null,
+    });
+
+    const result: any = await repo.findById('c-2', enrichOpts);
+
+    expect(result.agent).toEqual({ name: 'MCP Bot', avatarUrl: 'bot.png' });
+    expect(result.launcher).toBeNull();
+    expect(result).not.toHaveProperty('agentRole');
+  });
+
+  it('non-agent comment: neither agent nor launcher is attached', async () => {
+    const { repo } = makeRepo({
+      id: 'c-3',
+      createdSource: 'user',
+      aiChatId: null,
+      creator: { name: 'Bob', avatarUrl: null },
+      agentRole: null,
+    });
+
+    const result: any = await repo.findById('c-3', enrichOpts);
+
+    expect(result).not.toHaveProperty('agent');
+    expect(result).not.toHaveProperty('launcher');
+    // A plain human comment still strips the internal join column.
+    expect(result).not.toHaveProperty('agentRole');
+  });
+
+  it('missing row: returns undefined without crashing the enrichment', async () => {
+    const { repo } = makeRepo(undefined);
+    await expect(repo.findById('nope', enrichOpts)).resolves.toBeUndefined();
+  });
+
+  it('non-includeCreator callers keep the plain shape (no enrichment, no agent-role select)', async () => {
+    const { repo, selectArgs } = makeRepo({
+      id: 'c-4',
+      createdSource: 'agent',
+      aiChatId: 'chat-1',
+    });
+
+    // No opts => the enrichment (and its subquery select) must be skipped, so
+    // callers doing a bare lookup (parent-comment check, controller findOne)
+    // are unaffected by the additive fields.
+    const result: any = await repo.findById('c-4');
+
+    expect(result).not.toHaveProperty('agent');
+    expect(result).not.toHaveProperty('launcher');
+    expect(selectArgs).not.toContain(repo.withAgentRole);
+  });
+});

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

@@ -12,6 +12,24 @@ import { executeWithCursorPagination } from '@docmost/db/pagination/cursor-pagin
 import { ExpressionBuilder } from 'kysely';
 import { DB } from '@docmost/db/types/db';
 import { jsonObjectFrom } from 'kysely/helpers/postgres';
+import { resolveAgentProvenance } from '../agent-provenance';
+
+/**
+ * Role-resolution subquery for a comment's bound AI chat (#300). Joins
+ * comments.aiChatId -> ai_chats.role_id -> ai_agent_roles and selects the role's
+ * name + emoji. NO enabled/deletedAt filter: historical agent content must keep
+ * its signature even after the role is later disabled or soft-deleted — the same
+ * "resolve by id, ignore live/enabled" rule as AiAgentRoleRepo.findById (NOT
+ * findLiveEnabled). Exported so a unit test can assert the join binds only
+ * id<->roleId and never filters on enabled/deletedAt.
+ */
+export function commentAgentRoleQuery(eb: ExpressionBuilder<DB, 'comments'>) {
+  return eb
+    .selectFrom('aiChats')
+    .innerJoin('aiAgentRoles', 'aiAgentRoles.id', 'aiChats.roleId')
+    .select(['aiAgentRoles.name', 'aiAgentRoles.emoji'])
+    .whereRef('aiChats.id', '=', 'comments.aiChatId');
+}
 
 @Injectable()
 export class CommentRepo {
@@ -22,13 +40,30 @@ export class CommentRepo {
     commentId: string,
     opts?: { includeCreator: boolean; includeResolvedBy: boolean },
   ): Promise<Comment> {
-    return await this.db
+    const comment = await this.db
       .selectFrom('comments')
       .selectAll('comments')
       .$if(opts?.includeCreator, (qb) => qb.select(this.withCreator))
       .$if(opts?.includeResolvedBy, (qb) => qb.select(this.withResolvedBy))
+      // #300: enrich the single-row read with the agent-role subquery so the
+      // {agent,launcher} avatar stack is attached here too — the live websocket
+      // broadcasts (commentCreated/Updated/Resolved) return a comment loaded via
+      // findById, and must carry the SAME provenance as the list query
+      // findPageComments. Without this a freshly created / edited / resolved
+      // agent comment arrives un-enriched and the client's
+      // `createdSource === 'agent' && agent` gate drops the stack until a full
+      // refetch. Gated on includeCreator (mirroring findPageComments, which
+      // always selects the creator): the internal-chat launcher IS the creator,
+      // so the resolver needs it, and every broadcast caller passes
+      // includeCreator: true. Non-includeCreator callers keep the plain shape.
+      .$if(opts?.includeCreator, (qb) => qb.select(this.withAgentRole))
       .where('id', '=', commentId)
       .executeTakeFirst();
+
+    // Guard a missing row (don't destructure undefined in attachCommentAgent)
+    // and leave non-enriched callers' shape untouched.
+    if (!comment || !opts?.includeCreator) return comment;
+    return attachCommentAgent(comment) as Comment;
   }
 
   async findPageComments(pageId: string, pagination: PaginationOptions) {
@@ -37,15 +72,18 @@ export class CommentRepo {
       .selectAll('comments')
       .select((eb) => this.withCreator(eb))
       .select((eb) => this.withResolvedBy(eb))
+      .select((eb) => this.withAgentRole(eb))
       .where('pageId', '=', pageId);
 
-    return executeWithCursorPagination(query, {
+    const result = await executeWithCursorPagination(query, {
       perPage: pagination.limit,
       cursor: pagination.cursor,
       beforeCursor: pagination.beforeCursor,
       fields: [{ expression: 'id', direction: 'asc' }],
       parseCursor: (cursor) => ({ id: cursor.id }),
     });
+
+    return { ...result, items: result.items.map(attachCommentAgent) };
   }
 
   async updateComment(
@@ -82,6 +120,12 @@ export class CommentRepo {
     ).as('creator');
   }
 
+  /** Select the comment's resolved chat role (name + emoji) as `agentRole`, or
+   *  null when the comment has no internal chat / the chat has no role (#300). */
+  withAgentRole(eb: ExpressionBuilder<DB, 'comments'>) {
+    return jsonObjectFrom(commentAgentRoleQuery(eb)).as('agentRole');
+  }
+
   withResolvedBy(eb: ExpressionBuilder<DB, 'comments'>) {
     return jsonObjectFrom(
       eb
@@ -116,3 +160,30 @@ export class CommentRepo {
     return Number(result?.count) > 0;
   }
 }
+
+/**
+ * Attach the normalized agent/launcher provenance (#300) to a comment row and
+ * strip the internal `agentRole` join column. Non-agent rows pass through
+ * unchanged (neither field added — the client keeps the plain human avatar). The
+ * human author (`creator`) is the launcher for an internal chat, or the agent
+ * itself for external MCP; the resolver encodes both cases.
+ */
+function attachCommentAgent<
+  R extends {
+    createdSource?: string | null;
+    aiChatId?: string | null;
+    creator?: { name: string; avatarUrl?: string | null } | null;
+    agentRole?: { name: string; emoji?: string | null } | null;
+  },
+>(row: R) {
+  const { agentRole, ...rest } = row;
+  const provenance = resolveAgentProvenance({
+    isAgent: row.createdSource === 'agent',
+    aiChatId: row.aiChatId,
+    creator: row.creator,
+    agentRole,
+  });
+  return provenance
+    ? { ...rest, agent: provenance.agent, launcher: provenance.launcher }
+    : rest;
+}

apps/server/src/database/repos/page/page-history.repo.spec.ts

@@ -0,0 +1,107 @@
+import { PageHistoryRepo } from './page-history.repo';
+
+/**
+ * Enrichment coverage for the page-history agent avatar stack (#300/#304).
+ *
+ * attachPageHistoryAgent maps a DIFFERENT column set than comments —
+ * `lastUpdatedSource` / `lastUpdatedAiChatId` / `lastUpdatedBy` instead of
+ * `createdSource` / `aiChatId` / `creator` — so it needs its own direct proof
+ * that the {agent,launcher} pair resolves for each provenance shape and that the
+ * internal `agentRole` join column is stripped.
+ *
+ * The mapping is exercised through findPageHistoryByPageId (the only page-history
+ * path that enriches). The Kysely db is a chainable recorder: query-builder
+ * methods return the builder and `.execute()` (called by
+ * executeWithCursorPagination) yields preset rows, so no real database is
+ * touched. The `.select((eb) => ...)` callbacks are recorded but never invoked,
+ * so the preset row stands in for what the DB would have returned.
+ *
+ * NON-VACUITY: against an identity mapping (raw row pass-through) the agent-case
+ * assertions fail — `agent`/`launcher` would be undefined and the internal
+ * `agentRole` column would leak.
+ */
+describe('PageHistoryRepo.findPageHistoryByPageId — agent avatar stack enrichment', () => {
+  function makeRepo(rows: unknown[]) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const builder: any = {
+      selectFrom: () => builder,
+      select: () => builder,
+      where: () => builder,
+      orderBy: () => builder,
+      limit: () => builder,
+      execute: async () => rows,
+    };
+    const db = { selectFrom: () => builder };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return new PageHistoryRepo(db as any);
+  }
+
+  // perPage high enough that a single preset row never triggers the extra-row
+  // "has next page" branch (which would call generateCursor).
+  const pagination = { limit: 50 } as any;
+
+  const firstItem = async (row: Record<string, unknown>) => {
+    const repo = makeRepo([row]);
+    const result = await repo.findPageHistoryByPageId('page-1', pagination);
+    return result.items[0] as any;
+  };
+
+  it('internal chat WITH role: agent = role (emoji, no avatar), launcher = human, agentRole stripped', async () => {
+    const item = await firstItem({
+      id: 'ph-1',
+      lastUpdatedSource: 'agent',
+      lastUpdatedAiChatId: 'chat-1',
+      lastUpdatedBy: { name: 'Alice', avatarUrl: 'a.png' },
+      agentRole: { name: 'Editor', emoji: '✏️' },
+    });
+
+    expect(item.agent).toEqual({ name: 'Editor', emoji: '✏️', avatarUrl: null });
+    expect(item.launcher).toEqual({ name: 'Alice', avatarUrl: 'a.png' });
+    // The internal join column must never leak to the client.
+    expect(item).not.toHaveProperty('agentRole');
+  });
+
+  it('internal chat WITHOUT role: agent = "AI agent" fallback, launcher = human', async () => {
+    const item = await firstItem({
+      id: 'ph-2',
+      lastUpdatedSource: 'agent',
+      lastUpdatedAiChatId: 'chat-1',
+      lastUpdatedBy: { name: 'Alice', avatarUrl: 'a.png' },
+      agentRole: null,
+    });
+
+    expect(item.agent).toEqual({ name: 'AI agent', avatarUrl: null });
+    expect(item.agent).not.toHaveProperty('emoji');
+    expect(item.launcher).toEqual({ name: 'Alice', avatarUrl: 'a.png' });
+    expect(item).not.toHaveProperty('agentRole');
+  });
+
+  it('external MCP (lastUpdatedAiChatId null): agent = the account itself, launcher = null', async () => {
+    const item = await firstItem({
+      id: 'ph-3',
+      lastUpdatedSource: 'agent',
+      lastUpdatedAiChatId: null,
+      lastUpdatedBy: { name: 'MCP Bot', avatarUrl: 'bot.png' },
+      agentRole: null,
+    });
+
+    expect(item.agent).toEqual({ name: 'MCP Bot', avatarUrl: 'bot.png' });
+    expect(item.launcher).toBeNull();
+    expect(item).not.toHaveProperty('agentRole');
+  });
+
+  it('non-agent (lastUpdatedSource !== "agent"): neither agent nor launcher, agentRole stripped', async () => {
+    const item = await firstItem({
+      id: 'ph-4',
+      lastUpdatedSource: 'user',
+      lastUpdatedAiChatId: null,
+      lastUpdatedBy: { name: 'Bob', avatarUrl: null },
+      agentRole: null,
+    });
+
+    expect(item).not.toHaveProperty('agent');
+    expect(item).not.toHaveProperty('launcher');
+    // A plain human row still strips the internal join column.
+    expect(item).not.toHaveProperty('agentRole');
+  });
+});

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

@@ -12,6 +12,25 @@ import { executeWithCursorPagination } from '@docmost/db/pagination/cursor-pagin
 import { jsonArrayFrom, jsonObjectFrom } from 'kysely/helpers/postgres';
 import { ExpressionBuilder, sql } from 'kysely';
 import { DB } from '@docmost/db/types/db';
+import { resolveAgentProvenance } from '../agent-provenance';
+
+/**
+ * Role-resolution subquery for a page-history row's bound AI chat (#300). Joins
+ * pageHistory.lastUpdatedAiChatId -> ai_chats.role_id -> ai_agent_roles and
+ * selects the role's name + emoji. NO enabled/deletedAt filter: historical agent
+ * content must keep its signature even after the role is disabled or soft-deleted
+ * (same rule as AiAgentRoleRepo.findById, NOT findLiveEnabled). Exported so a
+ * unit test can assert the join never filters on enabled/deletedAt.
+ */
+export function pageHistoryAgentRoleQuery(
+  eb: ExpressionBuilder<DB, 'pageHistory'>,
+) {
+  return eb
+    .selectFrom('aiChats')
+    .innerJoin('aiAgentRoles', 'aiAgentRoles.id', 'aiChats.roleId')
+    .select(['aiAgentRoles.name', 'aiAgentRoles.emoji'])
+    .whereRef('aiChats.id', '=', 'pageHistory.lastUpdatedAiChatId');
+}
 
 @Injectable()
 export class PageHistoryRepo {
@@ -94,15 +113,18 @@ export class PageHistoryRepo {
       .select(this.baseFields)
       .select((eb) => this.withLastUpdatedBy(eb))
       .select((eb) => this.withContributors(eb))
+      .select((eb) => this.withAgentRole(eb))
       .where('pageId', '=', pageId);
 
-    return executeWithCursorPagination(query, {
+    const result = await executeWithCursorPagination(query, {
       perPage: pagination.limit,
       cursor: pagination.cursor,
       beforeCursor: pagination.beforeCursor,
       fields: [{ expression: 'id', direction: 'desc' }],
       parseCursor: (cursor) => ({ id: cursor.id }),
     });
+
+    return { ...result, items: result.items.map(attachPageHistoryAgent) };
   }
 
   async findPageLastHistory(
@@ -138,6 +160,12 @@ export class PageHistoryRepo {
     ).as('lastUpdatedBy');
   }
 
+  /** Select the row's resolved chat role (name + emoji) as `agentRole`, or null
+   *  when there is no internal chat / the chat has no role (#300). */
+  withAgentRole(eb: ExpressionBuilder<DB, 'pageHistory'>) {
+    return jsonObjectFrom(pageHistoryAgentRoleQuery(eb)).as('agentRole');
+  }
+
   withContributors(eb: ExpressionBuilder<DB, 'pageHistory'>) {
     return jsonArrayFrom(
       eb
@@ -151,3 +179,30 @@ export class PageHistoryRepo {
     ).as('contributors');
   }
 }
+
+/**
+ * Attach the normalized agent/launcher provenance (#300) to a page-history row
+ * and strip the internal `agentRole` join column. The trigger is
+ * `lastUpdatedSource === 'agent'`, the internal-chat discriminator is
+ * `lastUpdatedAiChatId`, and the human is `lastUpdatedBy`. Non-agent rows pass
+ * through unchanged (neither field added).
+ */
+function attachPageHistoryAgent<
+  R extends {
+    lastUpdatedSource?: string | null;
+    lastUpdatedAiChatId?: string | null;
+    lastUpdatedBy?: { name: string; avatarUrl?: string | null } | null;
+    agentRole?: { name: string; emoji?: string | null } | null;
+  },
+>(row: R) {
+  const { agentRole, ...rest } = row;
+  const provenance = resolveAgentProvenance({
+    isAgent: row.lastUpdatedSource === 'agent',
+    aiChatId: row.lastUpdatedAiChatId,
+    creator: row.lastUpdatedBy,
+    agentRole,
+  });
+  return provenance
+    ? { ...rest, agent: provenance.agent, launcher: provenance.launcher }
+    : rest;
+}

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

@@ -173,6 +173,9 @@ export interface Comments {
   resolvedSource: string | null;
   selection: string | null;
   spaceId: string;
+  suggestedText: string | null;
+  suggestionAppliedAt: Timestamp | null;
+  suggestionAppliedById: string | null;
   type: string | null;
   updatedAt: Generated<Timestamp>;
   workspaceId: string;

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

@@ -6,6 +6,8 @@ import {
   streamKeepAliveMs,
   streamingDispatcherOptions,
   isRetryableConnectError,
+  preResponseConnectRetries,
+  preResponseBackoffMs,
 } from './ai-streaming-fetch';
 
 /**
@@ -47,8 +49,8 @@ describe('streamTimeoutMs', () => {
     expect(streamingDispatcherOptions()).toEqual({
       headersTimeout: 900_000,
       bodyTimeout: 900_000,
-      keepAliveTimeout: 10_000,
-      keepAliveMaxTimeout: 10_000,
+      keepAliveTimeout: 4_000,
+      keepAliveMaxTimeout: 4_000,
     });
   });
 });
@@ -60,21 +62,91 @@ describe('streamKeepAliveMs', () => {
     else process.env.AI_STREAM_KEEPALIVE_MS = ORIG;
   });
 
-  it('defaults to 10s (recycle idle sockets so a NAT/proxy drop cannot poison reuse)', () => {
+  it('defaults to 4s (recycle idle sockets under common ~5s upstream idle cutoffs)', () => {
     delete process.env.AI_STREAM_KEEPALIVE_MS;
-    expect(streamKeepAliveMs()).toBe(10_000);
+    expect(streamKeepAliveMs()).toBe(4_000);
   });
 
   it('honours a positive override and ignores invalid/non-positive', () => {
-    process.env.AI_STREAM_KEEPALIVE_MS = '4000';
-    expect(streamKeepAliveMs()).toBe(4000);
+    process.env.AI_STREAM_KEEPALIVE_MS = '7000';
+    expect(streamKeepAliveMs()).toBe(7000);
     for (const bad of ['0', '-1', 'x', '']) {
       process.env.AI_STREAM_KEEPALIVE_MS = bad;
-      expect(streamKeepAliveMs()).toBe(10_000);
+      expect(streamKeepAliveMs()).toBe(4_000);
     }
   });
 });
 
+/**
+ * #310: the PRE-RESPONSE retry budget was raised 2 -> 4 (5 total attempts) and
+ * made env-configurable so a BURST of upstream resets doesn't exhaust it.
+ */
+describe('preResponseConnectRetries', () => {
+  const ORIG = process.env.AI_STREAM_PRE_RESPONSE_RETRIES;
+  afterEach(() => {
+    if (ORIG === undefined) delete process.env.AI_STREAM_PRE_RESPONSE_RETRIES;
+    else process.env.AI_STREAM_PRE_RESPONSE_RETRIES = ORIG;
+  });
+
+  it('defaults to 4 retries (5 total attempts)', () => {
+    delete process.env.AI_STREAM_PRE_RESPONSE_RETRIES;
+    expect(preResponseConnectRetries()).toBe(4);
+  });
+
+  it('honours a non-negative override (incl. 0 = single attempt)', () => {
+    process.env.AI_STREAM_PRE_RESPONSE_RETRIES = '6';
+    expect(preResponseConnectRetries()).toBe(6);
+    process.env.AI_STREAM_PRE_RESPONSE_RETRIES = '0';
+    expect(preResponseConnectRetries()).toBe(0);
+  });
+
+  it('ignores an invalid / negative override (falls back to default 4)', () => {
+    for (const bad of ['-1', 'abc', '']) {
+      process.env.AI_STREAM_PRE_RESPONSE_RETRIES = bad;
+      expect(preResponseConnectRetries()).toBe(4);
+    }
+  });
+});
+
+/**
+ * #310: linear `150 * (attempt + 1)` backoff replaced with capped exponential +
+ * FULL jitter to avoid a thundering herd of lock-step reconnects. Bound-check the
+ * jitter by pinning the randomness source to its extremes.
+ */
+describe('preResponseBackoffMs', () => {
+  it('with rand=0 waits 0 (bottom of the full-jitter window)', () => {
+    for (let attempt = 0; attempt < 6; attempt++) {
+      expect(preResponseBackoffMs(attempt, () => 0)).toBe(0);
+    }
+  });
+
+  it('with rand=1 returns the capped exponential top of the window', () => {
+    // base 150ms, exp = 150 * 2**attempt, capped at 2000ms.
+    expect(preResponseBackoffMs(0, () => 1)).toBe(150);
+    expect(preResponseBackoffMs(1, () => 1)).toBe(300);
+    expect(preResponseBackoffMs(2, () => 1)).toBe(600);
+    expect(preResponseBackoffMs(3, () => 1)).toBe(1200);
+    // 150 * 2**4 = 2400 -> capped to 2000.
+    expect(preResponseBackoffMs(4, () => 1)).toBe(2000);
+    expect(preResponseBackoffMs(10, () => 1)).toBe(2000);
+  });
+
+  it('stays within [0, cap] and is NOT the old fixed linear value', () => {
+    const cap = 2000;
+    for (let attempt = 0; attempt < 8; attempt++) {
+      for (const r of [0, 0.5, 0.999, 1]) {
+        const d = preResponseBackoffMs(attempt, () => r);
+        expect(d).toBeGreaterThanOrEqual(0);
+        expect(d).toBeLessThanOrEqual(cap);
+      }
+    }
+    // The old formula gave a fixed 150*(attempt+1); the jittered one with a
+    // mid-range rand does not reproduce it (e.g. attempt 0 -> 75, not 150).
+    expect(preResponseBackoffMs(0, () => 0.5)).toBe(75);
+    expect(preResponseBackoffMs(0, () => 0.5)).not.toBe(150);
+  });
+});
+
 describe('isRetryableConnectError', () => {
   it('matches connection-level codes on the error or its cause', () => {
     expect(isRetryableConnectError({ cause: { code: 'ECONNRESET' } })).toBe(true);
@@ -156,8 +228,12 @@ describe('createStreamingFetch — against a delayed server', () => {
 describe('withPreResponseRetry', () => {
   // The retry is the OUTERMOST layer (over the dispatcher-bound streaming fetch),
   // matching ai.service's withPreResponseRetry(instrument(createStreamingFetch())).
-  // PRE_RESPONSE_CONNECT_RETRIES is 2 -> at most 3 total attempts.
-  const MAX_ATTEMPTS = 3;
+  // The budget is env-driven (AI_STREAM_PRE_RESPONSE_RETRIES, default 4 -> 5
+  // total attempts). We PIN it to 2 here so the exhaustion test is fast and
+  // deterministic regardless of the default; total attempts = retries + 1 = 3.
+  const RETRIES = 2;
+  const MAX_ATTEMPTS = RETRIES + 1;
+  const ORIG_RETRIES = process.env.AI_STREAM_PRE_RESPONSE_RETRIES;
   let server: http.Server;
   let url: string;
   let requests = 0;
@@ -194,6 +270,13 @@ describe('withPreResponseRetry', () => {
   beforeEach(() => {
     requests = 0;
     resetMode = 'first';
+    process.env.AI_STREAM_PRE_RESPONSE_RETRIES = String(RETRIES);
+  });
+
+  afterEach(() => {
+    if (ORIG_RETRIES === undefined)
+      delete process.env.AI_STREAM_PRE_RESPONSE_RETRIES;
+    else process.env.AI_STREAM_PRE_RESPONSE_RETRIES = ORIG_RETRIES;
   });
 
   it('retries a pre-response reset on a fresh connection and succeeds', async () => {
@@ -216,12 +299,28 @@ describe('withPreResponseRetry', () => {
     expect(caught).toBeDefined();
     // A retryable connection error reached the caller (not swallowed).
     expect(isRetryableConnectError(caught)).toBe(true);
-    // Bounded: exactly PRE_RESPONSE_CONNECT_RETRIES + 1 attempts hit the server
+    // Bounded: exactly AI_STREAM_PRE_RESPONSE_RETRIES + 1 attempts hit the server
     // (pins both the limit and that the final error propagates — guards an
     // off-by-one or an infinite loop).
     expect(requests).toBe(MAX_ATTEMPTS);
   });
 
+  it('honours a raised AI_STREAM_PRE_RESPONSE_RETRIES (more attempts before giving up)', async () => {
+    // Env-driven budget: 4 retries -> 5 total attempts against a persistently
+    // resetting connect.
+    process.env.AI_STREAM_PRE_RESPONSE_RETRIES = '4';
+    resetMode = 'all';
+    let caught: unknown;
+    try {
+      await retryingFetch()(url);
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeDefined();
+    expect(isRetryableConnectError(caught)).toBe(true);
+    expect(requests).toBe(5);
+  });
+
   it('does NOT retry an aborted request (no retry storm)', async () => {
     resetMode = 'all';
     const ctrl = new AbortController();

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

@@ -19,7 +19,7 @@ import { Agent } from 'undici';
 const DEFAULT_STREAM_TIMEOUT_MS = 900_000;
 
 /**
- * Default keep-alive recycle window (10s). A pooled connection idle longer than
+ * Default keep-alive recycle window (4s). A pooled connection idle longer than
  * this is CLOSED rather than reused.
  *
  * Long agent turns leave gaps of tens of seconds between provider calls (one
@@ -30,17 +30,70 @@ const DEFAULT_STREAM_TIMEOUT_MS = 900_000;
  * the resets correlate with idleSincePrevCall ~42s, while a direct path to the
  * provider does NOT reset). Recycling idle sockets well below such a drop window
  * means a long-gap call opens a fresh connection instead of reusing a stale one.
+ * Kept comfortably under common ~5s upstream/middlebox idle cutoffs so undici
+ * recycles the socket before the network kills it, while still long enough to
+ * reuse a connection within a single burst of back-to-back calls (#310).
  * `keepAliveMaxTimeout` also caps a server-advertised keep-alive so the provider
  * cannot push the reuse window back up.
  */
-const DEFAULT_STREAM_KEEPALIVE_MS = 10_000;
+const DEFAULT_STREAM_KEEPALIVE_MS = 4_000;
 
 /**
- * How many times to retry a PRE-RESPONSE connection failure (a reset/timeout
- * before ANY response byte) on a fresh connection. Safe because `fetch()` only
- * rejects before the Response resolves — a started stream is never replayed.
+ * Default number of times to retry a PRE-RESPONSE connection failure (a
+ * reset/timeout before ANY response byte) on a fresh connection. Safe because
+ * `fetch()` only rejects before the Response resolves — a started stream is
+ * never replayed.
+ *
+ * Raised from 2 to 4 (total 5 attempts) so a short BURST of upstream/middlebox
+ * resets is absorbed without exhausting the budget: prod saw 2 of 3 attempts
+ * burned on a single turn, leaving no headroom (#310). Override with
+ * `AI_STREAM_PRE_RESPONSE_RETRIES`.
  */
-const PRE_RESPONSE_CONNECT_RETRIES = 2;
+const DEFAULT_PRE_RESPONSE_CONNECT_RETRIES = 4;
+
+/**
+ * Configured PRE-RESPONSE retry budget. Override with
+ * `AI_STREAM_PRE_RESPONSE_RETRIES`; a missing/invalid/negative value falls back
+ * to {@link DEFAULT_PRE_RESPONSE_CONNECT_RETRIES}. Total attempts = value + 1.
+ * 0 disables the retry (a single attempt).
+ */
+export function preResponseConnectRetries(): number {
+  // Read the raw string first: an empty/whitespace value coerces to 0 via
+  // Number(), which is a VALID setting here (0 = single attempt), so it must be
+  // treated as "unset" rather than "disable the retry".
+  const rawStr = process.env.AI_STREAM_PRE_RESPONSE_RETRIES;
+  if (rawStr === undefined || rawStr.trim() === '') {
+    return DEFAULT_PRE_RESPONSE_CONNECT_RETRIES;
+  }
+  const raw = Number(rawStr);
+  return Number.isFinite(raw) && raw >= 0
+    ? Math.floor(raw)
+    : DEFAULT_PRE_RESPONSE_CONNECT_RETRIES;
+}
+
+/** Base backoff before the first PRE-RESPONSE retry (ms). */
+const PRE_RESPONSE_BACKOFF_BASE_MS = 150;
+
+/** Cap on the exponential backoff window before jitter (ms). */
+const PRE_RESPONSE_BACKOFF_CAP_MS = 2_000;
+
+/**
+ * Backoff (ms) to wait before PRE-RESPONSE retry number `attempt` (0-based).
+ *
+ * Capped exponential with FULL jitter: `delay = random in [0, min(base*2^attempt,
+ * cap)]`. Full jitter spreads concurrent retries across the whole window so a
+ * burst of turns that all reset at once do not reconnect in lock-step and
+ * hammer the upstream in a thundering herd (#310); the exponential growth backs
+ * off harder as resets persist, and the cap keeps the wait bounded.
+ */
+export function preResponseBackoffMs(
+  attempt: number,
+  rand: () => number = Math.random,
+): number {
+  const exp = PRE_RESPONSE_BACKOFF_BASE_MS * 2 ** attempt;
+  const capped = Math.min(exp, PRE_RESPONSE_BACKOFF_CAP_MS);
+  return rand() * capped;
+}
 
 /** undici cause codes for a connection-level failure that occurred PRE-RESPONSE. */
 const RETRYABLE_CONNECT_CODES = new Set([
@@ -177,20 +230,19 @@ export function createStreamingFetch(): typeof fetch {
  */
 export function withPreResponseRetry(baseFetch: typeof fetch): typeof fetch {
   return (async (input: Parameters<typeof fetch>[0], init?: RequestInit) => {
+    const maxRetries = preResponseConnectRetries();
     for (let attempt = 0; ; attempt++) {
       try {
         return await baseFetch(input, init);
       } catch (err) {
         const aborted = init?.signal?.aborted === true;
-        if (
-          aborted ||
-          attempt >= PRE_RESPONSE_CONNECT_RETRIES ||
-          !isRetryableConnectError(err)
-        ) {
+        if (aborted || attempt >= maxRetries || !isRetryableConnectError(err)) {
           throw err;
         }
-        // Brief backoff before the fresh-connection retry.
-        await new Promise((resolve) => setTimeout(resolve, 150 * (attempt + 1)));
+        // Jittered backoff before the fresh-connection retry (anti-thundering-herd).
+        await new Promise((resolve) =>
+          setTimeout(resolve, preResponseBackoffMs(attempt)),
+        );
       }
     }
   }) as typeof fetch;

packages/git-sync/build/engine/client.types.d.ts

@@ -1,109 +0,0 @@
-/**
- * The client seam. `pull.ts`/`push.ts` depend on a narrow STRUCTURAL interface
- * rather than any concrete client, because the gitmost server writes NATIVELY —
- * through repositories + collab `openDirectConnection`.
- *
- * `GitSyncClient` is that interface: the native datasource (server side)
- * implements it, and the engine only ever uses `Pick<GitSyncClient, ...>`
- * subsets of it. The signatures below MIRROR exactly the methods the engine's
- * `pull.ts`/`push.ts` actually call (arg shapes + the fields the engine reads
- * off each result), so a REST-style client is still structurally assignable and
- * the native adapter has a precise contract.
- */
-/**
- * A page node as returned by `listSpaceTree` (the sidebar/tree walk, no body).
- * The engine layout (`buildVaultLayout`) consumes `PageNode` from `./layout`,
- * which only requires `id` (+ optional `title`/`slugId`/`parentPageId`); this
- * lite shape documents the fields the tree walk surfaces. Real tree nodes also
- * carry `position`, `icon`, `hasChildren` — kept open via the index signature.
- */
-export interface GitSyncPageNodeLite {
-    id: string;
-    slugId?: string;
-    title?: string;
-    parentPageId?: string | null;
-    hasChildren?: boolean;
-    /** `listSpaceTree` nodes carry extra fields (position, icon, …). */
-    [key: string]: unknown;
-}
-/**
- * The structural client the engine depends on. Only `Pick<GitSyncClient, ...>`
- * subsets are ever used:
- *   - pull reads:  `getPageJson` (+ the tree walk's `listSpaceTree`),
- *   - push writes: `importPageMarkdown` / `createPage` / `deletePage` /
- *                  `movePage` / `renamePage`,
- *   - continuous (phase B+): `listRecentSince` / `listTrash` / `restorePage`.
- */
-export interface GitSyncClient {
-    /**
-     * Full tree of page nodes for the space (or the subtree rooted at
-     * `rootPageId`), each WITHOUT body content. `complete` is `false` when the
-     * walk was truncated / a fetch failed — the pull side suppresses absence
-     * deletions on an incomplete tree (SPEC §8). Native impl returns
-     * `complete: true` always (reads the DB, not a paginated REST endpoint).
-     */
-    listSpaceTree(spaceId: string, rootPageId?: string): Promise<{
-        pages: GitSyncPageNodeLite[];
-        complete: boolean;
-    }>;
-    /**
-     * One page WITH its ProseMirror body content. `applyPullActions` reads
-     * `id`, `slugId`, `title`, `parentPageId`, `spaceId` (for the file meta) and
-     * `content` (to stabilize/serialize). `updatedAt` is carried for the
-     * poll-suppression loop-guard.
-     */
-    getPageJson(pageId: string): Promise<{
-        id: string;
-        slugId: string;
-        title: string;
-        parentPageId: string | null;
-        spaceId: string;
-        updatedAt: string;
-        content: unknown;
-    }>;
-    /**
-     * Merge a page's body from a self-contained markdown file (meta + body). The
-     * collab/Yjs write path (SPEC §2/§15.6) — never a raw jsonb overwrite.
-     * `applyPushActions` reads only an optional `updatedAt` off the result
-     * (via `extractUpdatedAt`, tolerant of extra fields).
-     *
-     * `baseMarkdown` is the last-synced version of the file (`refs/docmost/
-     * last-pushed`), the common ancestor for a THREE-WAY merge against the live
-     * doc so concurrent human edits survive (review #5). Optional/null -> 2-way.
-     */
-    importPageMarkdown(pageId: string, fullMarkdown: string, baseMarkdown?: string | null): Promise<{
-        updatedAt?: string;
-        [key: string]: unknown;
-    }>;
-    /**
-     * Create a new page and return the assigned id at `data.id`
-     * (`applyPushActions` reads `result.data.id`, then writes it back into the
-     * file's meta). An optional top-level/`data.updatedAt` feeds the loop-guard.
-     */
-    createPage(title: string, content: string, spaceId: string, parentPageId?: string): Promise<{
-        data: {
-            id: string;
-        };
-        updatedAt?: string;
-        [key: string]: unknown;
-    }>;
-    /** Soft-delete a page to Trash (SPEC §8). Result is not inspected. */
-    deletePage(pageId: string): Promise<unknown>;
-    /**
-     * Reparent a page (and optionally set its fractional-index `position`). The
-     * engine passes `position` UNDEFINED for now; the native impl computes a
-     * default between siblings. Result is not inspected.
-     */
-    movePage(pageId: string, parentPageId: string | null, position?: string): Promise<unknown>;
-    /** Change a page's title only (no body touch). Result is not inspected. */
-    renamePage(pageId: string, title: string): Promise<unknown>;
-    /**
-     * Pages updated since `sinceIso` (the poll-safety reconciliation, SPEC §8).
-     * `spaceId` may be undefined (all spaces); `hardPageCap` bounds the walk.
-     */
-    listRecentSince(spaceId: string | undefined, sinceIso: string | null, hardPageCap?: number): Promise<unknown[]>;
-    /** List soft-deleted (trashed) pages for the space (deletion detection). */
-    listTrash(spaceId: string): Promise<unknown[]>;
-    /** Restore a soft-deleted page from Trash. Result is not inspected. */
-    restorePage(pageId: string): Promise<unknown>;
-}

packages/git-sync/build/engine/client.types.js

@@ -1,13 +0,0 @@
-/**
- * The client seam. `pull.ts`/`push.ts` depend on a narrow STRUCTURAL interface
- * rather than any concrete client, because the gitmost server writes NATIVELY —
- * through repositories + collab `openDirectConnection`.
- *
- * `GitSyncClient` is that interface: the native datasource (server side)
- * implements it, and the engine only ever uses `Pick<GitSyncClient, ...>`
- * subsets of it. The signatures below MIRROR exactly the methods the engine's
- * `pull.ts`/`push.ts` actually call (arg shapes + the fields the engine reads
- * off each result), so a REST-style client is still structurally assignable and
- * the native adapter has a precise contract.
- */
-export {};

packages/git-sync/build/engine/config-errors.d.ts

@@ -1 +0,0 @@
-export declare function loadSettingsOrExit<T>(factory: () => T): T;

packages/git-sync/build/engine/config-errors.js

@@ -1,50 +0,0 @@
-import { ZodError } from 'zod';
-// Turn a ZodError from settings validation into a clear, actionable startup
-// message that names the offending env var(s), then exit(1) — no raw stack
-// trace. Mirrors the Python new-project skeleton's load_settings_or_exit.
-// A non-ZodError is left to propagate unchanged.
-export function loadSettingsOrExit(factory) {
-    try {
-        return factory();
-    }
-    catch (err) {
-        if (!(err instanceof ZodError))
-            throw err;
-        const missing = [];
-        const invalid = [];
-        for (const issue of err.issues) {
-            const name = issue.path.length ? String(issue.path[0]) : '?';
-            // A missing required variable surfaces as an `invalid_type` issue whose
-            // received value was `undefined`. zod 3 exposed `issue.received` directly;
-            // zod 4 dropped that field and instead folds it into the message
-            // ("expected string, received undefined"). Detect both shapes so the
-            // missing-vs-invalid split holds across zod majors. NOTE: an invalid (but
-            // present) value uses a different code (invalid_format / invalid_value) or
-            // an `invalid_type` message that reports a non-undefined received (e.g.
-            // "received NaN" from a coerced number), so neither is misread as missing.
-            const i = issue;
-            const isMissing = issue.code === 'invalid_type' &&
-                (i.received === 'undefined' ||
-                    /received undefined/i.test(i.message ?? ''));
-            if (isMissing)
-                missing.push(name);
-            else
-                invalid.push(`${name}: ${issue.message}`);
-        }
-        const lines = ['Configuration error in environment / .env:'];
-        if (missing.length) {
-            lines.push('  Missing required variable(s):');
-            for (const n of [...new Set(missing)])
-                lines.push(`    - ${n}`);
-        }
-        if (invalid.length) {
-            lines.push('  Invalid value(s):');
-            for (const item of invalid)
-                lines.push(`    - ${item}`);
-        }
-        lines.push('');
-        lines.push('Set them in .env (see .env.example) and try again.');
-        process.stderr.write(lines.join('\n') + '\n');
-        process.exit(1);
-    }
-}

packages/git-sync/build/engine/cycle.d.ts

@@ -1,70 +0,0 @@
-import { VaultGit } from "./git.js";
-import { GitSyncClient } from "./client.types.js";
-import { Settings } from "./settings.js";
-/**
- * Absolute-path filesystem primitives the cycle needs. Injected (not imported)
- * so the engine stays IO-free and unit-testable. `mkdir` is recursive; `rm` is
- * force (a missing file is a no-op).
- */
-export interface CycleFs {
-    readFile: (absPath: string) => Promise<string>;
-    writeFile: (absPath: string, text: string) => Promise<void>;
-    mkdir: (absDir: string) => Promise<void>;
-    rm: (absPath: string) => Promise<void>;
-}
-export interface RunCycleDeps {
-    spaceId: string;
-    /** The Docmost seam (reads for pull, writes for push). */
-    client: GitSyncClient;
-    /** The per-space git vault (a real working repo). */
-    vault: VaultGit;
-    /** Engine settings; `vaultPath` roots the relPath -> absolute-path mapping. */
-    settings: Settings;
-    fs: CycleFs;
-    log: (line: string) => void;
-    /**
-     * Delete-cap hook (the ONLY caller-specific policy). Called with the push
-     * dry-run's planned delete count (`Number.POSITIVE_INFINITY` when the dry-run
-     * itself failed, so the hook can fail safe) and the live client; returns the
-     * client to use for the REAL apply. The default (omitted) applies every op
-     * unmodified. gitmost uses it to neutralize deletes when over its cap.
-     *
-     * When omitted, NO dry-run is performed (one fewer push planning pass).
-     */
-    resolveApplyClient?: (plannedDeletes: number, client: GitSyncClient) => GitSyncClient;
-}
-export interface RunCycleResult {
-    ran: boolean;
-    /** Set when the cycle short-circuited without running pull/push. */
-    skipped?: "merge-in-progress";
-    pull?: {
-        written: number;
-        deleted: number;
-        conflict: boolean;
-    };
-    push?: {
-        mode: string;
-        failures: number;
-    };
-}
-/**
- * Run ONE full reconcile cycle for a space: PULL (Docmost -> vault) then PUSH
- * (vault -> Docmost), under the engine's required branch choreography. This is
- * the single entry point the app drives — it owns the staging order so it can
- * never drift from the engine it ships with.
- *
- * Staging (the ⭐ data-loss-critical order, SPEC §6/§9):
- *   1. assertGitAvailable + ensureRepo (the git state store must exist).
- *   2. refuse on an unresolved merge (a prior conflicting pull); next checkout
- *      would fail otherwise.
- *   3. ensureBranch('docmost','main') + checkout('docmost'). Pull writes MUST
- *      land on `docmost`, not `main`: applyPullActions commits on `docmost`,
- *      then checks out `main` and merges docmost -> main. Writing Docmost
- *      content straight onto `main` would clobber local file edits before push
- *      can diff them.
- *   4. PULL: readExisting -> listSpaceTree -> computePullActions -> apply.
- *   5. PUSH: optional dry-run to feed the delete-cap hook, then the real apply.
- *
- * Lock + cap POLICY live in the caller; this owns only the mechanics.
- */
-export declare function runCycle(deps: RunCycleDeps): Promise<RunCycleResult>;

packages/git-sync/build/engine/cycle.js

@@ -1,97 +0,0 @@
-import { readExisting, computePullActions, applyPullActions } from "./pull.js";
-import { runPush } from "./push.js";
-/**
- * Run ONE full reconcile cycle for a space: PULL (Docmost -> vault) then PUSH
- * (vault -> Docmost), under the engine's required branch choreography. This is
- * the single entry point the app drives — it owns the staging order so it can
- * never drift from the engine it ships with.
- *
- * Staging (the ⭐ data-loss-critical order, SPEC §6/§9):
- *   1. assertGitAvailable + ensureRepo (the git state store must exist).
- *   2. refuse on an unresolved merge (a prior conflicting pull); next checkout
- *      would fail otherwise.
- *   3. ensureBranch('docmost','main') + checkout('docmost'). Pull writes MUST
- *      land on `docmost`, not `main`: applyPullActions commits on `docmost`,
- *      then checks out `main` and merges docmost -> main. Writing Docmost
- *      content straight onto `main` would clobber local file edits before push
- *      can diff them.
- *   4. PULL: readExisting -> listSpaceTree -> computePullActions -> apply.
- *   5. PUSH: optional dry-run to feed the delete-cap hook, then the real apply.
- *
- * Lock + cap POLICY live in the caller; this owns only the mechanics.
- */
-export async function runCycle(deps) {
-    const { spaceId, client, vault, settings, fs, log, resolveApplyClient } = deps;
-    const vaultRoot = settings.vaultPath;
-    const abs = (relPath) => `${vaultRoot}/${relPath}`;
-    // 1. The engine state store is git: make sure the repo + branches exist
-    //    before any tracked-file listing or diff.
-    await vault.assertGitAvailable();
-    await vault.ensureRepo();
-    // 2. Refuse to run on top of an unresolved merge (SPEC §9): a prior
-    //    conflicting pull leaves the vault mid-merge; the next checkout would fail.
-    if (await vault.isMergeInProgress()) {
-        log(`vault has an unresolved merge — resolve it (or 'git merge --abort') ` +
-            `and re-run (SPEC §9); skipping cycle.`);
-        return { ran: false, skipped: "merge-in-progress" };
-    }
-    // 3. Pull writes happen on `docmost`; be on it BEFORE applying (see docstring).
-    await vault.ensureBranch("docmost", "main");
-    await vault.checkout("docmost");
-    // 4. PULL --------------------------------------------------------------------
-    const existing = await readExisting({
-        listTracked: () => vault.listTrackedFiles("*.md"),
-        readFile: (relPath) => fs.readFile(abs(relPath)),
-    });
-    const tree = await client.listSpaceTree(spaceId);
-    const pullActions = computePullActions({
-        pages: tree.pages,
-        treeComplete: tree.complete,
-        existing,
-    });
-    const pullResult = await applyPullActions({
-        client,
-        git: vault,
-        writeFile: (absPath, text) => fs.writeFile(absPath, text),
-        mkdir: (absDir) => fs.mkdir(absDir),
-        rm: (absPath) => fs.rm(absPath),
-    }, pullActions, vaultRoot);
-    // 5. PUSH --------------------------------------------------------------------
-    const pushDeps = {
-        settings,
-        git: vault,
-        makeClient: () => client,
-        readFile: (relPath) => fs.readFile(abs(relPath)),
-        writeFile: (relPath, text) => fs.writeFile(abs(relPath), text),
-        log,
-    };
-    let applyClient = client;
-    if (resolveApplyClient) {
-        // Plan the push as a DRY-RUN first to read the delete count, then let the
-        // caller decide the apply client (e.g. neutralize deletes over a cap). A
-        // failed dry-run yields Infinity so the hook can fail safe.
-        let plannedDeletes;
-        try {
-            const dry = await runPush(pushDeps, { dryRun: true });
-            plannedDeletes = dry.planned?.deletes ?? 0;
-        }
-        catch (err) {
-            log(`push dry-run planning failed (${err instanceof Error ? err.message : String(err)}); deferring deletion policy to the cap hook (fail-safe).`);
-            plannedDeletes = Number.POSITIVE_INFINITY;
-        }
-        applyClient = resolveApplyClient(plannedDeletes, client);
-    }
-    const pushResult = await runPush({ ...pushDeps, makeClient: () => applyClient }, { dryRun: false });
-    return {
-        ran: true,
-        pull: {
-            written: pullResult.written,
-            deleted: pullResult.deleted,
-            conflict: pullResult.merge.conflict,
-        },
-        push: {
-            mode: pushResult.mode,
-            failures: pushResult.failures?.length ?? 0,
-        },
-    };
-}

packages/git-sync/build/engine/git.d.ts

@@ -1,259 +0,0 @@
-/** Bot identity used for engine-authored vault commits (SPEC §7.3). */
-export declare const BOT_AUTHOR_NAME = "Docmost Sync";
-export declare const BOT_AUTHOR_EMAIL = "docmost-sync@local";
-/** Default branch the vault repo is initialized on. */
-export declare const DEFAULT_BRANCH = "main";
-/**
- * One row of `git diff --name-status` (SPEC §6 "ФС → Docmost"). `status` is the
- * single-letter change code (`-M` rename detection on), `path` is the (new) file
- * path; for a rename/copy (`R`/`C`) `oldPath` is the source and `path` is the
- * destination, with `score` carrying git's similarity index (0–100).
- */
-export interface DiffEntry {
-    status: "A" | "M" | "D" | "R" | "C";
-    /** New (destination) path. For A/M/D it is the only path. */
-    path: string;
-    /** Source path — present only for R/C. */
-    oldPath?: string;
-    /** Rename/copy similarity score (0–100) — present only for R/C. */
-    score?: number;
-}
-/** Result of a `merge`: whether it succeeded cleanly or left conflict markers. */
-export interface MergeResult {
-    /** True when the merge applied cleanly (fast-forward or clean 3-way). */
-    ok: boolean;
-    /** True when the merge stopped on conflicts (markers left in the worktree). */
-    conflict: boolean;
-    /** Raw combined stdout+stderr, for logging/diagnostics. */
-    output: string;
-}
-/** Options for an engine-authored commit (provenance, SPEC §7.3). */
-export interface CommitOptions {
-    authorName: string;
-    authorEmail: string;
-    /**
-     * Trailer lines appended to the commit message body (e.g.
-     * `Docmost-Sync-Source: docmost`). These are the machine-readable provenance
-     * the loop-guard keys on (SPEC §12, "commit-attribution").
-     */
-    trailers?: string[];
-}
-/**
- * A git wrapper bound to a single vault path. Construct once per vault; every
- * method runs git with `cwd = vaultPath`.
- */
-export declare class VaultGit {
-    private readonly vaultPath;
-    constructor(vaultPath: string);
-    /**
-     * Preflight: verify a runnable `git` binary is on PATH. The daemon shells out
-     * to system `git` for every vault operation, so a missing binary (e.g. a slim
-     * container image without git) must fail fast with an actionable message
-     * rather than a cryptic ENOENT deep inside the first real git call. Presence
-     * check only — we do NOT gate on a specific version. Runs `git --version`
-     * with NO `cwd` (the vault dir may not exist yet at preflight time).
-     */
-    assertGitAvailable(): Promise<void>;
-    /**
-     * Run a git command in the vault and return trimmed stdout. THIN wrapper over
-     * the single `runRaw` primitive: throws a clear, unified Error (including
-     * stderr/stdout) on a non-zero exit.
-     */
-    private run;
-    /**
-     * The ONE primitive every git invocation in this module flows through. Builds
-     * the full argv (`--no-pager -c core.quotepath=false <args>`), env, cwd, and
-     * maxBuffer, runs git, and NEVER throws — it returns the exit info so callers
-     * can treat a non-zero exit as either an error (`run`) or a meaningful state
-     * (e.g. a merge conflict, a porcelain diff that "fails" deliberately).
-     *
-     *   - argv: ALWAYS prepends `--no-pager -c core.quotepath=false`, so git never
-     *     blocks on a pager and always prints verbatim UTF-8 paths (no octal
-     *     escaping/quoting). `quotepath=false` is the baseline for ALL path-
-     *     printing commands (ls-files, diff --name-only, …).
-     *   - cwd: `opts.cwd === null` -> do NOT set cwd (the preflight, where the
-     *     vault dir may not exist); otherwise `opts.cwd ?? this.vaultPath`.
-     *   - env: `vaultGitEnv(opts?.env)` (cwd-isolation + caller extras).
-     *   - On a spawn/exec error we capture the error `message` too, so a failure
-     *     before git could write to stderr (e.g. ENOENT) is NOT lost.
-     */
-    private runRaw;
-    /**
-     * Ensure the vault directory exists and is an initialized git repo on `main`
-     * with an initial (empty) commit so branches exist. Idempotent: safe to call
-     * on every run. Sets a LOCAL bot identity for the vault repo if none is set
-     * (so engine commits never fall back to a global/unset identity).
-     */
-    ensureRepo(): Promise<void>;
-    /** True if `cwd` is inside a git work-tree (the vault is initialized). */
-    private isRepo;
-    /** True if a LOCAL git config key is set in the vault repo. */
-    private hasLocalConfig;
-    /** True if the repo has at least one commit (HEAD resolves). */
-    private hasAnyCommit;
-    /** True if a branch with the given name exists. */
-    branchExists(name: string): Promise<boolean>;
-    /**
-     * Create `name` from `fromBranch` if it does not already exist. No-op (and no
-     * checkout) when the branch is already present.
-     */
-    ensureBranch(name: string, fromBranch: string): Promise<void>;
-    /** Name of the currently checked-out branch. */
-    currentBranch(): Promise<string>;
-    /** Check out an existing branch. */
-    checkout(name: string): Promise<void>;
-    /** Stage everything (adds, modifications, deletions). */
-    stageAll(): Promise<void>;
-    /**
-     * True if the vault is mid-merge (an unresolved merge from a previous run,
-     * SPEC §9 / §12). Detected via a `MERGE_HEAD` ref OR any unmerged
-     * (conflicted) index entries (`git ls-files -u`). The pull cycle checks this
-     * BEFORE any checkout so a left-over merge produces a clear, actionable
-     * message instead of a raw "you need to resolve your current index first"
-     * failure deep inside `checkout`. This is what makes re-runs converge
-     * (resumability, SPEC §12).
-     */
-    isMergeInProgress(): Promise<boolean>;
-    /**
-     * Commit the currently STAGED changes with an explicit author/committer
-     * identity and the given trailers appended to the message body (SPEC §7.3
-     * provenance). Returns `true` if a commit was made, `false` if there was
-     * nothing to commit (graceful no-op). The caller is expected to have staged
-     * its changes first (e.g. via `stageAll`).
-     */
-    commit(message: string, opts: CommitOptions): Promise<boolean>;
-    /**
-     * Low-level commit used by both `commit` and `ensureRepo`'s initial commit.
-     * Builds the full message with appended trailers and sets author + committer
-     * identity via env vars (so the committer matches the author, not the repo
-     * default).
-     */
-    private commitRaw;
-    /**
-     * Merge `fromBranch` into the current branch (`git merge --no-edit`).
-     * Fast-forwards when possible; performs a real 3-way merge otherwise. Conflict
-     * state is SURFACED (returned), NOT auto-resolved (SPEC §9): the conflict
-     * markers are left in the worktree for manual resolution by a later increment,
-     * and — critically — nothing is pushed to Docmost (we never write to Docmost
-     * anyway).
-     */
-    merge(fromBranch: string): Promise<MergeResult>;
-    /** True if the index has any unmerged (conflicted) paths. */
-    private hasUnmergedPaths;
-    /**
-     * List tracked files on the current branch (paths relative to the vault
-     * root, forward-slash separated). An optional glob (a git pathspec) narrows
-     * the listing, e.g. `"*.md"`.
-     *
-     * The target wiki is RUSSIAN, so vault file names routinely contain Cyrillic
-     * (e.g. `Колонка.md`). With git's DEFAULT `core.quotepath=true`, `ls-files`
-     * returns non-ASCII paths octal-escaped and double-quoted (`"\320\232..."`),
-     * which `src/pull.ts` `readExisting` would then parse as garbage paths,
-     * breaking move/duplicate detection. We defeat that two ways at once:
-     *   - `core.quotepath=false` disables the octal-escape/quoting. It is now the
-     *     `runRaw` argv baseline (prepended to EVERY invocation), so we no longer
-     *     pass it inline here.
-     *   - `-z` emits NUL-delimited RAW UTF-8 paths (no quoting, no newline
-     *     ambiguity), which we split on `\0`.
-     * We read the RAW stdout (NOT the trimming `run()` helper, which would mangle
-     * the NUL-delimited bytes) and split on `\0`, dropping empty entries. Paths
-     * are returned verbatim — git already emits forward slashes.
-     */
-    listTrackedFiles(glob?: string): Promise<string[]>;
-    /**
-     * Diff two refs with `--name-status -M -z` and parse the NUL-delimited output
-     * (SPEC §6: the FS→Docmost push direction diffs `main` against
-     * `refs/docmost/last-pushed`). Rename detection is ON (`-M`), so a moved/renamed
-     * file is reported as a single `R` row with both its old and new path instead
-     * of a delete+add pair — that distinction is what lets the push planner tell a
-     * move from a delete+create (SPEC §8 "Move vs delete").
-     *
-     * `-z` makes git emit NUL-delimited RAW UTF-8 records (the Russian wiki has
-     * Cyrillic file names) with NO quoting/escaping. The record shape differs by
-     * status:
-     *   - A/M/D:  `status\0path\0`
-     *   - R/C:    `Rnnn\0oldPath\0newPath\0`  (nnn = similarity score, e.g. `R100`)
-     * We read the RAW stdout (not the trimming `run()` helper, which would mangle
-     * the NUL bytes), split on `\0`, drop the trailing empty entry, and walk the
-     * tokens pulling 1 or 2 path tokens per status. Paths are returned verbatim.
-     */
-    diffNameStatus(fromRef: string, toRef: string): Promise<DiffEntry[]>;
-    /**
-     * Resolve a ref/commit-ish to its full SHA, or `null` if it does not exist.
-     * `rev-parse --verify --quiet` exits non-zero (and prints nothing) for an
-     * unknown ref, so a non-zero exit maps cleanly to `null`. Used to read
-     * `refs/docmost/last-pushed` (SPEC §5) — which is absent before the first push.
-     */
-    revParse(ref: string): Promise<string | null>;
-    /**
-     * Read a ref to its SHA, or `null` if unset. Thin alias over `revParse`,
-     * named for the push direction's marker `refs/docmost/last-pushed` (SPEC §5:
-     * "что из `main` уже отражено в Docmost").
-     */
-    readRef(ref: string): Promise<string | null>;
-    /**
-     * Point `ref` at `target` (`git update-ref <ref> <target>`). Used to advance
-     * `refs/docmost/last-pushed` to the just-pushed `main` commit after a push
-     * (SPEC §6 step 3 / §5). `target` may be a SHA or any commit-ish git accepts.
-     */
-    updateRef(ref: string, target: string): Promise<void>;
-    /**
-     * Fast-forward `branch` to `toCommit` — but ONLY if it is a TRUE fast-forward,
-     * i.e. the current `branch` tip is an ancestor of `toCommit` (verified via
-     * `git merge-base --is-ancestor <branch> <toCommit>`). Used to advance the
-     * `docmost` mirror branch after a clean push (SPEC §6 step 3 / §10): once a
-     * push succeeds, Docmost already contains the pushed `main` content, so the
-     * mirror must reflect it — otherwise the NEXT pull would diff our own write
-     * back and re-pull it (loop-guard).
-     *
-     * SAFETY — never force, never clobber divergent history:
-     *   - If `branch` IS an ancestor of `toCommit`, advance it with
-     *     `git update-ref refs/heads/<branch> <toCommit>`. The `docmost` branch is
-     *     NOT checked out during a push (push works on `main`), so updating the ref
-     *     directly is safe and avoids any working-tree touch.
-     *   - If `branch` is NOT an ancestor (divergent / would-be non-fast-forward),
-     *     do NOT move it — return `{ ok: false, reason: 'not-fast-forward' }` and
-     *     let the caller log it. We must never overwrite a `docmost` history that
-     *     has commits the push base does not contain.
-     *
-     * Returns `{ ok: true }` when the branch was advanced (or already at
-     * `toCommit`, a degenerate fast-forward), `{ ok: false, reason }` otherwise.
-     * A missing `branch` or `toCommit` also yields `{ ok: false }` with a reason.
-     */
-    fastForwardBranch(branch: string, toCommit: string): Promise<{
-        ok: boolean;
-        reason?: string;
-    }>;
-    /**
-     * Read a file's content at a specific ref (`git show <ref>:<path>`), or `null`
-     * if the path does not exist there. Used by the push direction to read the
-     * PRE-IMAGE of a DELETED file (e.g. at `refs/docmost/last-pushed`) so its
-     * `docmost:meta` — and therefore its `pageId` — can be recovered to translate
-     * the deletion into a `delete_page` (SPEC §6/§8: only TRACKED files, i.e. ones
-     * that had a pageId, are deleted in Docmost). A non-zero exit (path absent at
-     * that ref) maps to `null` rather than throwing.
-     */
-    showFileAtRef(ref: string, path: string): Promise<string | null>;
-}
-/**
- * Build the environment for a vault git invocation (SPEC §12 cwd-isolation).
- * Used by the single `runRaw` primitive every git command flows through, so
- * these pins apply uniformly (including the `git --version` preflight).
- *
- * cwd-isolation is this module's central safety guarantee: every git command
- * MUST operate on the vault repo at `cwd: vaultPath` and nothing else. An
- * inherited `GIT_DIR` / `GIT_WORK_TREE` in `process.env` would silently
- * redirect the operation away from `cwd` (e.g. to the source repo or another
- * checkout), defeating that guarantee. So we always strip them, regardless of
- * whatever else the caller adds (author/committer identity, etc.).
- *
- * Exported for unit testing.
- */
-export declare function vaultGitEnv(extra?: Record<string, string>): NodeJS.ProcessEnv;
-/**
- * Build a commit message body with trailer lines appended (SPEC §7.3). The
- * trailers are separated from the subject by a blank line so `git interpret-
- * trailers` / `git log --format=%(trailers)` parse them as trailers.
- * Exported for unit testing.
- */
-export declare function buildCommitMessage(subject: string, trailers?: string[]): string;

packages/git-sync/build/engine/git.js

@@ -1,570 +0,0 @@
-/**
- * Thin async wrapper over the system `git` binary (SPEC §5: state store = git).
- *
- * IMPORTANT — VAULT-SCOPED: every operation here runs with `cwd = vaultPath`,
- * which is the vault's OWN git repository (default `data/vault`), SEPARATE from
- * the gitmost application repo. This module MUST NEVER run git against the
- * application repo. `data/` is gitignored, so a nested repo under `data/vault`
- * is safe. The pull cycle is READ-ONLY toward Docmost; this module only touches
- * the local vault git, never a git remote (push is deferred, see SPEC §7).
- *
- * Implementation notes:
- *   - We shell out via `node:child_process` `execFile` (promisified), passing
- *     ARGS AS AN ARRAY — no shell, so there is no command injection surface even
- *     if a page title / branch name contains shell metacharacters.
- *   - EVERY git invocation funnels through the single `runRaw` primitive, which
- *     ALWAYS prepends `--no-pager -c core.quotepath=false` to the argv (so git
- *     never blocks on a pager and always prints verbatim UTF-8 paths). There is
- *     no exception — even the `git --version` preflight goes through `runRaw`.
- *   - "nothing to commit" is treated as a graceful no-op, not an error.
- */
-import { execFile } from "node:child_process";
-import { mkdir } from "node:fs/promises";
-import { promisify } from "node:util";
-const execFileAsync = promisify(execFile);
-/** Bot identity used for engine-authored vault commits (SPEC §7.3). */
-export const BOT_AUTHOR_NAME = "Docmost Sync";
-export const BOT_AUTHOR_EMAIL = "docmost-sync@local";
-/** Default branch the vault repo is initialized on. */
-export const DEFAULT_BRANCH = "main";
-/**
- * A git wrapper bound to a single vault path. Construct once per vault; every
- * method runs git with `cwd = vaultPath`.
- */
-export class VaultGit {
-    vaultPath;
-    constructor(vaultPath) {
-        this.vaultPath = vaultPath;
-    }
-    /**
-     * Preflight: verify a runnable `git` binary is on PATH. The daemon shells out
-     * to system `git` for every vault operation, so a missing binary (e.g. a slim
-     * container image without git) must fail fast with an actionable message
-     * rather than a cryptic ENOENT deep inside the first real git call. Presence
-     * check only — we do NOT gate on a specific version. Runs `git --version`
-     * with NO `cwd` (the vault dir may not exist yet at preflight time).
-     */
-    async assertGitAvailable() {
-        // Goes through the single `runRaw` primitive like every other invocation.
-        // `cwd: null` means "do not set a cwd" — the vault dir may not exist yet at
-        // preflight time, so we must not point git at a missing directory.
-        const r = await this.runRaw(["--version"], { cwd: null });
-        if (r.code !== 0) {
-            const detail = (r.stderr || r.stdout || "").trim();
-            throw new Error("git binary not found or not runnable — install git (the vault state " +
-                `store requires it). Underlying error: ${detail}`);
-        }
-    }
-    /**
-     * Run a git command in the vault and return trimmed stdout. THIN wrapper over
-     * the single `runRaw` primitive: throws a clear, unified Error (including
-     * stderr/stdout) on a non-zero exit.
-     */
-    async run(args, opts) {
-        const r = await this.runRaw(args, opts);
-        if (r.code !== 0) {
-            const detail = (r.stderr || r.stdout || "").trim();
-            throw new Error(`git ${args.join(" ")} failed: ${detail}`);
-        }
-        return r.stdout.trim();
-    }
-    /**
-     * The ONE primitive every git invocation in this module flows through. Builds
-     * the full argv (`--no-pager -c core.quotepath=false <args>`), env, cwd, and
-     * maxBuffer, runs git, and NEVER throws — it returns the exit info so callers
-     * can treat a non-zero exit as either an error (`run`) or a meaningful state
-     * (e.g. a merge conflict, a porcelain diff that "fails" deliberately).
-     *
-     *   - argv: ALWAYS prepends `--no-pager -c core.quotepath=false`, so git never
-     *     blocks on a pager and always prints verbatim UTF-8 paths (no octal
-     *     escaping/quoting). `quotepath=false` is the baseline for ALL path-
-     *     printing commands (ls-files, diff --name-only, …).
-     *   - cwd: `opts.cwd === null` -> do NOT set cwd (the preflight, where the
-     *     vault dir may not exist); otherwise `opts.cwd ?? this.vaultPath`.
-     *   - env: `vaultGitEnv(opts?.env)` (cwd-isolation + caller extras).
-     *   - On a spawn/exec error we capture the error `message` too, so a failure
-     *     before git could write to stderr (e.g. ENOENT) is NOT lost.
-     */
-    async runRaw(args, opts) {
-        const cwd = opts?.cwd === null ? undefined : (opts?.cwd ?? this.vaultPath);
-        try {
-            const { stdout, stderr } = await execFileAsync("git", ["--no-pager", "-c", "core.quotepath=false", ...args], {
-                // Generous buffer: file listings / porcelain output on a large vault
-                // can be sizable.
-                ...(cwd !== undefined ? { cwd } : {}),
-                maxBuffer: 64 * 1024 * 1024,
-                env: vaultGitEnv(opts?.env),
-            });
-            return { code: 0, stdout, stderr };
-        }
-        catch (err) {
-            const e = err;
-            return {
-                code: typeof e.code === "number" ? e.code : 1,
-                stdout: e.stdout ?? "",
-                // Preserve the error message when there is no stderr (e.g. a spawn
-                // failure like ENOENT, where promisified execFile sets stderr to an
-                // EMPTY STRING — so `||`, not `??`, to fall through to `message`).
-                stderr: e.stderr || e.message || "",
-            };
-        }
-    }
-    /**
-     * Ensure the vault directory exists and is an initialized git repo on `main`
-     * with an initial (empty) commit so branches exist. Idempotent: safe to call
-     * on every run. Sets a LOCAL bot identity for the vault repo if none is set
-     * (so engine commits never fall back to a global/unset identity).
-     */
-    async ensureRepo() {
-        await mkdir(this.vaultPath, { recursive: true });
-        if (!(await this.isRepo())) {
-            // `git init -b main` sets the initial branch on modern git; we still
-            // guard the branch name below for safety on older binaries.
-            await this.run(["init", "-b", DEFAULT_BRANCH]);
-        }
-        // Set a local identity for the vault repo if unset, so engine commits have
-        // a deterministic committer even on a machine with no global git config.
-        if (!(await this.hasLocalConfig("user.name"))) {
-            await this.run(["config", "user.name", BOT_AUTHOR_NAME]);
-        }
-        if (!(await this.hasLocalConfig("user.email"))) {
-            await this.run(["config", "user.email", BOT_AUTHOR_EMAIL]);
-        }
-        // Neutralize correctness-affecting git config in the vault's LOCAL config so
-        // a user's GLOBAL/system config cannot change porcelain BEHAVIOR (not just
-        // output) and corrupt the vault. The vault is OUR dedicated repo, so LOCAL
-        // values (which override global/system) are the right scope. Set
-        // UNCONDITIONALLY every run — idempotent and cheap; `git config <key>`
-        // writes to `--local` by default inside the repo. These MUST be in place
-        // before any add/commit/checkout that could be affected, hence they run
-        // before the initial-commit block below.
-        //   - core.autocrlf=false — CRITICAL (SPEC §11): a global core.autocrlf=true
-        //     would rewrite LF<->CRLF on add/checkout, making our deterministic,
-        //     byte-stable markdown churn and breaking the round-trip invariant.
-        //     `false` guarantees git stores/checks out verbatim bytes.
-        //   - core.safecrlf=false — avoid CRLF-related warnings/aborts on add.
-        //   - commit.gpgsign=false — the headless daemon must never try to GPG-sign
-        //     a commit (would fail/hang; we already set GIT_TERMINAL_PROMPT=0).
-        //   - core.attributesFile=/dev/null — neutralize the user's GLOBAL
-        //     gitattributes so a global clean/smudge filter (filter.<name>.clean)
-        //     cannot rewrite the STORED blob and break §11 byte-stability (a config
-        //     that core.autocrlf=false does not cover). POSIX-only path, which is
-        //     fine: the daemon runs on Linux (Docker) / macOS. A system
-        //     /etc/gitattributes remains the host admin's domain (out of scope).
-        // NOTE: these stay PERSISTED LOCAL config (not `-c` flags) on purpose — a
-        // human running git by hand in the vault must inherit the same neutralized
-        // behavior; a transient `-c` would not persist. (core.quotepath, by
-        // contrast, only affects OUR parsing of output and so is baked into the
-        // `runRaw` argv baseline instead.)
-        try {
-            await this.run(["config", "core.autocrlf", "false"]);
-            await this.run(["config", "core.safecrlf", "false"]);
-            await this.run(["config", "commit.gpgsign", "false"]);
-            await this.run(["config", "core.attributesFile", "/dev/null"]);
-        }
-        catch (err) {
-            const detail = err instanceof Error ? err.message : String(err);
-            throw new Error(`failed to pin vault git config (SPEC §11) — ensure ${this.vaultPath}` +
-                "/.git/config is writable and not locked (e.g. stale config.lock): " +
-                detail);
-        }
-        // Create the initial empty commit on `main` if the repo has no commits yet,
-        // so both `main` and (later) `docmost` branches have a common base.
-        if (!(await this.hasAnyCommit())) {
-            // Make sure we are on the default branch before the first commit (covers
-            // the older-git case where `init -b` was not honored).
-            await this.run(["checkout", "-B", DEFAULT_BRANCH]);
-            await this.commitRaw("init vault", {
-                authorName: BOT_AUTHOR_NAME,
-                authorEmail: BOT_AUTHOR_EMAIL,
-                allowEmpty: true,
-            });
-        }
-    }
-    /** True if `cwd` is inside a git work-tree (the vault is initialized). */
-    async isRepo() {
-        const r = await this.runRaw(["rev-parse", "--is-inside-work-tree"]);
-        return r.code === 0 && r.stdout.trim() === "true";
-    }
-    /** True if a LOCAL git config key is set in the vault repo. */
-    async hasLocalConfig(key) {
-        const r = await this.runRaw(["config", "--local", "--get", key]);
-        return r.code === 0 && r.stdout.trim().length > 0;
-    }
-    /** True if the repo has at least one commit (HEAD resolves). */
-    async hasAnyCommit() {
-        const r = await this.runRaw(["rev-parse", "--verify", "HEAD"]);
-        return r.code === 0;
-    }
-    /** True if a branch with the given name exists. */
-    async branchExists(name) {
-        const r = await this.runRaw([
-            "rev-parse",
-            "--verify",
-            `refs/heads/${name}`,
-        ]);
-        return r.code === 0;
-    }
-    /**
-     * Create `name` from `fromBranch` if it does not already exist. No-op (and no
-     * checkout) when the branch is already present.
-     */
-    async ensureBranch(name, fromBranch) {
-        if (await this.branchExists(name))
-            return;
-        await this.run(["branch", name, fromBranch]);
-    }
-    /** Name of the currently checked-out branch. */
-    async currentBranch() {
-        return this.run(["rev-parse", "--abbrev-ref", "HEAD"]);
-    }
-    /** Check out an existing branch. */
-    async checkout(name) {
-        await this.run(["checkout", name]);
-    }
-    /** Stage everything (adds, modifications, deletions). */
-    async stageAll() {
-        await this.run(["add", "-A"]);
-    }
-    /**
-     * True if the vault is mid-merge (an unresolved merge from a previous run,
-     * SPEC §9 / §12). Detected via a `MERGE_HEAD` ref OR any unmerged
-     * (conflicted) index entries (`git ls-files -u`). The pull cycle checks this
-     * BEFORE any checkout so a left-over merge produces a clear, actionable
-     * message instead of a raw "you need to resolve your current index first"
-     * failure deep inside `checkout`. This is what makes re-runs converge
-     * (resumability, SPEC §12).
-     */
-    async isMergeInProgress() {
-        // MERGE_HEAD exists exactly while a merge is in progress.
-        const mergeHead = await this.runRaw([
-            "rev-parse",
-            "--verify",
-            "--quiet",
-            "MERGE_HEAD",
-        ]);
-        if (mergeHead.code === 0 && mergeHead.stdout.trim().length > 0)
-            return true;
-        // Fallback / belt-and-suspenders: any unmerged index entries also mean the
-        // working tree is mid-conflict and a checkout would refuse.
-        const unmerged = await this.runRaw(["ls-files", "-u"]);
-        return unmerged.code === 0 && unmerged.stdout.trim().length > 0;
-    }
-    /**
-     * Commit the currently STAGED changes with an explicit author/committer
-     * identity and the given trailers appended to the message body (SPEC §7.3
-     * provenance). Returns `true` if a commit was made, `false` if there was
-     * nothing to commit (graceful no-op). The caller is expected to have staged
-     * its changes first (e.g. via `stageAll`).
-     */
-    async commit(message, opts) {
-        // Nothing staged -> nothing to commit. Treat as a no-op (SPEC §11: a
-        // deterministic re-pull of unchanged pages produces identical bytes, so
-        // git sees no diff and we must not error).
-        const staged = await this.runRaw([
-            "diff",
-            "--cached",
-            "--quiet",
-        ]);
-        // `diff --cached --quiet` exits 0 when the index matches HEAD (nothing
-        // staged), 1 when there are staged changes.
-        if (staged.code === 0)
-            return false;
-        await this.commitRaw(message, opts);
-        return true;
-    }
-    /**
-     * Low-level commit used by both `commit` and `ensureRepo`'s initial commit.
-     * Builds the full message with appended trailers and sets author + committer
-     * identity via env vars (so the committer matches the author, not the repo
-     * default).
-     */
-    async commitRaw(message, opts) {
-        const fullMessage = buildCommitMessage(message, opts.trailers);
-        // `--no-verify` skips pre-commit/commit-msg hooks: a global core.hooksPath
-        // (or any injected hook) must never interfere with engine commits in our
-        // dedicated vault repo.
-        const args = ["commit", "--no-verify", "-m", fullMessage];
-        if (opts.allowEmpty)
-            args.push("--allow-empty");
-        // Route through the single `runRaw` primitive; set author + committer
-        // identity via env vars (so the committer matches the author, not the repo
-        // default). Throw via the same unified message on a non-zero exit.
-        const r = await this.runRaw(args, {
-            env: {
-                GIT_AUTHOR_NAME: opts.authorName,
-                GIT_AUTHOR_EMAIL: opts.authorEmail,
-                GIT_COMMITTER_NAME: opts.authorName,
-                GIT_COMMITTER_EMAIL: opts.authorEmail,
-            },
-        });
-        if (r.code !== 0) {
-            const detail = (r.stderr || r.stdout || "").trim();
-            throw new Error(`git ${args.join(" ")} failed: ${detail}`);
-        }
-    }
-    /**
-     * Merge `fromBranch` into the current branch (`git merge --no-edit`).
-     * Fast-forwards when possible; performs a real 3-way merge otherwise. Conflict
-     * state is SURFACED (returned), NOT auto-resolved (SPEC §9): the conflict
-     * markers are left in the worktree for manual resolution by a later increment,
-     * and — critically — nothing is pushed to Docmost (we never write to Docmost
-     * anyway).
-     */
-    async merge(fromBranch) {
-        const r = await this.runRaw(["merge", "--no-edit", fromBranch]);
-        const output = `${r.stdout}\n${r.stderr}`.trim();
-        if (r.code === 0) {
-            return { ok: true, conflict: false, output };
-        }
-        // A non-zero exit on merge most commonly means a conflict. Confirm by
-        // checking for unmerged paths (porcelain "U" status) so we don't mislabel
-        // an unrelated failure as a conflict.
-        const conflict = await this.hasUnmergedPaths();
-        return { ok: false, conflict, output };
-    }
-    /** True if the index has any unmerged (conflicted) paths. */
-    async hasUnmergedPaths() {
-        const r = await this.runRaw(["diff", "--name-only", "--diff-filter=U"]);
-        return r.code === 0 && r.stdout.trim().length > 0;
-    }
-    /**
-     * List tracked files on the current branch (paths relative to the vault
-     * root, forward-slash separated). An optional glob (a git pathspec) narrows
-     * the listing, e.g. `"*.md"`.
-     *
-     * The target wiki is RUSSIAN, so vault file names routinely contain Cyrillic
-     * (e.g. `Колонка.md`). With git's DEFAULT `core.quotepath=true`, `ls-files`
-     * returns non-ASCII paths octal-escaped and double-quoted (`"\320\232..."`),
-     * which `src/pull.ts` `readExisting` would then parse as garbage paths,
-     * breaking move/duplicate detection. We defeat that two ways at once:
-     *   - `core.quotepath=false` disables the octal-escape/quoting. It is now the
-     *     `runRaw` argv baseline (prepended to EVERY invocation), so we no longer
-     *     pass it inline here.
-     *   - `-z` emits NUL-delimited RAW UTF-8 paths (no quoting, no newline
-     *     ambiguity), which we split on `\0`.
-     * We read the RAW stdout (NOT the trimming `run()` helper, which would mangle
-     * the NUL-delimited bytes) and split on `\0`, dropping empty entries. Paths
-     * are returned verbatim — git already emits forward slashes.
-     */
-    async listTrackedFiles(glob) {
-        const r = await this.runRaw(["ls-files", "-z", ...(glob ? [glob] : [])]);
-        if (r.code !== 0) {
-            const detail = (r.stderr || r.stdout || "").trim();
-            throw new Error(`git ls-files failed: ${detail}`);
-        }
-        return r.stdout.split("\0").filter((p) => p.length > 0);
-    }
-    /**
-     * Diff two refs with `--name-status -M -z` and parse the NUL-delimited output
-     * (SPEC §6: the FS→Docmost push direction diffs `main` against
-     * `refs/docmost/last-pushed`). Rename detection is ON (`-M`), so a moved/renamed
-     * file is reported as a single `R` row with both its old and new path instead
-     * of a delete+add pair — that distinction is what lets the push planner tell a
-     * move from a delete+create (SPEC §8 "Move vs delete").
-     *
-     * `-z` makes git emit NUL-delimited RAW UTF-8 records (the Russian wiki has
-     * Cyrillic file names) with NO quoting/escaping. The record shape differs by
-     * status:
-     *   - A/M/D:  `status\0path\0`
-     *   - R/C:    `Rnnn\0oldPath\0newPath\0`  (nnn = similarity score, e.g. `R100`)
-     * We read the RAW stdout (not the trimming `run()` helper, which would mangle
-     * the NUL bytes), split on `\0`, drop the trailing empty entry, and walk the
-     * tokens pulling 1 or 2 path tokens per status. Paths are returned verbatim.
-     */
-    async diffNameStatus(fromRef, toRef) {
-        const r = await this.runRaw([
-            "diff",
-            "--name-status",
-            "-M",
-            "-z",
-            fromRef,
-            toRef,
-        ]);
-        if (r.code !== 0) {
-            const detail = (r.stderr || r.stdout || "").trim();
-            throw new Error(`git diff --name-status failed: ${detail}`);
-        }
-        // Tokens alternate: <status> <path...> <status> <path...> ... With `-z`,
-        // each token (status code AND each path) is its own NUL-delimited field.
-        const tokens = r.stdout.split("\0").filter((t) => t.length > 0);
-        const entries = [];
-        let i = 0;
-        while (i < tokens.length) {
-            const raw = tokens[i++];
-            // The status token is e.g. `A`, `M`, `D`, or `R100` / `C075`. The leading
-            // letter is the change kind; any trailing digits are the similarity score.
-            const letter = raw[0];
-            if (letter === "R" || letter === "C") {
-                const score = Number.parseInt(raw.slice(1), 10);
-                const oldPath = tokens[i++];
-                const path = tokens[i++];
-                if (oldPath === undefined || path === undefined)
-                    break; // malformed tail
-                entries.push({
-                    status: letter,
-                    path,
-                    oldPath,
-                    ...(Number.isFinite(score) ? { score } : {}),
-                });
-            }
-            else if (letter === "A" || letter === "M" || letter === "D") {
-                const path = tokens[i++];
-                if (path === undefined)
-                    break; // malformed tail
-                entries.push({ status: letter, path });
-            }
-            else {
-                // Unknown/other status (e.g. T type-change, U unmerged) — consume one
-                // path token defensively so the walk stays aligned, but do not emit it
-                // (the push planner only handles A/M/D/R/C).
-                i++;
-            }
-        }
-        return entries;
-    }
-    /**
-     * Resolve a ref/commit-ish to its full SHA, or `null` if it does not exist.
-     * `rev-parse --verify --quiet` exits non-zero (and prints nothing) for an
-     * unknown ref, so a non-zero exit maps cleanly to `null`. Used to read
-     * `refs/docmost/last-pushed` (SPEC §5) — which is absent before the first push.
-     */
-    async revParse(ref) {
-        const r = await this.runRaw(["rev-parse", "--verify", "--quiet", ref]);
-        if (r.code !== 0)
-            return null;
-        const sha = r.stdout.trim();
-        return sha.length > 0 ? sha : null;
-    }
-    /**
-     * Read a ref to its SHA, or `null` if unset. Thin alias over `revParse`,
-     * named for the push direction's marker `refs/docmost/last-pushed` (SPEC §5:
-     * "что из `main` уже отражено в Docmost").
-     */
-    async readRef(ref) {
-        return this.revParse(ref);
-    }
-    /**
-     * Point `ref` at `target` (`git update-ref <ref> <target>`). Used to advance
-     * `refs/docmost/last-pushed` to the just-pushed `main` commit after a push
-     * (SPEC §6 step 3 / §5). `target` may be a SHA or any commit-ish git accepts.
-     */
-    async updateRef(ref, target) {
-        await this.run(["update-ref", ref, target]);
-    }
-    /**
-     * Fast-forward `branch` to `toCommit` — but ONLY if it is a TRUE fast-forward,
-     * i.e. the current `branch` tip is an ancestor of `toCommit` (verified via
-     * `git merge-base --is-ancestor <branch> <toCommit>`). Used to advance the
-     * `docmost` mirror branch after a clean push (SPEC §6 step 3 / §10): once a
-     * push succeeds, Docmost already contains the pushed `main` content, so the
-     * mirror must reflect it — otherwise the NEXT pull would diff our own write
-     * back and re-pull it (loop-guard).
-     *
-     * SAFETY — never force, never clobber divergent history:
-     *   - If `branch` IS an ancestor of `toCommit`, advance it with
-     *     `git update-ref refs/heads/<branch> <toCommit>`. The `docmost` branch is
-     *     NOT checked out during a push (push works on `main`), so updating the ref
-     *     directly is safe and avoids any working-tree touch.
-     *   - If `branch` is NOT an ancestor (divergent / would-be non-fast-forward),
-     *     do NOT move it — return `{ ok: false, reason: 'not-fast-forward' }` and
-     *     let the caller log it. We must never overwrite a `docmost` history that
-     *     has commits the push base does not contain.
-     *
-     * Returns `{ ok: true }` when the branch was advanced (or already at
-     * `toCommit`, a degenerate fast-forward), `{ ok: false, reason }` otherwise.
-     * A missing `branch` or `toCommit` also yields `{ ok: false }` with a reason.
-     */
-    async fastForwardBranch(branch, toCommit) {
-        const branchRef = `refs/heads/${branch}`;
-        // Resolve both endpoints first so a missing ref is a clean refusal, not a
-        // confusing `merge-base` failure.
-        const branchSha = await this.revParse(branchRef);
-        if (branchSha === null) {
-            return { ok: false, reason: `branch ${branch} does not exist` };
-        }
-        const targetSha = await this.revParse(toCommit);
-        if (targetSha === null) {
-            return { ok: false, reason: `target ${toCommit} does not resolve` };
-        }
-        // Already at the target -> a no-op fast-forward (still ok).
-        if (branchSha === targetSha)
-            return { ok: true };
-        // `merge-base --is-ancestor A B` exits 0 iff A is an ancestor of B. Only a
-        // true ancestor is a fast-forward; anything else is divergent and refused.
-        const ancestor = await this.runRaw([
-            "merge-base",
-            "--is-ancestor",
-            branchSha,
-            targetSha,
-        ]);
-        if (ancestor.code !== 0) {
-            return { ok: false, reason: "not-fast-forward" };
-        }
-        // Safe to advance: the branch is not checked out during push, so a direct
-        // ref update avoids a checkout/working-tree touch.
-        await this.updateRef(branchRef, targetSha);
-        return { ok: true };
-    }
-    /**
-     * Read a file's content at a specific ref (`git show <ref>:<path>`), or `null`
-     * if the path does not exist there. Used by the push direction to read the
-     * PRE-IMAGE of a DELETED file (e.g. at `refs/docmost/last-pushed`) so its
-     * `docmost:meta` — and therefore its `pageId` — can be recovered to translate
-     * the deletion into a `delete_page` (SPEC §6/§8: only TRACKED files, i.e. ones
-     * that had a pageId, are deleted in Docmost). A non-zero exit (path absent at
-     * that ref) maps to `null` rather than throwing.
-     */
-    async showFileAtRef(ref, path) {
-        // `git show <ref>:<path>` requires the path relative to the repo root; pass
-        // it verbatim (forward-slash, matching `listTrackedFiles` / diff output).
-        const r = await this.runRaw(["show", `${ref}:${path}`]);
-        if (r.code !== 0)
-            return null;
-        return r.stdout;
-    }
-}
-/**
- * Build the environment for a vault git invocation (SPEC §12 cwd-isolation).
- * Used by the single `runRaw` primitive every git command flows through, so
- * these pins apply uniformly (including the `git --version` preflight).
- *
- * cwd-isolation is this module's central safety guarantee: every git command
- * MUST operate on the vault repo at `cwd: vaultPath` and nothing else. An
- * inherited `GIT_DIR` / `GIT_WORK_TREE` in `process.env` would silently
- * redirect the operation away from `cwd` (e.g. to the source repo or another
- * checkout), defeating that guarantee. So we always strip them, regardless of
- * whatever else the caller adds (author/committer identity, etc.).
- *
- * Exported for unit testing.
- */
-export function vaultGitEnv(extra) {
-    const env = {
-        ...process.env,
-        // Locale-independent output (defense in depth). We never parse localized
-        // prose, but pinning the locale prevents a future regression where some
-        // git message we DO key on is translated by an inherited LC_ALL/LANG.
-        LC_ALL: "C",
-        LANG: "C",
-        // Never page (we already pass --no-pager, but a stray GIT_PAGER could still
-        // bite) and never block on an interactive prompt (e.g. credentials) — the
-        // daemon runs unattended and must not hang.
-        GIT_PAGER: "cat",
-        GIT_TERMINAL_PROMPT: "0",
-        ...extra,
-    };
-    delete env.GIT_DIR;
-    delete env.GIT_WORK_TREE;
-    return env;
-}
-/**
- * Build a commit message body with trailer lines appended (SPEC §7.3). The
- * trailers are separated from the subject by a blank line so `git interpret-
- * trailers` / `git log --format=%(trailers)` parse them as trailers.
- * Exported for unit testing.
- */
-export function buildCommitMessage(subject, trailers) {
-    if (!trailers || trailers.length === 0)
-        return subject;
-    return `${subject}\n\n${trailers.join("\n")}`;
-}

packages/git-sync/build/engine/layout.d.ts

@@ -1,44 +0,0 @@
-/**
- * Pure page-tree -> vault path mapping (SPEC §12).
- *
- * Given the flat list of page nodes for a space (as returned by
- * `listAllSpacePages`), compute for every page a deterministic, collision-free
- * destination: a folder path (root -> leaf ancestors) plus a file stem (the
- * page's own name, no extension). This module is intentionally PURE and
- * dependency-free apart from the sanitization helpers, so the whole tree ->
- * path logic is unit-testable without any I/O. The names are COSMETIC; identity
- * lives in each file's meta block (pageId / slugId).
- */
-/** Flat page node as returned by `listAllSpacePages` (no content). */
-export interface PageNode {
-    id: string;
-    title?: string;
-    slugId?: string;
-    parentPageId?: string | null;
-    hasChildren?: boolean;
-}
-/** A page's resolved vault destination: folder path + file stem. */
-export interface VaultEntry {
-    /** Folder path, root -> leaf (the page's ancestors). Empty for a root page. */
-    segments: string[];
-    /** The page's own file name without extension. */
-    stem: string;
-}
-/**
- * Build the full vault layout for a space.
- *
- * Returns a Map keyed by pageId -> `{ segments, stem }`. The result is
- * deterministic for a given input and guarantees every full destination path
- * (`[...segments, stem].join("/")`) is unique, so no page can silently overwrite
- * another.
- *
- * Disambiguation is layered:
- *   1. Sibling collisions (same sanitized title under the same parent) are
- *      resolved with a stable ` ~<slugId>` suffix (the suffix is itself
- *      sanitized, since slugId/id is untrusted data that must never inject a
- *      path separator).
- *   2. A final full-path pass catches residual collisions that sibling-scoping
- *      cannot see — e.g. two pages whose parents are BOTH outside the input set
- *      both bucket at the root with `segments: []`.
- */
-export declare function buildVaultLayout(pages: PageNode[]): Map<string, VaultEntry>;